Countrylayer API

The countrylayer service provides common information about countries via a REST API. With this API, users will be able to get detailed information about countries in the world. Because they can filter by name of a country, language, code, currency, the capital city, calling code, region, or regional bloc.

In this document, you will find out about the API structure, the methods, potential errors you may encounter, and code examples. If you still have questions and doubts, please do not hesitate to contact us. Our team will do their best to help you.

API Key

The API has a unique identifier as an API key that gets passed into the API as an URL parameter access_key. This parameter serves as a unique identifying authentication with the countrylayer API.

Base URL:

https://api.countrylayer.com/v2/

Append your API Key: See an example of how to authenticate the countrylayer API with the access_key parameter: 

https://api.countrylayer.com/v2/all
    ? access_key = API_KEY

API Response

The data is returned in a standard JSON format and easily parsed in any programming language.

Example Response: See below an example of an API response that provides information about all world countries. 

[
  {
        "name": "Germany",
        "topLevelDomain": [
            ".de"
        ],
        "alpha2Code": "DE",
        "alpha3Code": "DEU",
        "callingCodes": [
            "49"
        ],
        "capital": "Berlin",
        "altSpellings": [
            "DE",
            "Federal Republic of Germany",
            "Bundesrepublik Deutschland"
        ],
        "region": "Europe",
        "subregion": "Western Europe",
        "population": 81770900,
        "latlng": [
             51,
             9
        ],
         "demonym": "German",
         "area": 357114,
         "gini":  28.3,
         "timezones": [
             "UTC+01:00"
        ],
        "borders": [
            "AUT",
            "BEL",
            "CZE",
            "DNK",
            "FRA",
            "LUX",
            "NLD",
            "POL",
            "CHE"
        ],
        "nativeName": "Deutschland",
        "numericCode": "276",
        "currencies": [
            {
                "code": "EUR",
                "name": "Euro",
                "symbol": "€"
            }
        ],
        "languages": [
            {
                "iso639_1": "de",
                "iso639_2": "deu",
                "name": "German",
                "nativeName": "Deutsch"
            }
        ],
        "translations": {
            "br": "Alemanha",
            "de": "Deutschland",
            "es": "Alemania",
            "fa": "آلمان",
            "fr": "Allemagne",
            "hr": "Njemačka",
            "it": "Germania",
            "ja": "ドイツ",
            "nl": "Duitsland",
            "pt": "Alemanha"
        },
        "flag": "https://restcountries.eu/data/deu.svg",
        "regionalBlocs": [
            {
                "acronym": "EU",
                "name": "European Union"
            }
        ],
        "cioc": "GER"
    },
    {…}
]

As we can see from the example response above, we are receiving different details regarding countries.

Available Endpoints

The API comes with a number of endpoints. Each of them provides different functionality. Please be aware that not all endpoints are available on every subscription plan.

Connecting via HTTPS

All paid subscription plans available for the countrylayer API come with support for 256-bit SSL encryption. To connect to the API via HTTPS, simply use the HTTPS protocol instead of standard HTTP.

Error Codes

Whenever a requested resource is not available or an API call fails for another reason, a JSON error is returned. Errors always come with an error code and a description.

Example Error: The following error is returned if your monthly API request volume has been exceeded. 

{
	"success": false,
	"error": {
	"code": 104,
	"type": "monthly_limit_reached",
	"info": "Your monthly API request volume has been reached. Please upgrade your plan."    
	}
}

Other Errors:

                     
Code Type Info
404 404_not_found The requested resource does not exist.
101 invalid_access_key No API Key was specified or an invalid API Key was specified.
103 invalid_api_function The requested API endpoint does not exist.
104 usage_limit_reached The maximum allowed API amount of monthly API requests has been reached.
                 

Endpoints

Endpoint for all countries

The API comes with an updated endpoint that returns all of the available countries. To receive the list, make an API request to “/all” endpoint.

NOTE: Depending on your subscription plan, you may receive limited data information using this endpoint.

API Request:

GET https://api.countrylayer.com/v2/all
    ? access_key = API_KEY

Request Parameters:

Parameter Description
access_key [Required] Your API Key.

API Response: 

