GET /api/country

A caching proxy endpoint that retrieves country information from the RestCountries API. This endpoint exists to provide consistent caching behavior for country lookups.

Endpoint

GET /api/country

Query parameters

code

string

required

The ISO 3166-1 alpha-2 or alpha-3 country code (e.g., “PL” or “POL”).

Response

Returns the raw response from RestCountries API v3.1. The response is an array containing country data.

[0]

object

required

Country data object from RestCountries API

Show Country data structure

name

object

Contains country name variations including common and official

cca2

string

ISO 3166-1 alpha-2 code

cca3

string

ISO 3166-1 alpha-3 code

latlng

number[]

Coordinates as [latitude, longitude]

borders

string[]

Array of alpha-3 codes for bordering countries

area

number

Country area in square kilometers

population

number

Country population

flags

object

Contains svg and png flag URLs

region

string

Geographic region

subregion

string

Geographic subregion

Caching

This endpoint uses Next.js’s force-cache strategy:

const res = await fetch(`https://restcountries.com/v3.1/alpha/${code}`, {
    cache: 'force-cache'
});

From app/api/country/route.ts:11-13 Country data is cached indefinitely to reduce external API calls and improve performance.

Example request

curl https://yourdomain.com/api/country?code=PL

Example response

[
  {
    "name": {
      "common": "Poland",
      "official": "Republic of Poland",
      "nativeName": {
        "pol": {
          "official": "Rzeczpospolita Polska",
          "common": "Polska"
        }
      }
    },
    "cca2": "PL",
    "cca3": "POL",
    "latlng": [52, 20],
    "borders": ["BLR", "CZE", "DEU", "LTU", "RUS", "SVK", "UKR"],
    "area": 312679,
    "population": 37950802,
    "flags": {
      "png": "https://flagcdn.com/w320/pl.png",
      "svg": "https://flagcdn.com/pl.svg"
    },
    "region": "Europe",
    "subregion": "Central Europe",
    "capital": ["Warsaw"],
    "languages": {
      "pol": "Polish"
    },
    "currencies": {
      "PLN": {
        "name": "Polish złoty",
        "symbol": "zł"
      }
    }
  }
]

The response includes many additional fields beyond what’s shown above. Refer to the RestCountries API documentation for the complete schema.

Error responses

Missing country code:

{
  "error": "Country code is required"
}

Status: 400 Failed to fetch from RestCountries:

{
  "error": "Internal Server Error"
}

Status: 500

Code example

// Fetch country details by code
const response = await fetch('/api/country?code=PL');
const [countryData] = await response.json();

console.log(countryData.name.common); // "Poland"
console.log(countryData.capital[0]); // "Warsaw"

Use cases

This endpoint is primarily used by:

Country search/autocomplete components
Guess validation in the game interface
Displaying country details after user selection

Setup

Architecture

API Reference

Contributing

Endpoint

Query parameters

Response

Caching

Example request

Example response

Error responses

Code example

Use cases

Build docs developers (and LLMs) love

Setup

Architecture

API Reference

Contributing

Documentation Index

​Endpoint

​Query parameters

​Response

​Caching

​Example request

​Example response

​Error responses

​Code example

​Use cases

Build docs developers (and LLMs) love

Endpoint

Query parameters

Response

Caching

Example request

Example response

Error responses

Code example

Use cases