Introduction

This document is intended for users who want to write applications that interact with our aviation weather data API.

It explains basic concepts of the API itself and provides an overview of the different functions that our API supports.

 

Getting Started

This documentation is structured first by a group of related functionality: Station, METAR, TAF, etc., and then by endpoint. Endpoints are a specific method within that API that performs one action and is located at a specific URL.

  • Our API is organized around REST
  • All requests should be made over SSL
  • All request and response bodies, including errors, are encoded in JSON by default

Each endpoint in this documentation is described using several parts:

  • Base URL https://api.checkwx.com/
  • API Endpoint
  • Header Parameters
  • URL Parameters
  • Querystring Parameters
 

Authentication

All API endpoints require an API key which is unique for each user. Your specific API key can be found on your Account Settings page.

In order to use our services you must provided your API key as a Header Parameter with each request as shown in our examples.

If you are currently logged into our website, we have already included your API key in the examples. Otherwise just replace YOUR_API_KEY with your actual API key.

 

JSON Response

JSON (JavaScript Object Notation) is a simple machine-readable data-interchange format that provides a text representation of arbitrary data structures. All of our API response bodies consist of a UTF-8-encoded, JSON-formatted object, including errors.

You can familiarize yourself with the core concepts of the JSON data format at json.org .
 

JSON Pretty Print

Normally a JSON formatted response data is compressed in a single line standard format. However for human readability, you can specify a Querysting parameter which will return the JSON with indentation, line wraps and spacing. This is especially useful when viewing the response JSON using CURL on the commandline.

Querystring Parameters

Parameter Description Example
pretty=1 Pretty print JSON response. https://api.checkwx.com/station/kjfk?pretty=1
 

API Limits

All of our API Plans have different levels of daily request limits. Each API call you make to our services counts as one request, regardless of the number of parameters.

To illustrate this concept, see the examples below:

Example Requests Number of API Calls
https://api.checkwx/com/station/KPIE
https://api.checkwx/com/station/KSPG
https://api.checkwx/com/station/KLAL
3
https://api.checkwx/com/station/KPIE,KSPG,KLAL 1

Should you exceed your daily request limit, the API service will block your incoming requests and return a "402 : Over Quota" response.

The daily rate limit counter will reset to zero at 00:00 UTC.

To prevent exceeding your request limit you should consider caching the responses:

  • METAR and TAF requests should be requested and then cached for at least 15 minutes
  • STATION requests should be requested and then cached for at least 24 hours

To improve connections and experiences for all our users, we block some accounts when we see suspicious activity or other overloads on our system:

  • Creating multiple API accounts to circumvent API limits
  • Polling aggressively instead of caching responses
  • Making API calls with a high concurrency

Users that excessively or persistently exceed their rate limits may have their accounts disabled.

 

Examples

Each endpoint in this document has an example using CURL. Additionally we have basic examples for:  Javascript, JQuery, Node.js, PHP, Python and Ruby.

There are also some good examples on Github for working with our API.   One recommended repo is api.checkwx.com-examples.

  • If you are currently logged into our website, we have already included your API key in the examples.
  • If you are not logged in, just replace YOUR_API_KEY with your actual API key when copying an example.
  • In all of our endpoint descriptions, URL Parameters are displayed as :paramter.
  • Replace the parameter with the actual data value as shown below:
Example Parameter Actual Usage
https://api.checkwx.com/station/:icao https://api.checkwx.com/station/KJFK
 

.NET Wrapper

Nathanael Nordentoft has written a public .NET/C# wrapper

The wrapper is written to give users three ways of communicating with our API:

  • The RAW JSON services which will deliver the raw JSON response and HTTP status code from the API
  • The RAW XML services which will deliver the raw XML response and HTTP status code from the API
  • The .NET object services which will deserialize and deliver domain objects from the delivered JSON
 

Error Messages

Successful API requests are returned with a status code of 200.

If you receive a status code in the range of 400 to 450, please check the error section in the JSON response data for the exact error message and resolution.

Code Name Description
200 OK Successful request and response
400 Bad Request Malformed parameters or other bad request
401 Unauthorized Your API key is invalid
402 Over quota Over plan quota on this endpoint
403 Forbidden Invalid request
404 Not found The resource or endpoint does not exist
422 Validation error A validation error occurred
50X Internal Server Error An error occurred with our API