How to Use the REST Countries API with Python, PHP, Ruby & Javascript Examples

Getting information or metadata about countries is critical for many software applications. For instance, most product registration forms require clients to specify their country, country code, and other related information. Moreover, some shipping-related software needs to return the country codes for faster shipments. In such scenarios, it is convenient if there is a way for the application to retrieve the required data quickly.

Fortunately, now there are APIs that enable you to get country data for your applications. REST Countries API is one such API that provides essential information about countries.

Connect to the REST Countries API

What is the REST Countries API?

REST Countries API is a simple REST API from RapidAPI that provides information about countries in the world In JSON format. Data of each country contains useful information like the capital city, population, languages, currencies, regions, country code, and many more.

This API is completely free and supports various programming languages, including Python, PHP, Ruby, and Javascript. In this article, we will see how to use REST Countries API with multiple programming languages.

How does the REST Countries API work?

REST Countries API works by sending a request to the endpoint and getting the necessary response from the server. It only uses the API key and API host authentication parameters when sending the request so that the server can identify that it is coming from a legitimate client. Once the API server receives the valid request, the backend application will process it and send back the response to the client in JSON format. If the request is successful, it will display all the country data. On the other hand, the response payload will contain details about the error and the relevant error code if the request is invalid or unsuccessful.

Target Audience for the REST Countries API

Web Developers

REST Countries API is useful for web developers for many website functionalities, such as creating registration or sign-up forms, displaying currencies for hotel booking websites, and payment applications, to name a few. They can use this API to populate a dropdown list of countries and auto-fill other data corresponding to the country the clients select. This API is also useful for educational websites and apps for small children for teaching basic information about countries.

Shipping Companies

In particular, this API is very useful for app developers looking to build international shipping apps for shipping companies that often require country data to complete the shipment information and tracking. Besides, this API allows shipping companies to create a database of country information that is searchable at any time.

Researchers/Learners

Apart from using apps developed using this API, students and researchers can directly get information from this API for any research and activities related to countries. They can get the required information at no cost since this API is completely free.

How to connect to the REST Countries API Tutorial – Step by Step.

Step 1 – Sign up and Get a RapidAPI Account.

RapidAPI is the world’s largest API marketplace used by more than a million developers around the world. You can use RapidAPI to search and connect to thousands of APIs using a single SDK, API key, and Dashboard.

To create a RapidAPI account, go to rapidapi.com and click on the Sign Up icon. You can use your Google, Github, or Facebook account for Single Sign-on (SSO) or create an account manually.

Step 2 – Search the API Marketplace

Navigate to the Marketplace and search for “REST Countries API.” Then, select the REST Countries API (The first API in the following image) from the search results.

Step 3 – Test the API

It is important to run a test for the endpoints after subscribing to the API. For that, navigate to the Endpoints section of the API, which lists all the available endpoints.

Next, select the endpoint you want to test and add the required details. Each API endpoint has code snippets in multiple languages, and it automatically adds the API keys.

Finally, click on the “Test Endpoint” Button to test the API. Upon successful testing of an API endpoint, you will get the response with a 200 status. On the other hand, it will output an error code and message if there is an error in the request.

REST Countries API Endpoints

There is one endpoint for REST Countries API.

GET /rest/v1/all

This endpoint returns all the countries with a list of information about them. You do not need to specify any mandatory parameters for this simple endpoint, and it only requires the X-RapidAPI-Key and X-RapidAPI-Host header parameters.

The following list shows a summary of the data it returns as the response.

Country name
Capital city
An object of alternative spellings for the country name. For example, for the USA, alternatives will be: “US,” “USA,” and “United States of America.”
The relevance
Regions and sub-regions the country belongs to
Translation of the country name in German, Spanish, French, Japanese, and Italian
The population of the country
Latitude and longitude
Demonym or the name of the nationality. For example, the demonym of Australia is Australian, Portugal is Portuguese, etc.
Area of the country
The Gini Index
A list of timezones
A list of border country codes
Native name
Calling codes
Top-level domain name. For example, ‘.au’ for Australia and ‘.uk’ for the United Kingdom
Three-letter ISO 3166-1 alpha-3 code. For example, ‘AFG’ for Afghanistan
Two-letter ISO 3166-1 alpha-2 code. For example, ‘AF’ for Afghanistan
A list of currencies
A list of languages

Integrating REST Countries API to an Application

In this section, we will see how to integrate the REST Countries API into a software application using different programming languages such as Python, PHP, Ruby, and Javascript. To execute these code snippets, first, you need to install the specific programming language on your computer. We will be using the “/rest/v1/all ” GET endpoint for all the code snippets.

You can simply integrate the following code snippets into your application based on the application language. You need to include the API key and API-host parameters in the header of each code snippet.

