Turn destination codes into places travelers recognize. Retrieve city names, country and state details, coordinates and time zones, or download the directory to power destination search in your travel product.
Send code=NYC to retrieve New York City and its reference data. Replace YOUR_API_KEY with your assigned key.
Retrieve geographic and demographic details for specific cities or export the complete cities database in JSON, XML, or CSV formats.
EndpointGET https://content.airhex.com/api/v3.7.10/cities/
curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
--data-urlencode 'apikey=YOUR_API_KEY' \
--data-urlencode 'code=NYC'[
{
"airhex_id": "5333",
"updated": "2025-10-23 05:47:19",
"code": "NYC",
"country_code": "US",
"name": "New York City",
"state_short": "NY",
"state_full": "New York",
"latitude": "40.7143528",
"longitude": "-74.0059731",
"city_photo": "https:\/\/content.airhex.com\/content\/city_photos\/5333.jpg",
"timezone": "America\/New_York",
"gmt": "-4",
"population": "8992908",
"popularity": "39128143"
}
]Full JSON response. Scroll within the panel to explore all fields. Expanded JSON and XML examples are available below.
Provide at least one of code, country_code, name, or dump=1. Setting dump=1 overrides the other lookup parameters.
| Parameter | Required | Value | Type | Default | Description |
|---|---|---|---|---|---|
| apikey | Required | Any | String | none | Your assigned API key. Get a free test API key. |
| code | Conditional | AAA-ZZZ | String | none | Three-letter IATA city code |
| country_code | Conditional | AA-ZZ | String | none | Two-letter ISO 3166-1 Alpha-2 country code |
| name | Conditional | Any | String | none | City name or partial substring for search matching |
| dump | Conditional | 0 or 1 | Integer | 0 | Set to 1 to export the complete database (ignores other conditional parameters above) |
| response_type | Optional | JSON or XML or CSV | String | JSON | Response format: JSON, XML, or CSV (CSV initiates file download) |
Retrieve city identities, geographic details, destination images and demographic fields. Linked fields open focused guides with examples and integration advice.
| Field | Example | Description |
|---|---|---|
| airhex_id | 5333 | Unique permanent record identifier |
| updated | 2025-10-23 05:47:19 | Date and time the record was last updated |
| code | NYC | City’s three-letter IATA code |
| country_code | US | ISO 3166-1 Alpha-2 country code |
| name | New York City | City’s name |
| state_short | NY | State/province abbreviation (US, CA, AU cities only) |
| state_full | New York | Full state/province name (US, CA, AU cities only) |
| latitude | 40.7143528 | Geographic latitude of the city center |
| longitude | -74.0059731 | Geographic longitude of the city center |
| city_photo | https://content.airhex.com/content/city_photos/5333.jpg | Licensed, commercially usable city image URL |
| timezone | America/New_York | City's timezone identifier |
| gmt | -4 | City's time offset from GMT |
| population | 8992908 | Population count of the city |
| popularity | 39128143 | Relative popularity index (higher value indicates higher destination popularity) |
These examples show the complete New York City record in JSON and XML. Use response_type to select the output format.
[
{
"airhex_id": "5333",
"updated": "2025-10-23 05:47:19",
"code": "NYC",
"country_code": "US",
"name": "New York City",
"state_short": "NY",
"state_full": "New York",
"latitude": "40.7143528",
"longitude": "-74.0059731",
"city_photo": "https:\/\/content.airhex.com\/content\/city_photos\/5333.jpg",
"timezone": "America\/New_York",
"gmt": "-4",
"population": "8992908",
"popularity": "39128143"
}
]<?xml version="1.0" encoding="UTF-8"?>
<cities>
<city>
<airhex_id>5333</airhex_id>
<updated>2025-10-23 05:47:19</updated>
<code>NYC</code>
<country_code>US</country_code>
<name>New York City</name>
<state_short>NY</state_short>
<state_full>New York</state_full>
<latitude>40.7143528</latitude>
<longitude>-74.0059731</longitude>
<city_photo>https://content.airhex.com/content/city_photos/5333.jpg</city_photo>
<timezone>America/New_York</timezone>
<gmt>-4</gmt>
<population>8992908</population>
<popularity>39128143</popularity>
</city>
</cities>
Export the city dataset for a local destination selector. Retain airhex_id and updated alongside codes, names and location details.
curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
--data-urlencode 'apikey=YOUR_API_KEY' \
--data-urlencode 'dump=1' \
--data-urlencode 'response_type=CSV' \
--output cities.csvUse a two-letter country code to build a country-specific city list.
curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
--data-urlencode 'apikey=YOUR_API_KEY' \
--data-urlencode 'country_code=US'Partial name searches may return multiple cities. Compare country and available state details before selecting a destination.
curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
--data-urlencode 'apikey=YOUR_API_KEY' \
--data-urlencode 'name=New York'Use city names, country context and popularity values to order suggestions in your own destination search.
Use available licensed city photos to illustrate destination cards and guides.
Support city-level searches alongside individual airports, with clear labels for each option.
Yes. Use popularity as a relative ordering signal in your application; higher values indicate higher destination popularity. Combine it with your own text matching and location context. The field does not provide personalized recommendations or a complete autocomplete algorithm.
The city_photo field provides available licensed destination-image URLs for commercial use within your GEO Essentials license. Coverage is not universal: check for a populated URL and provide a fallback for cities without an image. Use the images within the usage rights agreed for your product.
Airhex aggregates and verifies geographic data from multiple sources and reviews it daily. Retain airhex_id and updated when importing city records, and refresh your local directory periodically. Daily review does not mean every city field changes each day.
Yes, with an appropriate GEO Essentials license. Use dump=1 and response_type to export JSON, XML or CSV. Retain airhex_id and updated and periodically refresh your local records.
No. Use the Airports API with city_code to retrieve associated airport records. Confirm how your flight supplier handles city-level searches before offering an “all airports” option.
Name searches support partial matching. Compare name, country_code and available state fields rather than automatically selecting the first result.
state_short and state_full apply to cities in the United States, Canada and Australia. Handle empty values and use city name and country as the basic display context.
Use code, such as code=NYC. The Cities API does not use iata as its lookup parameter.
Use timezone with the relevant timestamp and current time zone rules. Do not treat the gmt offset as a fixed offset for every date.
The directory provides destination reference data. It does not establish route coverage, fares or availability; obtain those from your booking supplier.
Build clearer destination suggestions and richer city displays with city codes, popularity data and available licensed photos.