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')
{
"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."
}
Countries Endpoints
Get Country Details
Retrieve detailed information for a specific country using its ISO2 code
GET
/
v1
/
countries
/
{iso2}
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')
{
"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.
See Pricing for plan details.
Availability: All plans (Community and above). The fields returned vary by tier — see Tier-Based Field Availability below.
Path Parameters
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
Your API key for authentication
Response
Unique identifier for the country
Official country name in English
Two-letter ISO 3166-1 alpha-2 country code
Three-letter ISO 3166-1 alpha-3 country code
Three-digit numeric country code
International dialing code for the country
Capital city of the country
Three-letter ISO 4217 currency code
Full name of the currency
Currency symbol (e.g., $, €, ₹)
Top-level domain for the country
Country name in the native language
Geographic region (e.g., Asia, Europe, Americas)
Geographic subregion (e.g., Southern Asia, Western Europe)
Demonym for the country’s residents
JSON string containing timezone information
JSON string containing country name translations
Country’s approximate latitude coordinate
Country’s approximate longitude coordinate
Flag emoji representation
Unicode representation of the flag emoji. Coordinates tier and above.
Geographic region ID (foreign key into
/regions). Basic tier.Geographic subregion ID (foreign key into
/subregions). Basic tier.Population estimate. Coordinates tier and above.
Nominal GDP in USD. Coordinates tier and above.
Surface area in square kilometres. Coordinates tier and above.
Display template for postal codes (
# = digit, @ = letter). Coordinates tier and above.Regex for postal-code validation. Coordinates tier and above.
Wikidata item identifier. Full tier only.
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')
{
"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
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
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 |
Was this page helpful?
⌘I