Creating an Account
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
- 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]"
}
-
You will receive an email with a link. Click on that link to verify your email address.
-
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"
}
- Generate an API key with your Signin Token.
POST /api/apiKey/generateApiKey
Key | Value |
---|---|
Authorization | Bearer P62VLToAfNgXBGmdQ4DFe4d7Eaw1Co4ms |
// 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
Key | Value |
---|---|
Authorization | Bearer fa966c9db6d84a97ad147e29 |
// 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
Key | Value |
---|---|
Authorization | Bearer P62VLToAfNgXBGmdQ4DFe4d7Eaw1Co4ms |
// 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
Updated over 2 years ago