Countries Data Reference

Countries GEO Data API — Alpha-2 and Alpha-3 codes of 250 countries. Country data fields returned as nested objects in every airport response.

API Reference

Full API Reference Airlines API Airports API Airline Logos API Cities Data

Authentication

All API requests require a valid API key. Pass it as a Bearer token in the Authorization header, or via the X-API-Key header. Keys are delivered immediately after subscribing.

Don't have an API key yet? Get started — you'll have a key in minutes.

# Bearer token (recommended)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.airhex.com/v1/airports?iata=JFK"

# Alternative: X-API-Key header
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.airhex.com/v1/airports?iata=JFK"

Base URL
https://api.airhex.com/v1

Country data is part of the Airports API response.
Each airport object returned by GET /airports includes a nested country object with the fields listed below.

Object Nested country object

Every airport response includes a nested country object. These are the available fields, filtered by your plan tier.

Field	Type	Plan	Description
`code2`	string	All	ISO 3166-1 alpha-2 code (e.g. "GB")
`code3`	string	All	ISO 3166-1 alpha-3 code (e.g. "GBR")
`name`	string	All	Country name (e.g. "United Kingdom")
`iso`	string	Growth Enterprise	ISO 3166-1 numeric code (e.g. "826")
`capital_code`	string	Growth Enterprise	IATA code of the capital city (e.g. "LON")
`currency_code`	string	Growth Enterprise	ISO 4217 currency code (e.g. "GBP")
`region`	string	Growth Enterprise	Geographic region (e.g. "Europe")
`continent_code`	string	Growth Enterprise	Continent code (e.g. "EU")
`population`	string	Growth Enterprise	Country population
`phone_code`	string	Growth Enterprise	International dialing code (e.g. "44")

Response Example

{
  "code2": "US",
  "code3": "USA",
  "name": "United States",
  "iso": "840",
  "capital_code": "WAS",
  "currency_code": "USD",
  "region": "North America",
  "continent_code": "NA",
  "population": "310232863",
  "phone_code": "+1"
}

Error Codes

Code	Description
`400`	Bad request — invalid query parameters (e.g. name or city search under 2 characters)
`401`	Unauthorized — missing or invalid API key. Check your Authorization header.
`403`	Forbidden — your plan does not permit this operation (e.g. bulk listing on Starter, inactive API key)
`429`	Too many requests — per-second rate limit exceeded. Back off and retry.
`503`	Service temporarily unavailable. Retry after a few seconds.

Rate Limits

All plans include unlimited monthly requests with fair-use rate limiting enforced per second. Standard rate headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset) are included in every response. Responses also include Cache-Control headers — caching responses locally is recommended to stay well within limits.

Legacy API — This documents the previous AirHex API (content.airhex.com). It remains operational for existing integrations but new projects should use the Current API.

GET https://content.airhex.com/api/v3.3/countries

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

Example Request:

https://content.airhex.com/api/v3.3/countries?apikey=YOUR_API_KEY&code2=US

At least one query parameter (code2, code3, iso, name, or dump) is required.

Request Parameters

Name	Required	Range	Type	Default	Description
`apikey`	Yes	Any	String	none	Your assigned API key
`code2`	No	AA-ZZ	String	none	Two-letter ISO 3166-1 Alpha-2 country code
`code3`	No	AAA-ZZZ	String	none	Three-letter ISO 3166-1 Alpha-3 country code
`iso`	No	Any	Int	none	Numeric ISO 3166-1 country code
`name`	No	Any	String	none	Country name or partial substring for matching
`dump`	No	0 or 1	Integer	0	Set to 1 to export the complete database (ignores other parameters)
`response_type`	No	JSON, XML, CSV	String	JSON	Response format: JSON, XML, or CSV (CSV initiates file download)

Response Fields

Field	Example	Description
`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
`continent_code`	NA	Two-letter continent code
`population`	310232863	Country's population count
`phone_code`	+1	International country dialing code

Response Example (JSON)

[
    {
        "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"
    }
]

Ready to integrate airport & country data?

Get your API key and start querying airport & country data in minutes.

Get Started

Trusted by leading aviation & travel companies