Please refer to Terms of Use before using our API.

Authorization

You need to create an account and generate an API key in order to use the APIs.

Create an Account and Generate an API Key

1. Create a new user account with

POST /api/user

// Request Body
{
  "username": "testuser",
  "email": "[email protected]",
  "password": "XXXXXXX"
}

// Response Body
{
    "id": "308efe70-2d2c-11ea-ba7c-d58de15e5bca",
    "username": "testuser",
    "email": "[email protected]"
}

2. You will receive an email with a link. Click on that link to verify your email address.

3. Generate a Signin Token with your username and password.

POST /signin

// Request Body
{  
   "username":"testuser",
   "password":"XXXXXXX"
}

// Response Body
{
    "access_token": "P62VLToAfNgXBGmdQ4DFe4d7Eaw1Co4ms",
    "expires_in": 1209600,
    "scope": "basic",
    "refresh_token": "t9RoypeNQxUFSgqFbWuGzFPicxL6472E",
    "token_type": "Bearer"
}

4. Generate an API key with your Signin Token.

POST /api/apiKey/generateApiKey

// Response Body
{
    "key": "fa966c9db6d84a97ad147e29"
}

This API key is long lived and we can deactivate it easily by using the above endpoint with the Signin Token again. Generating a new API key will deactivate the old one.

Start Using the APIs

Once you have created an API key, you can begin using the APIs.
Here is an example of how to pass in the API key to the rest of the APIs

GET /api/country/v2/countries?countryCode=US

// Response Body

[
  {
    "code": "US",
    "internationalDialingCode": "1",
    "currencyCode": "USD",
    "flag": "https://restcountries.eu/data/usa.svg",
    "cioc": "USA",
    "name": "United States of America",
    "demonym": "American",
    "cca2": "US",
    "cca3": "USA",
    "ccn3": "840",
    "id": "USA"
  }
]

Checking API Quota

By default, you're assigned 5000 API calls per month. To check your remaining quota for the month, use this endpoint with the Signin Token.

GET /api/user/apiQuota

// Response Body

{
  "monthlyRemainingQuota": 5000
}

Testing

You may use your API key to test the APIs for your application through the API console. Here are the steps to use the API console:

• Click on GET/POST to expand the call method details, then fill in the keyword parameter(s).
• Click on the "Try it" button to see the response, request URL and cURL of the API call.
  To integrate the API into your application, simply add the provided Key in the HTTP header (e.g. Authorization: Bearer XXXXXXXXXXXXXXXXXXX)

Responses

The response object provides an HTTP status code, which indicates whether a call has succeeded or failed. Status codes:

• HTTP Status Code: 200
  Indication: Successful

• HTTP Status Code: 4xx/5xx
  Indication: Failed. The response body will provide more details of the error