Get Country Details

Retrieve detailed information for a specific country using its ISO2 code

GET /v1/countries/{iso2}

cURL

curl -X GET 'https://api.countrystatecity.in/v1/countries/IN' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

import requests

def get_country_details(country_code):
    response = requests.get(
      f'https://api.countrystatecity.in/v1/countries/{country_code}',
      headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
    )
    
    if response.ok:
        return response.json()
    else:
        print('Country not found')
        return None

country = get_country_details('IN')
print(country)

const getCountryDetails = async (countryCode) => {
  const response = await fetch(`https://api.countrystatecity.in/v1/countries/${countryCode}`, {
    headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
  });

  if (response.ok) {
    const country = await response.json();
    console.log(country);
    return country;
  } else {
    console.error('Country not found');
  }
};

getCountryDetails('IN');

<?php
$countryCode = 'IN';
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.countrystatecity.in/v1/countries/{$countryCode}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => array(
    'X-CSCAPI-KEY: YOUR_API_KEY'
  ),
));

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($httpCode == 200) {
    $country = json_decode($response, true);
    echo json_encode($country, JSON_PRETTY_PRINT);
} else {
    echo "Country not found";
}
?>

package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
)

func getCountryDetails(countryCode string) {
    url := fmt.Sprintf("https://api.countrystatecity.in/v1/countries/%s", countryCode)
    
    client := &http.Client{}
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Add("X-CSCAPI-KEY", "YOUR_API_KEY")
    
    res, _ := client.Do(req)
    defer res.Body.Close()
    
    if res.StatusCode == 200 {
        body, _ := ioutil.ReadAll(res.Body)
        fmt.Println(string(body))
    } else {
        fmt.Println("Country not found")
    }
}

