Turn city codes into destinations travelers recognize. Match three-letter IATA city codes to city names, countries and available state details, or download the directory to power destination search in your travel product.
Pass NYC in the code parameter of the Cities API to retrieve New York City. Replace YOUR_API_KEY with your assigned key.
curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
--data-urlencode 'apikey=YOUR_API_KEY' \
--data-urlencode 'code=NYC'[
{
"airhex_id": "5333",
"code": "NYC",
"country_code": "US",
"name": "New York City",
"state_short": "NY",
"state_full": "New York",
...
}
]Abbreviated response. The ellipsis (…) represents additional city fields omitted here and is not part of the actual JSON response.
View the full Cities API reference →Look up a city code, find destinations by name or country, or export the city directory.
| Parameter | Required | Default | Description |
|---|---|---|---|
apikey |
Yes | None | Your assigned API key. Get a free test API key. |
code |
Conditional | None | Three-letter IATA city code, such as NYC. |
country_code |
Conditional | None | Two-letter ISO country code, such as US, to retrieve cities in a country. |
name |
Conditional | None | City name or partial name for search matching. |
dump |
Conditional | 0 | Set to 1 to export the complete database. Overrides the other lookup parameters. |
response_type |
No | JSON | Response format: JSON, XML or CSV. CSV triggers a file download. |
Provide at least one of code, country_code, name, or dump=1. The Cities API uses code, not iata, for a city-code lookup.
View all request parameters →Use the city code to resolve a destination and the accompanying name and location fields to display it clearly. Retain airhex_id when maintaining your local records.
| Field | Type | Example | Description |
|---|---|---|---|
airhex_id |
Identifier | 5333 | Permanent Airhex record identifier for maintaining your local destination directory. |
code |
String | NYC | Three-letter IATA city code for matching destination records. |
country_code |
String | US | Two-letter ISO country code for country labels and destination grouping. |
name |
String | New York City | City name for destination search, booking screens and itineraries. |
state_short |
String | NY | State or province abbreviation, available for US, Canadian and Australian cities. |
state_full |
String | New York | Full state or province name, available for US, Canadian and Australian cities. |
Export the city directory as CSV and build a local search index from codes, names, countries and available state details. Display enough location context to help travelers distinguish cities with similar names.
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 city-codes.csvSearch with name and read code from the returned records. Partial matching can produce several results, so compare country and state details before choosing a destination.
curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
--data-urlencode 'apikey=YOUR_API_KEY' \
--data-urlencode 'name=New York'Pass country_code=US to retrieve city records for the United States. Use their codes and names for a country-specific destination list; flight availability must come from your booking supplier.
curl --get 'https://content.airhex.com/api/v3.7.10/cities/' \
--data-urlencode 'apikey=YOUR_API_KEY' \
--data-urlencode 'country_code=US'After resolving a city, pass its code as city_code to the Airports API. This example requests airports with commercial flights associated with NYC. Keep each airport’s own code and name when displaying airport choices; the Cities API response does not contain an airport list.
curl --get 'https://content.airhex.com/api/v3.7.10/airports/' \
--data-urlencode 'apikey=YOUR_API_KEY' \
--data-urlencode 'city_code=NYC' \
--data-urlencode 'major_only=1'Show city names with country and state context instead of asking travelers to interpret destination codes.
Support city-level destination choices alongside individual airports, using the Cities and Airports APIs to label each option clearly.
Match coded destinations to the same city records across booking tools, customer support and reports.
A city code identifies a destination at city level, while an airport code identifies an individual airport. A city can be associated with multiple airports. Keep the supplier’s location type alongside its code so your application knows whether to look up a city or an airport.
Use code on the Cities API, such as code=NYC. The Airports API uses iata for an individual airport lookup and city_code to find airports associated with a city. These parameter names are specific to their endpoints.
Use the city record to label the destination and the Airports API to retrieve associated airports. Confirm how your flight supplier accepts city-level searches and which airports it includes. City reference data alone does not define a supplier’s search coverage or guarantee a bookable route.
Yes. The name parameter supports partial matching. Compare the returned name, country_code and available state fields instead of automatically selecting the first result. Preserve the selected city code and identity once the user chooses a destination.
Do not treat this directory as a list of every municipality. Build your code lookup from the returned city records, and check that code is populated before creating a code-based mapping. Handle destinations that your application cannot resolve without guessing a code from their names.
The documented state_short and state_full fields apply to cities in the United States, Canada and Australia. Handle empty values for other destinations and use the city name and country code as the basic display context.
Yes, with an appropriate GEO Essentials license. Use dump=1 and choose JSON, XML or CSV with response_type. Retain airhex_id as the permanent record identifier and updated from the full response, and refresh your local directory periodically.
No. The Cities API provides destination reference data. Use your flight supplier for route coverage, schedules, fares and availability; a city appearing in the directory does not establish that a particular journey is available to book.
Build clearer city search and destination choices across your travel product, without maintaining your own IATA city code directory.
Explore the complete city dataset, including IATA city codes, names, countries, state details, coordinates, time zones and destination images. View all request parameters and response fields, with individual lookups, country-based searches and bulk exports in JSON, XML and CSV.