Getting Started

The API uses a unique identifier, an API key, that is passed in the URL parameter access_key. This parameter serves as a unique identifying authentication with the Countrylayer API.

Base URL:

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

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 the world's countries.

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 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.

Other Errors: