{"openapi":"3.1.0","info":{"title":"CleAPI Airports and Places API","version":"1.0.0","description":"One CleAPI customer key for hosted airport and place data. Accounts and keys require a separately authenticated account integration; this API exposes no public account or key issuance endpoint. Subscriptions pay for API hosting, updates, and request processing, not ownership of the source data. OurAirports data is public domain. GeoNames data is CC BY 4.0: preserve source attribution and reuse rights. Only successful responses consume included monthly requests. Failed responses release their reservations; attempts remain rate-limited. No prices or live payment provider have been selected. No automatic overage charges. X-Request-Id is for accounting deduplication, not response caching."},"servers":[{"url":"http://localhost:3000","description":"Local development server (start only when needed)."}],"security":[{"CleAPIKey":[]}],"paths":{"/api/v1/airports":{"get":{"operationId":"searchAirports","summary":"Search airport names and codes","description":"Requires airports:read or data:read. Closed facilities are excluded by default. Codes may be absent; ICAO values are supplied by the source and are separate from GPS and local codes. This data is not suitable for operational navigation. An explicit type=closed filter includes closed facilities.","parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional client request identifier. A repeated accepted ID is rejected with 409, preventing duplicate monthly charges and free replays.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"}},{"name":"q","in":"query","required":false,"description":"Name or identifier search.","schema":{"type":"string","maxLength":128,"minLength":2}},{"name":"country","in":"query","required":false,"description":"Source two-letter country code, usually ISO 3166-1 alpha-2, including source-defined codes such as XK.","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"type","in":"query","required":false,"description":"","schema":{"type":"string","enum":["small_airport","medium_airport","large_airport","heliport","seaplane_base","balloonport","closed"]}},{"name":"include_closed","in":"query","required":false,"description":"","schema":{"type":"boolean","default":false}},{"name":"iata","in":"query","required":false,"description":"","schema":{"type":"string","pattern":"^[A-Za-z0-9]{3}$"}},{"name":"icao","in":"query","required":false,"description":"","schema":{"type":"string","pattern":"^[A-Za-z0-9]{4}$"}},{"name":"limit","in":"query","required":false,"description":"","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","required":false,"description":"","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}},{"name":"release_id","in":"query","required":false,"description":"Optional immutable release to pin pagination. Response metadata includes releaseId.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful API response. Only successful responses consume included monthly requests.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}},"X-Quota-Limit":{"description":"Included monthly API requests for this account.","schema":{"type":"string"}},"X-Quota-Remaining":{"description":"Available requests after this reservation; concurrent requests can change it.","schema":{"type":"string"}},"X-Quota-Period":{"description":"UTC calendar month, YYYY-MM.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Account request-attempt limit per fixed UTC minute.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Remaining request attempts in the current fixed minute.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Fixed minute reset as Unix seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirportSearch"}}}},"400":{"description":"Invalid parameters or request ID. Failed responses do not consume monthly allowance.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked Bearer key.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope, account status, or API service entitlement prevents access.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request ID already accepted or used for a different request. No new monthly charge is reserved.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Account rate or monthly allowance exhausted. No automatic overage charge. Retry-After identifies the next eligible time.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate or monthly allowance resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Database, dataset, or request processing unavailable. There is no fallback demo data.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/airports/nearby":{"get":{"operationId":"nearbyAirports","summary":"Find airports near coordinates","description":"Requires airports:read or data:read. Geodesic PostGIS geography distance in kilometers; nearest airports first.","parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional client request identifier. A repeated accepted ID is rejected with 409, preventing duplicate monthly charges and free replays.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"}},{"name":"latitude","in":"query","required":true,"description":"","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"longitude","in":"query","required":true,"description":"","schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"radius_km","in":"query","required":false,"description":"","schema":{"type":"number","minimum":0.001,"maximum":1000,"default":100}},{"name":"country","in":"query","required":false,"description":"Source two-letter country code, usually ISO 3166-1 alpha-2, including source-defined codes such as XK.","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"type","in":"query","required":false,"description":"","schema":{"type":"string","enum":["small_airport","medium_airport","large_airport","heliport","seaplane_base","balloonport","closed"]}},{"name":"include_closed","in":"query","required":false,"description":"","schema":{"type":"boolean","default":false}},{"name":"limit","in":"query","required":false,"description":"","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","required":false,"description":"","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}},{"name":"release_id","in":"query","required":false,"description":"Optional immutable release to pin pagination. Response metadata includes releaseId.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful API response. Only successful responses consume included monthly requests.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}},"X-Quota-Limit":{"description":"Included monthly API requests for this account.","schema":{"type":"string"}},"X-Quota-Remaining":{"description":"Available requests after this reservation; concurrent requests can change it.","schema":{"type":"string"}},"X-Quota-Period":{"description":"UTC calendar month, YYYY-MM.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Account request-attempt limit per fixed UTC minute.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Remaining request attempts in the current fixed minute.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Fixed minute reset as Unix seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NearbyAirports"}}}},"400":{"description":"Invalid parameters or request ID. Failed responses do not consume monthly allowance.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked Bearer key.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope, account status, or API service entitlement prevents access.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request ID already accepted or used for a different request. No new monthly charge is reserved.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Account rate or monthly allowance exhausted. No automatic overage charge. Retry-After identifies the next eligible time.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate or monthly allowance resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Database, dataset, or request processing unavailable. There is no fallback demo data.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/airports/{id}":{"get":{"operationId":"getAirport","summary":"Read an airport by OurAirports source ID","description":"Requires airports:read or data:read.","parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional client request identifier. A repeated accepted ID is rejected with 409, preventing duplicate monthly charges and free replays.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"}},{"name":"id","in":"path","required":true,"description":"Namespaced source ID, for example oa:2434.","schema":{"type":"string","pattern":"^oa:[1-9][0-9]{0,15}$"}}],"responses":{"200":{"description":"Successful API response. Only successful responses consume included monthly requests.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}},"X-Quota-Limit":{"description":"Included monthly API requests for this account.","schema":{"type":"string"}},"X-Quota-Remaining":{"description":"Available requests after this reservation; concurrent requests can change it.","schema":{"type":"string"}},"X-Quota-Period":{"description":"UTC calendar month, YYYY-MM.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Account request-attempt limit per fixed UTC minute.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Remaining request attempts in the current fixed minute.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Fixed minute reset as Unix seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirportDetail"}}}},"400":{"description":"Invalid parameters or request ID. Failed responses do not consume monthly allowance.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked Bearer key.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope, account status, or API service entitlement prevents access.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The namespaced record ID was not found in the active release.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request ID already accepted or used for a different request. No new monthly charge is reserved.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Account rate or monthly allowance exhausted. No automatic overage charge. Retry-After identifies the next eligible time.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate or monthly allowance resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Database, dataset, or request processing unavailable. There is no fallback demo data.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/places":{"get":{"operationId":"searchPlaces","summary":"Search cities and administrative seats","description":"Requires places:read or data:read. Initial coverage is GeoNames cities500: populated places over 500 inhabitants and administrative seats through PPLA4. It does not include every geographic feature.","parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional client request identifier. A repeated accepted ID is rejected with 409, preventing duplicate monthly charges and free replays.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"}},{"name":"q","in":"query","required":false,"description":"Search place names, ASCII names, and alternate names. Read a gn:{source id} identifier through the place detail route.","schema":{"type":"string","maxLength":128,"minLength":2}},{"name":"country","in":"query","required":false,"description":"Source two-letter country code, usually ISO 3166-1 alpha-2, including source-defined codes such as XK.","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"feature_class","in":"query","required":false,"description":"","schema":{"type":"string","pattern":"^[A-Z]$"}},{"name":"limit","in":"query","required":false,"description":"","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","required":false,"description":"","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}},{"name":"release_id","in":"query","required":false,"description":"Optional immutable release to pin pagination. Response metadata includes releaseId.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful API response. Only successful responses consume included monthly requests.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}},"X-Quota-Limit":{"description":"Included monthly API requests for this account.","schema":{"type":"string"}},"X-Quota-Remaining":{"description":"Available requests after this reservation; concurrent requests can change it.","schema":{"type":"string"}},"X-Quota-Period":{"description":"UTC calendar month, YYYY-MM.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Account request-attempt limit per fixed UTC minute.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Remaining request attempts in the current fixed minute.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Fixed minute reset as Unix seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceSearch"}}}},"400":{"description":"Invalid parameters or request ID. Failed responses do not consume monthly allowance.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked Bearer key.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope, account status, or API service entitlement prevents access.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request ID already accepted or used for a different request. No new monthly charge is reserved.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Account rate or monthly allowance exhausted. No automatic overage charge. Retry-After identifies the next eligible time.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate or monthly allowance resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Database, dataset, or request processing unavailable. There is no fallback demo data.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/places/{id}":{"get":{"operationId":"getPlace","summary":"Read a place by GeoNames source ID","description":"Requires places:read or data:read.","parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional client request identifier. A repeated accepted ID is rejected with 409, preventing duplicate monthly charges and free replays.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"}},{"name":"id","in":"path","required":true,"description":"Namespaced GeoNames source ID.","schema":{"type":"string","pattern":"^gn:[1-9][0-9]{0,15}$"}}],"responses":{"200":{"description":"Successful API response. Only successful responses consume included monthly requests.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}},"X-Quota-Limit":{"description":"Included monthly API requests for this account.","schema":{"type":"string"}},"X-Quota-Remaining":{"description":"Available requests after this reservation; concurrent requests can change it.","schema":{"type":"string"}},"X-Quota-Period":{"description":"UTC calendar month, YYYY-MM.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Account request-attempt limit per fixed UTC minute.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Remaining request attempts in the current fixed minute.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Fixed minute reset as Unix seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceDetail"}}}},"400":{"description":"Invalid parameters or request ID. Failed responses do not consume monthly allowance.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked Bearer key.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope, account status, or API service entitlement prevents access.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The namespaced record ID was not found in the active release.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request ID already accepted or used for a different request. No new monthly charge is reserved.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Account rate or monthly allowance exhausted. No automatic overage charge. Retry-After identifies the next eligible time.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate or monthly allowance resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Database, dataset, or request processing unavailable. There is no fallback demo data.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/metadata":{"get":{"operationId":"getDatasetMetadata","summary":"Read active dataset provenance and service terms","description":"Requires datasets:read or data:read. Returns actual active releases, source files, hashes, retrieval/import times, attribution and coverage. An empty data array means no release has been imported. Daily refresh is a target, not a claim of current freshness.","parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional client request identifier. A repeated accepted ID is rejected with 409, preventing duplicate monthly charges and free replays.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"}}],"responses":{"200":{"description":"Successful API response. Only successful responses consume included monthly requests.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}},"X-Quota-Limit":{"description":"Included monthly API requests for this account.","schema":{"type":"string"}},"X-Quota-Remaining":{"description":"Available requests after this reservation; concurrent requests can change it.","schema":{"type":"string"}},"X-Quota-Period":{"description":"UTC calendar month, YYYY-MM.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Account request-attempt limit per fixed UTC minute.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Remaining request attempts in the current fixed minute.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Fixed minute reset as Unix seconds.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataResponse"}}}},"400":{"description":"Invalid parameters or request ID. Failed responses do not consume monthly allowance.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked Bearer key.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key scope, account status, or API service entitlement prevents access.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request ID already accepted or used for a different request. No new monthly charge is reserved.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Account rate or monthly allowance exhausted. No automatic overage charge. Retry-After identifies the next eligible time.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate or monthly allowance resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Database, dataset, or request processing unavailable. There is no fallback demo data.","headers":{"X-Request-Id":{"description":"Request identifier; pass a unique X-Request-Id for each logical request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"CleAPIKey":{"type":"http","scheme":"bearer","description":"Caller-managed CleAPI key. Never put keys in URLs. data:read permits all first-party dataset read operations; narrower per-dataset scopes are supported."}},"schemas":{"Airport":{"type":"object","properties":{"id":{"type":"string"},"sourceId":{"type":"integer"},"ident":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"elevationFt":{"type":["number","null"]},"continent":{"type":["string","null"]},"countryCode":{"type":"string"},"regionCode":{"type":["string","null"]},"municipality":{"type":["string","null"]},"scheduledService":{"type":"boolean"},"iataCode":{"type":["string","null"]},"icaoCode":{"type":["string","null"]},"gpsCode":{"type":["string","null"]},"localCode":{"type":["string","null"]},"websiteUrl":{"type":["string","null"]},"wikipediaUrl":{"type":["string","null"]},"keywords":{"type":"array","items":{"type":"string"}},"normalizationWarnings":{"type":"array","description":"Optional transformation warnings for this record, such as invalid_website_url or invalid_wikipedia_url. Malformed optional URLs are omitted; this does not certify source accuracy.","items":{"type":"string"}}},"required":["id","sourceId","ident","type","name","latitude","longitude","elevationFt","continent","countryCode","regionCode","municipality","scheduledService","iataCode","icaoCode","gpsCode","localCode","websiteUrl","wikipediaUrl","keywords"],"additionalProperties":false},"NearbyAirport":{"type":"object","properties":{"id":{"type":"string"},"sourceId":{"type":"integer"},"ident":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"elevationFt":{"type":["number","null"]},"continent":{"type":["string","null"]},"countryCode":{"type":"string"},"regionCode":{"type":["string","null"]},"municipality":{"type":["string","null"]},"scheduledService":{"type":"boolean"},"iataCode":{"type":["string","null"]},"icaoCode":{"type":["string","null"]},"gpsCode":{"type":["string","null"]},"localCode":{"type":["string","null"]},"websiteUrl":{"type":["string","null"]},"wikipediaUrl":{"type":["string","null"]},"keywords":{"type":"array","items":{"type":"string"}},"distanceKm":{"type":"number"},"normalizationWarnings":{"type":"array","description":"Optional transformation warnings for this record, such as invalid_website_url or invalid_wikipedia_url. Malformed optional URLs are omitted; this does not certify source accuracy.","items":{"type":"string"}}},"required":["id","sourceId","ident","type","name","latitude","longitude","elevationFt","continent","countryCode","regionCode","municipality","scheduledService","iataCode","icaoCode","gpsCode","localCode","websiteUrl","wikipediaUrl","keywords","distanceKm"],"additionalProperties":false},"Place":{"type":"object","properties":{"id":{"type":"string"},"sourceId":{"type":"integer"},"name":{"type":"string"},"asciiName":{"type":"string"},"alternateNames":{"type":"array","items":{"type":"string"}},"latitude":{"type":"number"},"longitude":{"type":"number"},"featureClass":{"type":"string"},"featureCode":{"type":"string"},"countryCode":{"type":"string"},"countryCodes":{"type":"array","items":{"type":"string"}},"admin1Code":{"type":["string","null"]},"admin2Code":{"type":["string","null"]},"admin3Code":{"type":["string","null"]},"admin4Code":{"type":["string","null"]},"population":{"type":"integer"},"elevationM":{"type":["number","null"]},"dem":{"type":["number","null"]},"timezone":{"type":"string"},"sourceModifiedAt":{"type":"string","format":"date"}},"required":["id","sourceId","name","asciiName","alternateNames","latitude","longitude","featureClass","featureCode","countryCode","countryCodes","admin1Code","admin2Code","admin3Code","admin4Code","population","elevationM","dem","timezone","sourceModifiedAt"],"additionalProperties":false},"DatasetMetadata":{"type":"object","properties":{"dataset":{"type":"string","enum":["airports","places"]},"releaseId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","retired"]},"source":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"license":{"type":"string"},"licenseUrl":{"type":"string"},"attribution":{"type":"string"},"changes":{"type":"string"}},"required":["name","url","license","licenseUrl","attribution","changes"],"additionalProperties":false},"sourceFiles":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"bytes":{"type":"integer"},"fetchedAt":{"type":"string","format":"date-time"},"sourceLastModified":{"type":["string","null"],"format":"date-time"}},"required":["url","sha256","bytes","fetchedAt","sourceLastModified"],"additionalProperties":false}},"retrievedAt":{"type":"string","format":"date-time"},"importedAt":{"type":"string","format":"date-time"},"recordCount":{"type":"integer"},"referenceCount":{"type":"integer"},"coverage":{"type":"string"},"refreshTarget":{"const":"daily"},"lastSourceModifiedAt":{"type":["string","null"],"format":"date-time"},"qualityWarnings":{"type":"object","description":"Counts of normalization warnings in this imported release, including omitted malformed optional URLs. These counts describe CleAPI transformations and do not certify source accuracy or completeness.","additionalProperties":{"type":"integer","minimum":0}}},"required":["dataset","releaseId","status","source","sourceFiles","retrievedAt","importedAt","recordCount","referenceCount","coverage","refreshTarget","lastSourceModifiedAt","qualityWarnings"],"additionalProperties":false},"Pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"returned":{"type":"integer"},"nextOffset":{"type":["integer","null"]}},"required":["limit","offset","returned","nextOffset"],"additionalProperties":false},"AirportSearch":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Airport"}},"meta":{"type":"object","properties":{"dataset":{"$ref":"#/components/schemas/DatasetMetadata"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["dataset","pagination"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false},"AirportDetail":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Airport"},"meta":{"type":"object","properties":{"dataset":{"$ref":"#/components/schemas/DatasetMetadata"}},"required":["dataset"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false},"NearbyAirports":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NearbyAirport"}},"meta":{"type":"object","properties":{"dataset":{"$ref":"#/components/schemas/DatasetMetadata"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["dataset","pagination"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false},"PlaceSearch":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Place"}},"meta":{"type":"object","properties":{"dataset":{"$ref":"#/components/schemas/DatasetMetadata"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["dataset","pagination"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false},"PlaceDetail":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Place"},"meta":{"type":"object","properties":{"dataset":{"$ref":"#/components/schemas/DatasetMetadata"}},"required":["dataset"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["code","message","requestId"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"MetadataResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DatasetMetadata"}},"meta":{"type":"object","properties":{"service":{"type":"object","properties":{"chargeFor":{"type":"string"},"dataRights":{"type":"string"},"overages":{"type":"string"},"period":{"type":"string"}},"required":["chargeFor","dataRights","overages","period"],"additionalProperties":false}},"required":["service"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}