Documentation - countrylayer

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.

Endpoint for all countries: This endpoint returns information about all countries in the world.
Endpoint for country search by name: With this endpoint, we can receive information for the country searching it by name.
Endpoint for country search by capital: With this endpoint, we can receive information for the country searching it by the capital city.
Endpoint for country search by language: With this endpoint, we can receive information for the country searching it by the country language.
Endpoint for country search by currency: With this endpoint, we can receive information for the country searching it by the country used currency.
Endpoint for country search by region: With this endpoint, we can receive information for the countries searching it by the region in which the countries are belonging.
Endpoint for country search by region block: With this endpoint, we can receive information for the countries searching it by the region block where the countries are members.
Endpoint for country search by calling code: With this endpoint, we can receive information for the country searching it by the country calling code.
Endpoint for country search by alpha code: With this endpoint, we can receive information for the country searching it by the country alpha code.

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": "€"
        }
    ]
}

Business Continuity - API Overages

Ensuring our customers achieve success is paramount to what we do at APILayer. For this reason, we will be rolling out our Business Continuity plan guaranteeing your end users will never see a drop in coverage. Every plan has a certain amount of API calls that you can make in the given month. However, we would never want to cut your traffic or impact user experience negatively for your website or application in case you get more traffic.

What is an overage?

An overage occurs when you go over a quota for your API plan. When you reach your API calls limit, we will charge you a small amount for each new API call so we can make sure there will be no disruption in the service we provide to you and your website or application can continue running smoothly.

Prices for additional API calls will vary based on your plan. See table below for prices per call and example of an overage billing.

Plan Name	Monthly Price	Number of Calls	Overage Price per call	Overage	Total price
Basic	$9.99	250	0.047952	100	$14.79
Professional	$49.99	5,000	0.0119976	1000	$61.99
Enterprise	$149.99	20,000	0.0089994	3000	$176.99

Why does APILayer have overage fees?

Overage fees allow developers to continue using an API once a quota limit is reached and give them time to upgrade their plan based on projected future use while ensuring API providers get paid for higher usage.

How do I know if I will be charged for overages?

When you are close to reaching your API calls limit for the month, you will receive an automatic notification (at 75%, 90% and 100% of your monthly quota). However, it is your responsibility to review and monitor for the plan’s usage limitations. You are required to keep track of your quota usage to prevent overages. You can do this by tracking the number of API calls you make and checking the dashboard for up-to-date usage statistics.

How will I be charged for my API subscription?

You will be charged for your monthly subscription plan, plus any overage fees applied. Your credit card will be billed after the billing period has ended.

What happens if I don’t have any overage fees?

In this case, there will be no change to your monthly invoice. Only billing cycles that incur overages will see any difference in monthly charges. The Business Continuity plan is an insurance plan to be used only if needed and guarantees your end users never see a drop in coverage from you.

What if I consistently have more API calls than my plan allows?

If your site consistently surpasses the set limits each month, you may face additional charges for the excess usage. Nevertheless, as your monthly usage reaches a certain threshold, it becomes more practical to consider upgrading to the next plan. By doing so, you ensure a smoother and more accommodating experience for your growing customer base.

I would like to upgrade my plan. How can I do that?

You can easily upgrade your plan by going to your Dashboard and selecting the new plan that would be more suitable for your business needs. Additionally, you may contact your Account Manager to discuss a custom plan if you expect a continuous increase in usage.

Introducing Platinum Support - Enterprise-grade support for APILayer

Upgrade your APILayer subscription with our exclusive Platinum Support, an exceptional offering designed to enhance your business’ API management journey. With Platinum Support, you gain access to a host of premium features that take your support experience to a whole new level.

What does Platinum Support include?

	Standard Support	Platinum Support
General review of the issue
Access to knowledge base articles
Email support communication
Regular product updates and fixes
Dedicated account team
Priority Email Support with unlimited communication
Priority bug review and updates
Option for quarterly briefing call with Product Management
Feature requests as priority roadmap input into product

Priority Email Support: Experience unrivaled responsiveness with our priority email support. Rest assured that your inquiries receive top-priority attention, ensuring swift resolutions to any issues.

Unlimited Communication: Communication is key, and with Platinum Support, you enjoy unlimited access to our support team. No matter how complex your challenges are, our experts are here to assist you every step of the way.

Priority Bug Review and Fixes: Bugs can be a headache, but not with Platinum Support. Benefit from accelerated bug review and fixes, minimizing disruptions and maximizing your API performance.

Dedicated Account Team: We understand the value of personalized attention. That's why Platinum Support grants you a dedicated account team, ready to cater to your specific needs and provide tailored solutions.

Quarterly Briefing Call with Product Team: Stay in the loop with the latest updates and insights from our product team. Engage in a quarterly briefing call to discuss new features, enhancements, and upcoming developments.

Priority Roadmap Input: Your input matters! As a Platinum Support subscriber, your feature requests receive top priority, shaping our product roadmap to align with your evolving requirements.

Don't settle for the standard when you can experience the exceptional. Upgrade to Platinum Support today and supercharge your APILayer experience!

UPGRADE NOW