[
    {
        "name": "Afghanistan",
        "topLevelDomain": [
            ".af"
        ],
        "alpha2Code": "AF",
        "alpha3Code": "AFG",
        "callingCodes": [
            "93"
        ],
        "capital": "Kabul",
        "altSpellings": [
            "AF",
            "Afġānistān"
        ],
        "region": "Asia",
        "subregion": "Southern Asia",
        "population": 27657145,
        "latlng": [
            33,
            65
        ],
        "demonym": "Afghan",
        "area": 652230,
        "gini": 27.8,
        "timezones": [
            "UTC+04:30"
        ],
        "borders": [
            "IRN",
            "PAK",
            "TKM",
            "UZB",
            "TJK",
            "CHN"
        ],
        "nativeName": "افغانستان",
        "numericCode": "004",
        "currencies": [
            {
                "code": "AFN",
                "name": "Afghan afghani",
                "symbol": "؋"
            }
        ],
        "languages": [
            {
                "iso639_1": "ps",
                "iso639_2": "pus",
                "name": "Pashto",
                "nativeName": "پښتو"
            },
            {
                "iso639_1": "uz",
                "iso639_2": "uzb",
                "name": "Uzbek",
                "nativeName": "Oʻzbek"
            },
            {
                "iso639_1": "tk",
                "iso639_2": "tuk",
                "name": "Turkmen",
                "nativeName": "Türkmen"
            }
        ],
        "translations": {
            "br": "Afeganistão",
            "de": "Afghanistan",
            "es": "Afganistán",
            "fa": "افغانستان",
            "fr": "Afghanistan",
            "hr": "Afganistan",
            "it": "Afghanistan",
            "ja": "アフガニスタン",
            "nl": "Afghanistan",
            "pt": "Afeganistão"
        },
        "flag": "https://restcountries.eu/data/afg.svg",
        "regionalBlocs": [
            {
                "acronym": "SAARC",
                "name": "South Asian Association for Regional Cooperation"
            }
        ],
        "cioc": "AFG"
    },

Response Objects:

Parameter/Object Description
name Returns the name of the country
topLevelDomain Returns the country internet domain
alpha2Code Holds information about the country alpha2 code
alpha3Code Holds information about the country alpha2 code
callingCodes An object that holds information about all calling codes available in the country
capital Returns information about the country capital city
altSpellings An object that holds the information about the country alt spellings
region Returns information about the region in which the country is
subregion Returns information about the subregion in which the country is
population Holds information about the country population
latlng An object that returns the information about the latitude and the longitude of the country’s position.
demonym Holds information about the country demonym
area Holds information about the size of the geographical area that the country has.
gini Holds information about the country gini coefficient
timezones An object that holds all timezones in which the country belongs
borders An object holding information about the countries with which the country is bordering
nativeName Information about the country native name
numericCode The country numeric Code
currencies An object holding all available currencies in the country
languages An object holding all languages spoken into the country
translations An object that holds information about the different translations of the country name
flag URL holding the country flag image
regionalBlocs Regional blocks in which the country is a member
cioc Returns the country cioc code.

Endpoint for country search by name

This endpoint will return available country data when it is searched by name of the country. If we search using a partial name, for example, “aus” then the API will return all countries that contain “Aus”. If we want to search for a country by the correct full name, then in the query we will have to add the parameter FullText, true or false.

API Request:

GET https://api.countrylayer.com/v2/name/{name}
    ? access_key = API_KEY & fullText=

Request Parameters:

Parameter Description
access_key [Required] Your API Key.
name As part of the URL
fullText A boolean parameter in the URL

The API response and parameters are given above in the /all endpoint example.

Endpoint for country search by capital

This endpoint will return available country data when it is searched by the name of the country’s capital city.


API Request:

GET https://api.countrylayer.com/v2/capital/{capital}
    ? access_key = API_KEY

Request Parameters:

Parameter Description
access_key [Required] Your API Key.
capital As part of the URL

The API response and parameters are given above in the /all endpoint example.

Endpoint for country search by language

This endpoint will return available country data when it is searched by the official language spoken in the country. For example, if we search “ita” all countries where Italian is spoken will be returned into the response.


API Request:

GET https://api.countrylayer.com/v2/language/{language}
    ? access_key = API_KEY

Request Parameters:

Parameter Description
access_key [Required] Your API Key.
language As part of the URL

The API response and parameters are given above in the /all endpoint example.

Endpoint for country search by currency

This endpoint will return available country data when it is searched by the official currency in the country. For example, if we search “eur” all countries where Euro is the official currency will be returned into the response.

API Request:

GET https://api.countrylayer.com/v2/currency/{currency}
    ? access_key = API_KEY

Request Parameters:

Parameter Description
access_key [required] Your API Key.
currency As part of the URL

The API response and parameters are given above in the /all endpoint example.

Endpoint for country search by region

This endpoint will return available country data when it is searched by the region in which the country is located. For example, if we search “americas” all countries that are in Americas region will be returned to the response.

API Request:

GET https://api.countrylayer.com/v2/region/{region}
    ? access_key = API_KEY

Request Parameters:

Parameter Description
access_key [required] Your API Key.
region As part of the URL

The API response and parameters are given above in the /all endpoint example.

Endpoint for country search by region block

This endpoint will return available country data when it is searched by the region block in which the country is a member. For example, if we search “EU” all countries that are members of the European Union will be returned into the response.

API Request:

GET https://api.countrylayer.com/v2/regionalbloc/{regionalbloc}
    ? access_key = API_KEY

Request Parameters:

Parameter Description
access_key [required] Your API Key.
regionalbloc As part of the URL

The API response and parameters are given above in the /all endpoint example.

Endpoint for country search by calling code

This endpoint will return available country data when it is searched by the country’s official calling code.

API Request:

GET https://api.countrylayer.com/v2/callingcode/{callingcode}
    ? access_key = API_KEY

Request Parameters:

Parameter Description
access_key [required] Your API Key.
callingcode As part of the URL

The API response and parameters are given above in the /all endpoint example.

Endpoint for country search by alpha code

This endpoint will return available country data when it is searched by the country alpha code.

API Request:

GET https://api.countrylayer.com/v2/alpha/{code}
    ? access_key = API_KEY

Request Parameters:

Parameter Description
access_key [required] Your API Key.
code As part of the URL

The API response and parameters are given above in the /all endpoint example.

Filters

As part of the API requests, filters can be used in order to refine the response only to needed information. For example, if you as a user want to receive information only about the country name, capital, and currency, then in the query parameters you can add filters. Example: filters=name;capital;currencies.

Example Response: 

{
    "name": "Austria",
    "capital": "Vienna",
    "currencies": [
        {
            "code": "EUR",
            "name": "Euro",
            "symbol": "€"
        }
    ]
}