REST Countries Getting Started: First API Call (2026)

Getting started overview

REST Countries offers a public API that provides country data without requiring an API key or authentication. This design choice simplifies the initial setup process, allowing developers to make requests directly to the API endpoints. The primary endpoint, /all, retrieves data for all countries. Responses are formatted as JSON, which is a common data interchange format for web APIs, as described by the JSON specification. This guide outlines the steps to perform your first API call and integrate country data into an application.

The API is best suited for applications that need to display country information, integrate country flags, or populate country-related dropdown menus. Its fully free tier and public access make it a suitable option for lightweight country data lookups. The API reference is available directly from the REST Countries official documentation.

Quick Reference Steps

The following table provides a high-level overview of the steps to get started with REST Countries:

Create an account and get keys

Unlike many other APIs, REST Countries does not require users to create an account or obtain an API key. The API is designed for public access, meaning that all endpoints are openly available for HTTP requests without any authentication headers or parameters. This significantly streamlines the onboarding process, as developers can immediately begin making requests to the API endpoints as documented on the REST Countries homepage.

This approach simplifies development, particularly for prototypes or applications where managing API keys might introduce unnecessary overhead. However, it also means there are no rate limits enforced per user, which could lead to performance issues if the API experiences very high demand. Developers should consider implementing their own caching mechanisms or rate limiting on the client side if their application anticipates frequent requests to avoid overwhelming the API or their own application.

Your first request

Making your first request to the REST Countries API is straightforward due to the lack of authentication. You can use various tools, including a web browser, cURL on the command line, or an HTTP client library in your preferred programming language.

Using a Web Browser

The simplest way to see the API's output is by navigating to the endpoint directly in your web browser. Open your browser and enter the following URL:

https://restcountries.com/v3.1/all

This will display a JSON array containing data for all countries. Your browser might format this JSON for readability if you have a browser extension installed for JSON viewing.

Using cURL

For command-line users, cURL is a common tool for making HTTP requests. Open your terminal or command prompt and execute the following command:

curl https://restcountries.com/v3.1/all

This command will print the entire JSON response to your console. For better readability, especially with large responses, you might pipe the output to a JSON formatter like jq:

curl https://restcountries.com/v3.1/all | jq .

jq is a lightweight and flexible command-line JSON processor. Information on jq can be found on its official documentation website.

Using Python (requests library)

If you're integrating the API into a Python application, the requests library is a common choice for making HTTP requests. First, ensure you have the library installed:

pip install requests

Then, you can make a request and process the JSON response:

import requests
import json

url = "https://restcountries.com/v3.1/all"
response = requests.get(url)

if response.status_code == 200:
    countries_data = response.json()
    # Print data for the first country as an example
    if countries_data:
        print(json.dumps(countries_data[0], indent=2))
    else:
        print("No country data received.")
else:
    print(f"Error: {response.status_code} - {response.text}")

This Python script fetches all country data and prints the detailed information for the first country in the list, formatted for readability.

Using JavaScript (Fetch API)

For client-side web applications, the Fetch API is a modern, promise-based mechanism for making web requests. Here's an example of how to fetch country data:

fetch('https://restcountries.com/v3.1/all')
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    // Log data for the first country as an example
    if (data.length > 0) {
      console.log(data[0]);
    } else {
      console.log('No country data received.');
    }
  })
  .catch(error => console.error('Error fetching country data:', error));

This JavaScript snippet demonstrates how to make a GET request and handle the JSON response, logging the details of the first returned country to the browser's console.

Common next steps

Once you have successfully made your first request and received country data, consider these common next steps to further integrate REST Countries into your application:

1. Explore Specific Endpoints: The API offers various endpoints beyond /all, such as searching by name (/name/{name}), code (/alpha/{code}), or region (/region/{region}). Review the REST Countries API documentation for a complete list and examples.
2. Filter Fields: To optimize payload size and network performance, you can specify which fields to include in the response using the fields parameter. For example, https://restcountries.com/v3.1/all?fields=name,capital,flags returns only the name, capital, and flags for each country.
3. Implement Caching: Since the API is public and does not have explicit rate limits per user, implementing client-side caching can improve performance and reduce redundant requests, especially for data that doesn't change frequently. You can store fetched data locally for a specific duration.
4. Error Handling: Implement robust error handling in your application to manage cases where the API might return non-200 status codes (e.g., 404 for not found, 500 for server errors). The MDN Web Docs on HTTP status codes provide a comprehensive reference.
5. Data Display: Design how to present the fetched country data in your user interface. This might involve creating dynamic dropdowns, country profile pages, or interactive maps using libraries like Leaflet or Google Maps, populated with REST Countries data.
6. Integration with UI Frameworks: If you are using a front-end framework like React, Vue, or Angular, integrate the API calls within your component lifecycle methods or dedicated data services.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips for REST Countries:

• Incorrect Endpoint URL: Double-check the URL for typos. The base URL is https://restcountries.com/v3.1/. Ensure you're using the correct version (v3.1) and endpoint path (e.g., all, name/{name}). Refer to the official API documentation for exact endpoint paths.
• Network Connectivity: Verify your internet connection. A lack of connectivity will prevent any HTTP request from succeeding.
• Firewall or Proxy Issues: If you're in a corporate or restricted network environment, a firewall or proxy server might be blocking outgoing HTTP requests to external domains. Consult your network administrator if you suspect this is the case.
• JSON Parsing Errors: If your code fails to parse the JSON response, ensure that the response is indeed valid JSON. Tools like online JSON validators can help confirm this. Incorrect parsing might occur if the API returns an error message in a non-JSON format (e.g., plain text or HTML).
• HTTP Status Codes: Always check the HTTP status code of the response. A 200 OK indicates success. Other codes, like 404 Not Found (incorrect endpoint or resource), 5xx Server Error (issue on the API's side), or 400 Bad Request (malformed parameters), provide clues about the problem.
• Browser Extensions: If testing in a browser, temporarily disable any extensions that modify network requests or page content, as they can sometimes interfere with API responses.
• CORS Issues (for client-side JavaScript): While REST Countries generally supports CORS, if you encounter a Cross-Origin Resource Sharing error (e.g., Access to fetch at '...' from origin '...' has been blocked by CORS policy) in your browser's console, ensure your serving origin is properly configured or test the request from a server-side environment.
• Rate Limiting: Although REST Countries does not enforce per-user rate limits, making an extremely high volume of requests in a short period could potentially lead to temporary blocking by the host or network infrastructure. If you suspect this, try a slower pace of requests.