curl -X GET 'https://api.countrystatecity.in/v1/countries' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries?q=india' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries?include_translations=true' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
import requests
response = requests.get(
'https://api.countrystatecity.in/v1/countries',
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
countries = response.json()
print(countries)
const response = await fetch('https://api.countrystatecity.in/v1/countries', {
headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
});
const countries = await response.json();
console.log(countries);
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.countrystatecity.in/v1/countries',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'X-CSCAPI-KEY: YOUR_API_KEY'
),
));
$response = curl_exec($curl);
curl_close($curl);
$countries = json_decode($response, true);
echo json_encode($countries, JSON_PRETTY_PRINT);
?>
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
url := "https://api.countrystatecity.in/v1/countries"
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()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Countries {
public static void main(String[] args) throws Exception {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.countrystatecity.in/v1/countries"))
.header("X-CSCAPI-KEY", "YOUR_API_KEY")
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
require 'net/http'
require 'json'
uri = URI("https://api.countrystatecity.in/v1/countries")
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)
countries = JSON.parse(response.body)
puts JSON.pretty_generate(countries)
[
{
"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\"}]"
}
]
[
{
"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\"}]",
"numeric_code": "356",
"currency_name": "Indian rupee",
"currency_symbol": "₹",
"tld": ".in",
"nationality": "Indian",
"population": 1380004385,
"gdp": 2870504000000,
"area_sq_km": 3287263,
"postal_code_format": "######",
"postal_code_regex": "^(\\d{6})$",
"emojiU": "U+1F1EE U+1F1F3",
"translations": "{\"kr\":\"인도\",\"de\":\"Indien\",\"es\":\"India\",\"fr\":\"Inde\",\"ja\":\"インド\"}",
"wikiDataId": "Q668"
}
]
{
"error": "Unauthorized. You shouldn't be here."
}
Get All Countries
Retrieve a complete list of all countries with basic information
curl -X GET 'https://api.countrystatecity.in/v1/countries' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries?q=india' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries?include_translations=true' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
import requests
response = requests.get(
'https://api.countrystatecity.in/v1/countries',
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
countries = response.json()
print(countries)
const response = await fetch('https://api.countrystatecity.in/v1/countries', {
headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
});
const countries = await response.json();
console.log(countries);
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.countrystatecity.in/v1/countries',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'X-CSCAPI-KEY: YOUR_API_KEY'
),
));
$response = curl_exec($curl);
curl_close($curl);
$countries = json_decode($response, true);
echo json_encode($countries, JSON_PRETTY_PRINT);
?>
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
url := "https://api.countrystatecity.in/v1/countries"
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()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Countries {
public static void main(String[] args) throws Exception {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.countrystatecity.in/v1/countries"))
.header("X-CSCAPI-KEY", "YOUR_API_KEY")
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
require 'net/http'
require 'json'
uri = URI("https://api.countrystatecity.in/v1/countries")
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)
countries = JSON.parse(response.body)
puts JSON.pretty_generate(countries)
[
{
"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\"}]"
}
]
[
{
"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\"}]",
"numeric_code": "356",
"currency_name": "Indian rupee",
"currency_symbol": "₹",
"tld": ".in",
"nationality": "Indian",
"population": 1380004385,
"gdp": 2870504000000,
"area_sq_km": 3287263,
"postal_code_format": "######",
"postal_code_regex": "^(\\d{6})$",
"emojiU": "U+1F1EE U+1F1F3",
"translations": "{\"kr\":\"인도\",\"de\":\"Indien\",\"es\":\"India\",\"fr\":\"Inde\",\"ja\":\"インド\"}",
"wikiDataId": "Q668"
}
]
{
"error": "Unauthorized. You shouldn't be here."
}
?fields= to limit columns returned, or ?sort= to order the list. Both are available on Starter+ plans. See the Field Filtering & Sorting guide for syntax and per-entity sortable fields.numeric_code, currency_name, currency_symbol, tld, nationality, population, gdp, area_sq_km, postal_code_format, postal_code_regex, emojiU, translations, and wikiDataId are returned on higher tiers. See the Tier-Based Field Availability section below.curl -X GET 'https://api.countrystatecity.in/v1/countries' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries?q=india' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries?include_translations=true' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
import requests
response = requests.get(
'https://api.countrystatecity.in/v1/countries',
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
countries = response.json()
print(countries)
const response = await fetch('https://api.countrystatecity.in/v1/countries', {
headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
});
const countries = await response.json();
console.log(countries);
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.countrystatecity.in/v1/countries',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'X-CSCAPI-KEY: YOUR_API_KEY'
),
));
$response = curl_exec($curl);
curl_close($curl);
$countries = json_decode($response, true);
echo json_encode($countries, JSON_PRETTY_PRINT);
?>
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
url := "https://api.countrystatecity.in/v1/countries"
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()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Countries {
public static void main(String[] args) throws Exception {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.countrystatecity.in/v1/countries"))
.header("X-CSCAPI-KEY", "YOUR_API_KEY")
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
require 'net/http'
require 'json'
uri = URI("https://api.countrystatecity.in/v1/countries")
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)
countries = JSON.parse(response.body)
puts JSON.pretty_generate(countries)
[
{
"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\"}]"
}
]
[
{
"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\"}]",
"numeric_code": "356",
"currency_name": "Indian rupee",
"currency_symbol": "₹",
"tld": ".in",
"nationality": "Indian",
"population": 1380004385,
"gdp": 2870504000000,
"area_sq_km": 3287263,
"postal_code_format": "######",
"postal_code_regex": "^(\\d{6})$",
"emojiU": "U+1F1EE U+1F1F3",
"translations": "{\"kr\":\"인도\",\"de\":\"Indien\",\"es\":\"India\",\"fr\":\"Inde\",\"ja\":\"インド\"}",
"wikiDataId": "Q668"
}
]
{
"error": "Unauthorized. You shouldn't be here."
}
Tier-Based Field Availability
The fields returned depend on your plan’s data access level.| 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.
Common Use Cases
Country Selector Dropdown
Country Selector Dropdown
const populateCountryDropdown = async () => {
const countries = await fetch('/api/countries').then(r => r.json());
const select = document.getElementById('country-select');
countries.forEach(country => {
const option = document.createElement('option');
option.value = country.iso2;
option.textContent = country.name;
select.appendChild(option);
});
};
Currency Context
Currency Context
const getCurrencyInfo = (countries, countryCode) => {
const country = countries.find(c => c.iso2 === countryCode);
return {
code: country.currency,
symbol: country.emoji
};
};
Authorizations
API key for authentication. Get your free key at app.countrystatecity.in.
Query Parameters
Search filter. Case-insensitive match on name and native fields. Min 2 characters. Requires Starter+ plan.
2 - 100"india"
Comma-separated list of fields to include in the response. id is always included. Requires Starter+ plan.
"name,iso2,iso3"
Comma-separated sort tokens: field or field:asc|desc. E.g. name:asc,iso2:desc. Requires Starter+ plan; you can sort only by fields your plan returns (e.g. population needs Supporter+).
"name:asc"
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 each 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
List of countries
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"