Documentation

Get started

When account access is enabled, sign in and create a key in your account. Key creation reveals the secret once. Store it securely and send it in the Authorization header.

curl 'https://cleapi.com/api/v1/airports?iata=SFO&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

This is an illustrative request. The API explorer sends requests to the current site. A missing database or dataset returns an error.

Endpoints

Search by q and a two-letter country code. Airport search also accepts iata, icao and type. Nearby search requires latitude and longitude; radius_km defaults to 100 and cannot exceed 1,000. Closed airports are excluded unless include_closed=true.

Airport IDs begin with oa:; place IDs begin with gn:. Use IDs returned by search. The OpenAPI contract lists all parameters and response fields.

Responses and pagination

Successful responses contain data and meta. Metadata describes source rights, coverage, retrieval and import dates, release identity and normalization warnings. Missing source values remain null.

Lists default to 20 records, with a maximum limit of 100. Follow meta.pagination.nextOffset using offset. Pass the returned meta.dataset.releaseId as release_id to keep list pages on the same release. A null next offset ends the list.

Usage and limits

A successful API call uses one request from your account's UTC calendar-month allowance. Failed calls release that reservation. Attempts still count toward the minute limit. All keys on an account share its limits.

Calls stop at the included allowance. Automatic overage charges are disabled. Check X-Quota-Limit, X-Quota-Remaining and X-Quota-Period; rate-limit responses include Retry-After. Your account shows the configured allowance. Paid checkout is unavailable until a billing provider and prices are configured.

Every new call may carry a unique X-Request-Id. Reusing an accepted ID returns 409. Authenticated responses use private, no-store caching.

Sources and attribution

OurAirports supplies public-domain airport data. GeoNames supplies the cities500 settlement collection and reference files under CC BY 4.0. Preserve required GeoNames credit, license links and notices of changes when reusing that data.

Places covers cities500 settlements, not every geographic feature or street address. Source data is provided as-is and can be incomplete or inaccurate. An empty quality-warning map records no CleAPI normalization warnings; it does not certify accuracy. Use response dates to assess freshness.

Errors

{
  "error": {
    "code": "DATASET_UNAVAILABLE",
    "message": "This dataset has not been imported yet.",
    "requestId": "request-id"
  }
}

Illustrative error structure.