curl -X GET 'https://api.countrystatecity.in/v1/countries/IN' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN?include_translations=true' \
-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."
}
Get Country Details
Retrieve detailed information for a specific country using its ISO2 code
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN?include_translations=true' \
-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."
}
?fields=name,iso2,... to receive only the columns you need. Available on Starter+ plans. See the Field Filtering & Sorting guide for syntax.curl -X GET 'https://api.countrystatecity.in/v1/countries/IN' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN?include_translations=true' \
-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
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
const getTimezoneInfo = (country) => {
const timezones = JSON.parse(country.timezones || '[]');
return timezones.map(tz => ({
name: tz.zoneName,
offset: tz.gmtOffsetName,
abbreviation: tz.abbreviation
}));
};
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 |
| Full | Supporter, Professional, Business | All Basic + numeric_code, currency_name, currency_symbol, tld, nationality, population, gdp, area_sq_km, postal_code_format, postal_code_regex, emojiU, translations, wikiDataId, localized_name, matched_locale |
translations is part of Full access but is not returned by default: add include_translations=true, or name it in ?fields=. localized_name and matched_locale are computed from the translations rather than stored, and appear only when you pass locale. See Localized Place Names.
See Pricing for plan details.Authorizations
API key for authentication. Get your free key at app.countrystatecity.in.
Path Parameters
ISO2 code (e.g., IN) or numeric ID of the country
"IN"
Query Parameters
Comma-separated list of fields to include in the response. id is always included. Requires Starter+ plan.
"name,iso2,capital"
BCP 47 locale code (e.g. pt-BR) to request a localized name. Adds localized_name (resolved via exact locale → base language → native name → English name fallback) and matched_locale (which tier matched) to the result; name is unaffected. Supporter+ plans only — silently omitted (not an error) on lower tiers. A malformed value is rejected with a 400 on every tier.
2 - 7^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$"pt-BR"
When true, includes the full translations field (JSON string keyed by language code). Supporter+ plans only — silently omitted (not an error) on lower tiers. Note that an explicit fields=translations also returns the field and takes precedence over this flag.
true
Response
Country details
Country object. Fields returned depend on your plan's data access level.
Unique identifier
101
Country name in English
"India"
ISO 3166-1 alpha-2 code
"IN"
ISO 3166-1 alpha-3 code
"IND"
International dialling code
"91"
Capital city name
"New Delhi"
Currency code
"INR"
Country name in native language
"भारत"
Flag emoji
"🇮🇳"
Latitude coordinate
"20.00000000"
Longitude coordinate
"77.00000000"
Geographic region
"Asia"
Region identifier
Geographic subregion
"Southern Asia"
Subregion identifier
JSON string of timezone objects with zoneName, gmtOffset, gmtOffsetName, abbreviation, tzName
"[{\"zoneName\":\"Asia/Kolkata\",\"gmtOffset\":19800,\"gmtOffsetName\":\"UTC+05:30\",\"abbreviation\":\"IST\",\"tzName\":\"Indian Standard Time\"}]"
ISO 3166-1 numeric code. Coordinates tier and above.
"356"
Full currency name. Coordinates tier and above.
"Indian rupee"
Currency symbol. Coordinates tier and above.
"₹"
Top-level domain. Coordinates tier and above.
".in"
Nationality/demonym. Coordinates tier and above.
"Indian"
Population count. Coordinates tier and above.
Gross domestic product (USD). Coordinates tier and above.
Area in square kilometres. Coordinates tier and above.
Postal code format pattern. Coordinates tier and above.
Postal code validation regex. Coordinates tier and above.
Flag emoji Unicode points. Coordinates tier and above.
"U+1F1EE U+1F1F3"
JSON string keyed by language code. Supporter+ plans only. Returned when include_translations=true or when fields=translations explicitly requests it.
Wikidata item identifier. Full access level only.
"Q668"
Name resolved via the locale query param's fallback chain (exact locale → base language → native name → English name). Only present when locale was supplied. Supporter+ plans only — silently omitted on lower tiers.
"Índia"
Which fallback tier satisfied the locale request: the exact locale (e.g. pt-BR), its base language (e.g. pt), native, or en (English fallback). Only present when locale was supplied. Supporter+ plans only — silently omitted on lower tiers.
"pt"