Python Code Snippet (requests)

The following Python code uses the “requests” library to send a GET request to the endpoint. Define the mandatory search term in the “query string” variable. Then use the URL, header, and the query string in the request method of the Request object to send the API call programmatically. You can also use requests.post method for this purpose.

import requests
url = "https://ajayakv-rest-countries-v1.p.rapidapi.com/rest/v1/all"
headers = {
    'x-rapidapi-host': "ajayakv-rest-countries-v1.p.rapidapi.com",
    'x-rapidapi-key': "cJvLRNK0GfdM9WSMbQe3inU7REn8JVy5"
    }
response = requests.request("GET", url, headers=headers)
print(response.text)

PHP Code Snippet (HTTP v2)

First, create two class objects for the client and the request. Then you need to set the API URL, request method, and the header separately from the request object. Finally, send the request through the send method of the client object.

<?php
 
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://ajayakv-rest-countries-v1.p.rapidapi.com/rest/v1/all');
$request->setRequestMethod('GET');
$request->setHeaders([
  'x-rapidapi-host' => 'ajayakv-rest-countries-v1.p.rapidapi.com',
  'x-rapidapi-key' => 'cJvLRNK0GfdM9WSMbQe3inU7REn8JVy5'
]);
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

Ruby (net::http)

Suppose you are using net::http module, import OpenSSL and URI modules of Ruby at the beginning. In this instance, bypass SSL certification verification by setting it to ‘VERIFY_NONE..’ Then, set request headers separately and send the request using the request method of the HTTP object as in the above code examples.

require 'uri'
require 'net/http'
require 'openssl'
 
url = URI("https://ajayakv-rest-countries-v1.p.rapidapi.com/rest/v1/all")
 
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
 
request = Net::HTTP::Get.new(url)
request["x-rapidapi-host"] = 'ajayakv-rest-countries-v1.p.rapidapi.com'
request["x-rapidapi-key"] = 'cJvLRNK0GfdM9WSMbQe3inU7REn8JVy5'
 
response = http.request(request)
puts response.read_body

Javascript (Axios)

Integrating this API into a JavaScript application is pretty straightforward and requires just a few lines of code. The following code snippet shows how to call this API using the ‘axios’ module of JavaScript. You can define the url, headers, and the request method in one JavaScript object and use the ‘axios. request’ method to send the request and retrieve the response.

import axios from "axios";
const options = {
  method: 'GET',
  url: 'https://ajayakv-rest-countries-v1.p.rapidapi.com/rest/v1/all',
  headers: {
    'x-rapidapi-host': 'ajayakv-rest-countries-v1.p.rapidapi.com',
    'x-rapidapi-key': 'cJvLRNK0GfdM9WSMbQe3inU7REn8JVy5'
  }
};
axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

Alternative to REST Countries API

Turnup Locations API – This API provides a list of Countries, States / Regions, and Cities. Using this API, you can get a list of Continent data, search continent by continent code, and search a country by its name and ID.

GeoDB API – You can use this comprehensive API to get the global city, region, and country data, and you can filter and display results in multiple languages.

Geo-Services by MVPC.com – This is another API that can be used to get country data like timezone, elevation, cities, sunset/sunrise, and distance. It provides a countries endpoint that returns all countries and relevant information.

Referential – This API is a collection of APIs that can return countries, states, cities, continents, dial, and zip codes in up to 20 languages. This API gets data from International Standardization bodies, the United Nations, government surveys, and GIS datasets.

Countries Cities – This API Provides information about countries and cities. Especially, its country data endpoint returns country data such as capital, location, timezone, population, currency, languages, and phone code.

Benefits of the REST Countries API

Easy to Integrate

The endpoint of REST Countries API is very simple and only requires header parameters. In addition, you can find example code snippets in many programming languages with two or more frameworks or modules. Hence, it is easy to integrate into any application. This simplicity enables even someone with little to no background using APIs to master this API reasonably quickly.

Wider Usage

The API response contains a lot of information that is beneficial for many applications. One can use all those data at once or only specific information from the response. For example, apps that need to show the Gini index of countries, the border countries, country calling codes, etc., can extract that specific information from the response. Thus this API can be integrated into many types of applications, resulting in wider usage.

Free API

REST Countries API allows app developers to get its full capabilities free of charge. It will be a huge benefit, especially for students who learn about APIs and application developers to develop innovative applications.

Summary

The REST Countries API is a free and simple API that provides useful information about all the world nations. Developers can utilize it for many application functionalities due to the usefulness of the data it provides. This article covered the available endpoints of this API and provided sample code snippets in Python, PHP, Ruby, and Javascript to show how to integrate it into an application.

Connect to the REST Countries API