func main() {
    getCountryDetails("IN")
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class CountryDetails {
    public static void main(String[] args) throws Exception {
        String countryCode = "IN";
        
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.countrystatecity.in/v1/countries/" + countryCode))
            .header("X-CSCAPI-KEY", "YOUR_API_KEY")
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
            
        if (response.statusCode() == 200) {
            System.out.println(response.body());
        } else {
            System.out.println("Country not found");
        }
    }
}

require 'net/http'
require 'json'

def get_country_details(country_code)
  uri = URI("https://api.countrystatecity.in/v1/countries/#{country_code}")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(uri)
  request['X-CSCAPI-KEY'] = 'YOUR_API_KEY'

  response = http.request(request)
  
  if response.code == '200'
    country = JSON.parse(response.body)
    puts JSON.pretty_generate(country)
  else
    puts 'Country not found'
  end
end

get_country_details('IN')

200 - Full tier (Professional, Business)

{
  "id": 101,
  "name": "India",
  "iso3": "IND",
  "numeric_code": "356",
  "iso2": "IN",
  "phonecode": "91",
  "capital": "New Delhi",
  "currency": "INR",
  "currency_name": "Indian rupee",
  "currency_symbol": "₹",
  "tld": ".in",
  "native": "भारत",
  "region": "Asia",
  "region_id": 3,
  "subregion": "Southern Asia",
  "subregion_id": 14,
  "nationality": "Indian",
  "timezones": "[{\"zoneName\":\"Asia/Kolkata\",\"gmtOffset\":19800,\"gmtOffsetName\":\"UTC+05:30\",\"abbreviation\":\"IST\",\"tzName\":\"Indian Standard Time\"}]",
  "translations": "{\"kr\":\"인도\",\"pt-BR\":\"Índia\",\"pt\":\"Índia\",\"nl\":\"India\",\"hr\":\"Indija\",\"fa\":\"هند\",\"de\":\"Indien\",\"es\":\"India\",\"fr\":\"Inde\",\"ja\":\"インド\",\"it\":\"India\",\"cn\":\"印度\",\"tr\":\"Hindistan\"}",
  "latitude": "20.00000000",
  "longitude": "77.00000000",
  "emoji": "🇮🇳",
  "emojiU": "U+1F1EE U+1F1F3",
  "population": 1380004385,
  "gdp": 2870504000000,
  "area_sq_km": 3287263,
  "postal_code_format": "######",
  "postal_code_regex": "^(\\d{6})$",
  "wikiDataId": "Q668"
}

{
  "id": 101,
  "name": "India",
  "iso2": "IN",
  "iso3": "IND",
  "phonecode": "91",
  "capital": "New Delhi",
  "currency": "INR",
  "native": "भारत",
  "emoji": "🇮🇳",
  "latitude": "20.00000000",
  "longitude": "77.00000000",
  "region": "Asia",
  "region_id": 3,
  "subregion": "Southern Asia",
  "subregion_id": 14,
  "timezones": "[{\"zoneName\":\"Asia/Kolkata\",\"gmtOffset\":19800,\"gmtOffsetName\":\"UTC+05:30\",\"abbreviation\":\"IST\",\"tzName\":\"Indian Standard Time\"}]"
}

{
  "error": "Country not found."
}

{
  "error": "Unauthorized. You shouldn't be here."
}

Retrieve detailed information for a specific country using its ISO2 code, including extended geographical, currency, and timezone data.

Availability: All plans (Community and above). The fields returned vary by tier — see Tier-Based Field Availability below.

Path Parameters

iso2 · string · required

ISO2 code of the country (e.g., “IN” for India, “US” for United States)

Trim response columns: Add ?fields=name,iso2,... to receive only the columns you need. Available on Supporter+ plans. See the Field Filtering & Sorting guide for syntax.

Authentication

X-CSCAPI-KEY · string · required

Your API key for authentication

Response

id · integer

Unique identifier for the country

name · string

Official country name in English

iso2 · string

Two-letter ISO 3166-1 alpha-2 country code

iso3 · string

Three-letter ISO 3166-1 alpha-3 country code

numeric_code · string

Three-digit numeric country code

phonecode · string

International dialing code for the country

capital · string

Capital city of the country

currency · string

Three-letter ISO 4217 currency code

currency_name · string

Full name of the currency

currency_symbol · string

Currency symbol (e.g., $, €, ₹)

tld · string

Top-level domain for the country

native · string

Country name in the native language

region · string

Geographic region (e.g., Asia, Europe, Americas)

subregion · string

Geographic subregion (e.g., Southern Asia, Western Europe)

nationality · string

Demonym for the country’s residents

timezones · string

JSON string containing timezone information

translations · string

JSON string containing country name translations

latitude · string

Country’s approximate latitude coordinate

longitude · string

Country’s approximate longitude coordinate

emoji · string

Flag emoji representation

emojiU · string

Unicode representation of the flag emoji. Coordinates tier and above.

region_id · integer

Geographic region ID (foreign key into /regions). Basic tier.

subregion_id · integer

Geographic subregion ID (foreign key into /subregions). Basic tier.

population · integer

Population estimate. Coordinates tier and above.

gdp · integer

Nominal GDP in USD. Coordinates tier and above.

area_sq_km · integer

Surface area in square kilometres. Coordinates tier and above.

postal_code_format · string

Display template for postal codes (# = digit, @ = letter). Coordinates tier and above.

postal_code_regex · string

Regex for postal-code validation. Coordinates tier and above.

wikiDataId · string

Wikidata item identifier. Full tier only.

cURL

curl -X GET 'https://api.countrystatecity.in/v1/countries/IN' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

import requests

def get_country_details(country_code):
    response = requests.get(
      f'https://api.countrystatecity.in/v1/countries/{country_code}',
      headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
    )
    
    if response.ok:
        return response.json()
    else:
        print('Country not found')
        return None

country = get_country_details('IN')
print(country)

const getCountryDetails = async (countryCode) => {
  const response = await fetch(`https://api.countrystatecity.in/v1/countries/${countryCode}`, {
    headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
  });

  if (response.ok) {
    const country = await response.json();
    console.log(country);
    return country;
  } else {
    console.error('Country not found');
  }
};

getCountryDetails('IN');

<?php
$countryCode = 'IN';
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.countrystatecity.in/v1/countries/{$countryCode}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => array(
    'X-CSCAPI-KEY: YOUR_API_KEY'
  ),
));

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($httpCode == 200) {
    $country = json_decode($response, true);
    echo json_encode($country, JSON_PRETTY_PRINT);
} else {
    echo "Country not found";
}
?>

package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
)

func getCountryDetails(countryCode string) {
    url := fmt.Sprintf("https://api.countrystatecity.in/v1/countries/%s", countryCode)
    
    client := &http.Client{}
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Add("X-CSCAPI-KEY", "YOUR_API_KEY")
    
    res, _ := client.Do(req)
    defer res.Body.Close()
    
    if res.StatusCode == 200 {
        body, _ := ioutil.ReadAll(res.Body)
        fmt.Println(string(body))
    } else {
        fmt.Println("Country not found")
    }
}

