countriesv1 - Aptitude Apps, LLC

The only country data API you’ll ever need.

Countries API provides quick access to accurate information for all countries recognized under ISO 3166. ISO 3166 is the standard published by the International Organization for Standardization (ISO) that defines codes for the names of countries, dependent territories, and special areas of geographical interest. There are currently 249 countries recognized under ISO 3166.

The API provides an extremely detailed data set. Data is continuously monitored for accuracy and updated accordingly.

Detailed

We have the most robust "Country" data set available today. Every country in our set falls within ISO 3166 so you know exactly what you're going to get. The amount of detail available for each country is unmatched anywhere on the web.

Fast

Optimized database and data processing mean you will get your data response extremely fast. No more waiting an unacceptable amount of time for your data response to come back.

Flexibile

We offer an extensive range of endpoints so you can get exactly what you need when you need it. Query string parameters are also available on some endpoints so you can really pinpoint exact data when desired.

Reliable

We have partnered with one of the top cloud providers available for backend services including database and computing power, so you can rest assured that the API is there when you need it.

Documentation

Data

Our extensive data set has everything you need. We provide the most detailed set of country data anywhere on the web. Our set includes:

Field	Description
name	Common, short form country name.
state_name	Official country name.
capital	Object containing name, lat/lon, population and notes for each country capital (some countries have more than one capital).
sovereignty	Identifies whether the country is an independent state or if not, the country which governs it.
iso_3166	Object containing ISO 3166 designations. Includes alpha-2, alpha-3, numeric code and subdivision code.
top_level_domain	Identifies tld indicator as assigned by IANA.
un_geoscheme	Object containing assigned UN geoscheme groupings. Includes region, subregion, and sub-subregion (if applicable).
area	Object containing total area, land area and water area in square miles and square kilometers. Water percentage is also included.
population	Total country population.
demonyms	A list of names used to describe country inhabitants.
time_zones	A list of all time zone offsets in which a country lies. Offsets of overseas territories for each country are also included in the list.
currency	Object containing recognized currencies in each country. Includes currency name, symbol, fractional unit, and ISO 4217 currency code.
languages	Object containing a list of official languages for each country.
government	Object containing government structure for each country. Includes system of governance, head of state, and constitutional form.
gdp	Object containing nominal GDP and nominal per capita GDP.
elevation	Object containing elevations for each country. Includes minimum, maximum, and span in feet and meters. . Also includes highest and lowest geographic point for each country.
gini	GINI index for the country.
hdi	Human Development Index for the country.
traffic	Traffic indicator for the country. Options are right hand traffic (RHT) or left hand traffic (LHT).
fearson_diversity	Object containing Fearon diversity index. Includes linguistic, religious, and ethnic fractionalizations.
anthem	Official country anthem.
motto	Official country motto.

Plans and Pricing

Four usage plans are available for Countries API. Review each plan’s features and choose the one that fits you best. If necessary, we can even create a custom plan tailored to your exact needs. All plans are month-to-month and can be cancelled at any time.

Basic

$0/month
40 requests/day
no overages allowed

Pro

$9.99/month
300 requests/day
$0.025 per additional request

Ultra

$49.99/month
750 requests/day
$0.01 per additional request

Basic Country Data
Detailed Country Data
Name/Capital Search Paths
Path Parameters
Sort and Filter Results
Randomized Results
Email Support

Mega

$99.99/month
5000 requests/day
$0.001 per additional request

Basic Country Data
Detailed Country Data
Name/Capital Search Paths
Path Parameters
Sort and Filter Results
Randomized Results
Metadata Endpoint
Custom Endpoints
Email Support

Response

Data is returned in a standard JSON format and easily parsed in any programming language. All data is in string format for ease of use and manipulation. A sample response is provided below:

