Getting Started

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.

---

Authentication

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

Your API keys carry many privileges, do not share your secret API keys in publicly accessible areas such as public GitHub repos.

In order to use our services you must provided your API key with each request using one of these two options:

As a Request Header

$ curl "https://api.checkwx.com/station/KJFK" -H "X-API-Key: "

As a Querysting parameter

$ curl "https://api.checkwx.com/station/KJFK?x-api-key="

---

Endpoints

The CheckWX API is organized around REST. Our API has predictable resource-oriented URLs, accepts GET requests, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

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.

• All requests should be made using HTTPS.
• All request and response bodies, including errors, are encoded in JSON.
• Standard url request for GET requests.
• All parameters are required unless otherwise specified.

Each endpoint in this documentation is described using several parts:

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

All API endpoints are relative to the Base URL:

• For example, assuming the base URL of https://api.checkwx.com, the station endpoint refers to https://api.checkwx.com/station.

---

API Daily 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 following example table:

To illustrate this concept, see the examples below:

Example Requests	API Calls
https://api.checkwx.com/station/KPIE https://api.checkwx.com/station/KSPG https://api.checkwx.com/stationKLAL	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 "429 Too Many Requests" response status code.

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 loads on our system:

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

---

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

Any non-200 HTTP response code can be considered an error.

All of our API endpoints return the following JSON structure:

{
  "data": [ ],
  "results": 0
}

JSON Keys

Key	Type	Description
data	Array	An array of one or more json objects
results	Integer	The number of results returned

---

JSON Example

{
  "data": [
    "KJRB 012356Z AUTO VRB03KT 10SM CLR 02/M11 A3027 RMK AO2 SLP251 60000 T00221111 10050 20022 53014 FZRANO",
    "KNYC 012351Z AUTO VRB04KT 10SM CLR 01/M14 A3028 RMK AO2 SLP245 T00111139 10033 20011 53015",
    "KLGA 012351Z 32013KT 10SM FEW250 02/M14 A3026 RMK AO2 SLP246 T00171139 10033 20017 53015",
    "KEWR 012351Z 34009KT 10SM FEW250 02/M14 A3026 RMK AO2 SLP247 T00221144 10044 20022 53014",
    "KTEB 012351Z 35007KT 10SM CLR 01/M13 A3026 RMK AO2 SLP248 T00061133 10033 20000 53019"
  ],
  "results": 5
}

---

Error Response

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

If you receive a status code in the range of 400 to 500, 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
403	Forbidden	Access to request or endpoint denied
404	Not Found	The resource or endpoint does not exist
422	Validation error	A Data validation error occurred
429	Too Many Requests	Successful request and response
500	Internal Server Error	An error occurred with our API service

{
  "error": "Unauthorized - Invalid API Key"
}

---

Examples

Each endpoint in this document has an example using CURL for simplicity.

Additionally we have basic examples for 30 different programming languages.

Example Parameter	Actual Usage
https://api.checkwx.com/station/:icao	https://api.checkwx.com/station/KJFK

There are also some good examples on Github for working with our API, such as api.checkwx.com-examples.

---

OpenAPI and Swagger

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.

We also offer interactive OpenAPI documentation with Swagger which allows you to test your API calls directly from your browser.

View our Swagger.

---

Redoc

Redoc is an open-source tool for generating documentation from OpenAPI (fka Swagger) definitions

View our Redoc.