Countries Database and Codes API

Keep country information consistent across your travel product. Match country identifiers to names and geographic details, or download the directory for destination filters, forms and reporting.

Get test API keyView example
  • Alpha-2, Alpha-3 and numeric ISO lookup
  • Individual records or bulk export
  • JSON, XML and CSV

Look up a country by its code

Send code2=US to retrieve the United States and its reference data. Replace YOUR_API_KEY with your assigned key.

API Endpoint Description

This endpoint retrieves specific country details or dumps the entire countries database with output in JSON, XML or CSV file

Endpoint
GET https://content.airhex.com/api/v3.7.10/countries/

Request · cURL

curl --get 'https://content.airhex.com/api/v3.7.10/countries/' \
  --data-urlencode 'apikey=YOUR_API_KEY' \
  --data-urlencode 'code2=US'

Response · JSON

[
    {
        "airhex_id": "735",
        "updated": "2026-06-16 14:48:41",
        "iso": "840",
        "code2": "US",
        "code3": "USA",
        "name": "United States",
        "capital_code": "WAS",
        "currency_code": "USD",
        "region": "North America",
        "continent_code": "NA",
        "population": "310232863",
        "phone_code": "+1"
    }
]

Full JSON response. Scroll within the panel to explore all fields. Expanded JSON and XML examples are available below.

Request parameters

Provide at least one of code2, code3, iso, 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.
code2 Conditional AA-ZZ String none Two-letter ISO 3166-1 Alpha-2 country code
code3 Conditional AAA-ZZZ String none Three-letter ISO 3166-1 Alpha-3 country code
iso Conditional Any Int none Numeric ISO 3166-1 country code
name Conditional Any String none Country name or partial substring for 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)

Response fields

Retrieve country identifiers, names and geographic reference details from the same record. Use the documented fields to keep country mappings consistent across your systems.

Field Example Description
airhex_id 735 Unique permanent record identifier
updated 2026-06-16 14:48:41 Date and time the record was last updated
iso 840 ISO 3166-1 numeric country code
code2 US ISO 3166-1 Alpha-2 two-letter country code
code3 USA ISO 3166-1 Alpha-3 three-letter country code
name United States Country name
capital_code WAS Three-letter IATA code for the country's capital city
currency_code USD Three-letter ISO currency code
region North America Geographical region of the country
continent_code NA Two-letter continent code
population 310232863 Country’s population count
phone_code +1 International country dialing code

Full response examples

These examples show the complete the United States record in JSON and XML. Use response_type to select the output format.

Response · JSON

[
    {
        "airhex_id": "735",
        "updated": "2026-06-16 14:48:41",
        "iso": "840",
        "code2": "US",
        "code3": "USA",
        "name": "United States",
        "capital_code": "WAS",
        "currency_code": "USD",
        "region": "North America",
        "continent_code": "NA",
        "population": "310232863",
        "phone_code": "+1"
    }
]

Response · XML

<?xml version="1.0" encoding="UTF-8"?>
<countries>
 <country>
  <airhex_id>735</airhex_id>
  <updated>2026-06-16 14:48:41</updated>
  <iso>840</iso>
  <code2>US</code2>
  <code3>USA</code3>
  <name>United States</name>
  <capital_code>WAS</capital_code>
  <currency_code>USD</currency_code>
  <region>North America</region>
  <continent_code>NA</continent_code>
  <population>310232863</population>
  <phone_code>+1</phone_code>
 </country>
</countries>

Common implementation tasks

Download your country directory

Export countries as CSV for your local forms and destination filters. Retain airhex_id and updated when importing records.

curl --get 'https://content.airhex.com/api/v3.7.10/countries/' \
  --data-urlencode 'apikey=YOUR_API_KEY' \
  --data-urlencode 'dump=1' \
  --data-urlencode 'response_type=CSV' \
  --output countries.csv

Match a three-letter country code

Use code3 when a supplier sends Alpha-3 identifiers, then read the corresponding code2 value from the response.

curl --get 'https://content.airhex.com/api/v3.7.10/countries/' \
  --data-urlencode 'apikey=YOUR_API_KEY' \
  --data-urlencode 'code3=USA'

Search by country name

Use name for a full or partial name search. Review the returned identities before choosing a match.

curl --get 'https://content.airhex.com/api/v3.7.10/countries/' \
  --data-urlencode 'apikey=YOUR_API_KEY' \
  --data-urlencode 'name=United States'

What you can build

Build consistent country selectors

Use recognizable country names and standardized identifiers across forms and destination filters.

Add useful destination context

Include currency and calling-code information in country guides and travel-planning screens.

Connect geographic data across your product

Match countries with city, airport and supplier records for consistent filtering and reporting.

Frequently asked questions

How does country data connect with airports and cities?

The Cities and Airports APIs return country_code as a two-letter ISO identifier. Match that value to code2 in the Countries API to retrieve country names and other reference details. Retain each record’s own airhex_id for identity.

Which country details can I show in my travel product?

Alongside country names and ISO identifiers, the response includes currency_code, phone_code, capital_code, region, continent_code and population. Use these for destination context and geographic grouping. Currency codes are reference values, not exchange rates; capital_code is an identifier rather than a display name.

How is country information kept up to date?

Airhex aggregates and verifies geographic data from multiple sources and reviews it daily. Retain airhex_id and updated and refresh your local directory periodically. Daily review does not mean every country field changes each day.

Which country-code formats can I look up?

Use code2 for two-letter ISO Alpha-2 codes, code3 for three-letter Alpha-3 codes, or iso for numeric ISO country codes. The response includes the corresponding identifiers for the country.

Can I find a country by name?

Yes. The name parameter supports partial matching. Compare the returned country names and codes before selecting a record.

Can I download and store the country directory?

Yes, with an appropriate GEO Essentials license. Set dump=1 and select JSON, XML or CSV with response_type. Retain airhex_id and updated and refresh your local copy periodically.

Does this API provide visa or entry requirements?

No. It provides country reference data. Obtain current visa rules, entry requirements and travel restrictions from an appropriate specialist or official source.

Bring consistent country information into every travel journey

Connect destination filters, traveler forms and country guides with maintained country codes and useful destination details.

Get test API keyGet a quote →