[
    {
        “name”: “Spain”,
        “state_name”: “Kingdom of Spain”,
        “capital”: [
            {
                “name”: “Madrid”,
                “notes”: “official”,
                “latitude”: “40.416775”,
                “longitude”: “-3.70379”,
                “population”: “3266126”
            }
        ],
        “population”: {
            “density_km”: “93.67”,
            “total”: “47394223”,
            “density_mi”: “242.59”
        },
        “iso_3166”: {
            “alpha2”: “ES”,
            “alpha3”: “ESP”,
            “numeric”: “724”,
            “subdivision”: “ISO 3166-2:ES”
        },
        “sovereignty”: “UN Member State”,
        “un_geoscheme”: {
            “region”: “Europe”,
            “subregion”: “Southern Europe”
        },
        “area”: {
            “total_mi”: “195365”,
            “land_km”: “498980”,
            “land_mi”: “192660”,
            “water_km”: “6390”,
            “total_km”: “505992”,
            “water_mi”: “2470”,
            “water_percent”: “1”
        },
        “elevation”: {
            “min_ft”: “sea level”,
            “min_m”: “sea level”,
            “span_m”: “3715”,
            “max_ft”: “12188”,
            “span_ft”: “12188”,
            “max_m”: “3715”
        },
        “native_name”: [
            {
                “name”: “España”,
                “state_name”: “Reino de España”,
                “language”: “Spanish”
            }
        ],
        “demonyms”: [
            “Spanish”
        ],
        “time_zones”: {
            “count”: “2”,
            “offset”: [
                “UTC±00:00”,
                “UTC+01:00”
            ]
        },
        “currency”: [
            {
                “name”: “Euro”,
                “symbol”: “€”,
                “fractional_unit”: “Cent”,
                “iso_4217”: “EUR”
            }
        ],
        “languages”: {
            “official”: [
                “Spanish”
            ]
        },
        “land_borders”: {
            “count”: “5”,
            “alpha2”: [
                “AD”,
                “FR”,
                “MA”,
                “PT”,
                “GI”
            ],
            “alpha3”: [
                “AND”,
                “FRA”,
                “MAR”,
                “PRT”,
                “GIB”
            ],
            “names”: [
                “Andorra”,
                “France”,
                “Morocco”,
                “Portugal”,
                “Gibraltar”
            ]
        },
        “government”: {
            “system_of_governance”: “Constitutional monarchy with ceremonial/non-executive monarch”,
            “constitutional_form”: “Constitutional Monarchy”,
            “head_of_state”: “Ceremonial”
        },
        “gdp”: {
            “nominal”: “1393490”,
            “nominal_per_capita”: “29402.11”
        },
        “fearon_diversity”: {
            “linguistic”: “0.4132”,
            “religious”: “0.4514”,
            “ethnic”: “0.4165”
        },
        “top_level_domain”: “.es”,
        “calling_code”: “34”,
        “gini”: “34.7”,
        “hdi”: “0.904”,
        “traffic”: “RHT”,
        “anthem”: “La Marcha Real (The Royal March)”,
        “motto”: “Further beyond”
    }
]

Errors

When a problem occurs, a JSON error is returned. The error will contain a status code and message. Errors are explained below:

Status Code

400

401

404

Message

Invalid Request

Unauthorized

Value Not Found

Information

You have specified an invalid resource or not supplied appropriate path parameters.

You are not authorized to use the specified endpoint.

The path parameter(s) provided could not be found.

Endpoints

The API provides numerous endpoints for ultimate flexibility. Select an endpoint below to understand usage and response. Note that not all endpoints are available on all plans.

/basic

An API request to the /basic endpoint returns six fields for every country:

Name, State Name, Capital, ISO 3166, UN Geoscheme, and Population.

Available on all plans.

/all

An API request to the /all endpoint returns all fields for every country.

Query string parameters can be used on this endpoint for additional filtering and sorting capabilities. ‘sort’, ‘limit’, ‘fields’, and ‘randomize’ parameters can be used individually or together.

Example: /all?sort=state_name:desc returns all fields for all countries sorted in descinding order by state name (‘asc’ sorts ascending).

Example: /all?limit=5 returns at most 5 records.

Example: /all?fields=name,state_name,capital returns only name, state name, and capital fields.

Example: /all?randomize=true returns response data in random order. This is a neat feature for quiz or game apps. Get a single, random country name by using: /all?limit=1&fields=name&randomize=true