func main() {
    getCountryDetails("IN")
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class CountryDetails {
    public static void main(String[] args) throws Exception {
        String countryCode = "IN";
        
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.countrystatecity.in/v1/countries/" + countryCode))
            .header("X-CSCAPI-KEY", "YOUR_API_KEY")
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
            
        if (response.statusCode() == 200) {
            System.out.println(response.body());
        } else {
            System.out.println("Country not found");
        }
    }
}

require 'net/http'
require 'json'

def get_country_details(country_code)
  uri = URI("https://api.countrystatecity.in/v1/countries/#{country_code}")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(uri)
  request['X-CSCAPI-KEY'] = 'YOUR_API_KEY'

  response = http.request(request)
  
  if response.code == '200'
    country = JSON.parse(response.body)
    puts JSON.pretty_generate(country)
  else
    puts 'Country not found'
  end
end

get_country_details('IN')

200 - Full tier (Professional, Business)

{
  "id": 101,
  "name": "India",
  "iso3": "IND",
  "numeric_code": "356",
  "iso2": "IN",
  "phonecode": "91",
  "capital": "New Delhi",
  "currency": "INR",
  "currency_name": "Indian rupee",
  "currency_symbol": "₹",
  "tld": ".in",
  "native": "भारत",
  "region": "Asia",
  "region_id": 3,
  "subregion": "Southern Asia",
  "subregion_id": 14,
  "nationality": "Indian",
  "timezones": "[{\"zoneName\":\"Asia/Kolkata\",\"gmtOffset\":19800,\"gmtOffsetName\":\"UTC+05:30\",\"abbreviation\":\"IST\",\"tzName\":\"Indian Standard Time\"}]",
  "translations": "{\"kr\":\"인도\",\"pt-BR\":\"Índia\",\"pt\":\"Índia\",\"nl\":\"India\",\"hr\":\"Indija\",\"fa\":\"هند\",\"de\":\"Indien\",\"es\":\"India\",\"fr\":\"Inde\",\"ja\":\"インド\",\"it\":\"India\",\"cn\":\"印度\",\"tr\":\"Hindistan\"}",
  "latitude": "20.00000000",
  "longitude": "77.00000000",
  "emoji": "🇮🇳",
  "emojiU": "U+1F1EE U+1F1F3",
  "population": 1380004385,
  "gdp": 2870504000000,
  "area_sq_km": 3287263,
  "postal_code_format": "######",
  "postal_code_regex": "^(\\d{6})$",
  "wikiDataId": "Q668"
}

{
  "id": 101,
  "name": "India",
  "iso2": "IN",
  "iso3": "IND",
  "phonecode": "91",
  "capital": "New Delhi",
  "currency": "INR",
  "native": "भारत",
  "emoji": "🇮🇳",
  "latitude": "20.00000000",
  "longitude": "77.00000000",
  "region": "Asia",
  "region_id": 3,
  "subregion": "Southern Asia",
  "subregion_id": 14,
  "timezones": "[{\"zoneName\":\"Asia/Kolkata\",\"gmtOffset\":19800,\"gmtOffsetName\":\"UTC+05:30\",\"abbreviation\":\"IST\",\"tzName\":\"Indian Standard Time\"}]"
}

{
  "error": "Country not found."
}

{
  "error": "Unauthorized. You shouldn't be here."
}

Common Use Cases

Localization and Translations

Use native names and translations for multi-language applications.

const getLocalizedCountryName = (country, language = 'en') => {
  if (language === 'native') return country.native;
  
  const translations = JSON.parse(country.translations || '{}');
  return translations[language] || country.name;
};

Timezone Information

Parse and use timezone data for scheduling applications.

const getTimezoneInfo = (country) => {
  const timezones = JSON.parse(country.timezones || '[]');
  return timezones.map(tz => ({
    name: tz.zoneName,
    offset: tz.gmtOffsetName,
    abbreviation: tz.abbreviation
  }));
};

Use this endpoint when you need detailed country information for user profiles, shipping calculations, or localization features.

Tier-Based Field Availability

Tier	Plans	Fields
Basic	Community, Starter, Legacy	id, name, iso2, iso3, phonecode, capital, currency, native, emoji, latitude, longitude, region, region_id, subregion, subregion_id, timezones
Coordinates	Supporter	All Basic + numeric_code, currency_name, currency_symbol, tld, nationality, population, gdp, area_sq_km, postal_code_format, postal_code_regex, emojiU
Full	Professional, Business	All Coordinates + translations, wikiDataId

See Pricing for plan details.