curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states?q=maha' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states?include_translations=true' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
import requestsdef get_states_by_country(country_code): response = requests.get( f'https://api.countrystatecity.in/v1/countries/{country_code}/states', headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'} ) if response.ok: states = response.json() print(f'Found {len(states)} states in {country_code}') return states else: print('Country not found or no states available') return []states = get_states_by_country('IN')
const getStatesByCountry = async (countryCode) => { const response = await fetch(`https://api.countrystatecity.in/v1/countries/${countryCode}/states`, { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }); if (response.ok) { const states = await response.json(); console.log(`Found ${states.length} states in ${countryCode}`); return states; } else { console.error('Country not found or no states available'); }};getStatesByCountry('IN');
<?phpfunction getStatesByCountry($countryCode) { $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://api.countrystatecity.in/v1/countries/{$countryCode}/states", 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) { $states = json_decode($response, true); echo "Found " . count($states) . " states in {$countryCode}\n"; return $states; } else { echo "Country not found or no states available\n"; return []; }}$states = getStatesByCountry('IN');?>
package mainimport ( "encoding/json" "fmt" "io/ioutil" "net/http")func getStatesByCountry(countryCode string) []map[string]interface{} { url := fmt.Sprintf("https://api.countrystatecity.in/v1/countries/%s/states", 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) var states []map[string]interface{} json.Unmarshal(body, &states) fmt.Printf("Found %d states in %s\n", len(states), countryCode) return states } else { fmt.Printf("Country not found or no states available\n") return nil }}func main() { states := getStatesByCountry("IN") fmt.Println(states)}
import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import com.google.gson.Gson;import com.google.gson.reflect.TypeToken;import java.lang.reflect.Type;import java.util.List;import java.util.Map;public class StatesByCountry { 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 + "/states")) .header("X-CSCAPI-KEY", "YOUR_API_KEY") .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() == 200) { Gson gson = new Gson(); Type listType = new TypeToken<List<Map<String, Object>>>(){}.getType(); List<Map<String, Object>> states = gson.fromJson(response.body(), listType); System.out.println("Found " + states.size() + " states in " + countryCode); } else { System.out.println("Country not found or no states available"); } }}
require 'net/http'require 'json'def get_states_by_country(country_code) uri = URI("https://api.countrystatecity.in/v1/countries/#{country_code}/states") 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' states = JSON.parse(response.body) puts "Found #{states.length} states in #{country_code}" states else puts 'Country not found or no states available' [] endendstates = get_states_by_country('IN')
{ "error": "Unauthorized. You shouldn't be here."}
States
Get States by Country
Retrieve all states/provinces for a specific country
GET
/
countries
/
{ciso}
/
states
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states?q=maha' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states?include_translations=true' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
import requestsdef get_states_by_country(country_code): response = requests.get( f'https://api.countrystatecity.in/v1/countries/{country_code}/states', headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'} ) if response.ok: states = response.json() print(f'Found {len(states)} states in {country_code}') return states else: print('Country not found or no states available') return []states = get_states_by_country('IN')
const getStatesByCountry = async (countryCode) => { const response = await fetch(`https://api.countrystatecity.in/v1/countries/${countryCode}/states`, { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }); if (response.ok) { const states = await response.json(); console.log(`Found ${states.length} states in ${countryCode}`); return states; } else { console.error('Country not found or no states available'); }};getStatesByCountry('IN');
<?phpfunction getStatesByCountry($countryCode) { $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://api.countrystatecity.in/v1/countries/{$countryCode}/states", 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) { $states = json_decode($response, true); echo "Found " . count($states) . " states in {$countryCode}\n"; return $states; } else { echo "Country not found or no states available\n"; return []; }}$states = getStatesByCountry('IN');?>
package mainimport ( "encoding/json" "fmt" "io/ioutil" "net/http")func getStatesByCountry(countryCode string) []map[string]interface{} { url := fmt.Sprintf("https://api.countrystatecity.in/v1/countries/%s/states", 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) var states []map[string]interface{} json.Unmarshal(body, &states) fmt.Printf("Found %d states in %s\n", len(states), countryCode) return states } else { fmt.Printf("Country not found or no states available\n") return nil }}func main() { states := getStatesByCountry("IN") fmt.Println(states)}
import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import com.google.gson.Gson;import com.google.gson.reflect.TypeToken;import java.lang.reflect.Type;import java.util.List;import java.util.Map;public class StatesByCountry { 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 + "/states")) .header("X-CSCAPI-KEY", "YOUR_API_KEY") .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() == 200) { Gson gson = new Gson(); Type listType = new TypeToken<List<Map<String, Object>>>(){}.getType(); List<Map<String, Object>> states = gson.fromJson(response.body(), listType); System.out.println("Found " + states.size() + " states in " + countryCode); } else { System.out.println("Country not found or no states available"); } }}
require 'net/http'require 'json'def get_states_by_country(country_code) uri = URI("https://api.countrystatecity.in/v1/countries/#{country_code}/states") 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' states = JSON.parse(response.body) puts "Found #{states.length} states in #{country_code}" states else puts 'Country not found or no states available' [] endendstates = get_states_by_country('IN')
{ "error": "Unauthorized. You shouldn't be here."}
Retrieve all states, provinces, regions, and territories for a specific country using the country’s ISO2 code.
Availability: All plans (Community and above). The fields returned vary by tier — see Tier-Based Field Availability below.
Trim and order results: Add ?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.
Additional fields like fips_code, iso3166_2, type, level, parent_id, native, population, translations, and wikiDataId are returned on higher tiers. See Tier-Based Field Availability below.
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states?q=maha' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states?include_translations=true' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
import requestsdef get_states_by_country(country_code): response = requests.get( f'https://api.countrystatecity.in/v1/countries/{country_code}/states', headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'} ) if response.ok: states = response.json() print(f'Found {len(states)} states in {country_code}') return states else: print('Country not found or no states available') return []states = get_states_by_country('IN')
const getStatesByCountry = async (countryCode) => { const response = await fetch(`https://api.countrystatecity.in/v1/countries/${countryCode}/states`, { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }); if (response.ok) { const states = await response.json(); console.log(`Found ${states.length} states in ${countryCode}`); return states; } else { console.error('Country not found or no states available'); }};getStatesByCountry('IN');
<?phpfunction getStatesByCountry($countryCode) { $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://api.countrystatecity.in/v1/countries/{$countryCode}/states", 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) { $states = json_decode($response, true); echo "Found " . count($states) . " states in {$countryCode}\n"; return $states; } else { echo "Country not found or no states available\n"; return []; }}$states = getStatesByCountry('IN');?>
package mainimport ( "encoding/json" "fmt" "io/ioutil" "net/http")func getStatesByCountry(countryCode string) []map[string]interface{} { url := fmt.Sprintf("https://api.countrystatecity.in/v1/countries/%s/states", 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) var states []map[string]interface{} json.Unmarshal(body, &states) fmt.Printf("Found %d states in %s\n", len(states), countryCode) return states } else { fmt.Printf("Country not found or no states available\n") return nil }}func main() { states := getStatesByCountry("IN") fmt.Println(states)}
import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import com.google.gson.Gson;import com.google.gson.reflect.TypeToken;import java.lang.reflect.Type;import java.util.List;import java.util.Map;public class StatesByCountry { 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 + "/states")) .header("X-CSCAPI-KEY", "YOUR_API_KEY") .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() == 200) { Gson gson = new Gson(); Type listType = new TypeToken<List<Map<String, Object>>>(){}.getType(); List<Map<String, Object>> states = gson.fromJson(response.body(), listType); System.out.println("Found " + states.size() + " states in " + countryCode); } else { System.out.println("Country not found or no states available"); } }}
require 'net/http'require 'json'def get_states_by_country(country_code) uri = URI("https://api.countrystatecity.in/v1/countries/#{country_code}/states") 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' states = JSON.parse(response.body) puts "Found #{states.length} states in #{country_code}" states else puts 'Country not found or no states available' [] endendstates = get_states_by_country('IN')
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.
Search filter. Case-insensitive match on name and native fields. Min 2 characters. Requires Starter+ plan.
Required string length: 2 - 100
Example:
"maha"
fields
string
Comma-separated list of fields to include in the response. id is always included. Requires Starter+ plan.
Example:
"name,iso2"
sort
string
Comma-separated sort tokens: field or field:asc|desc. Requires Starter+ plan.
Example:
"name:asc"
locale
string
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.
Required string length: 2 - 7
Pattern: ^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$
Example:
"pt-BR"
include_translations
boolean
default:false
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.
Example:
true
Response
List of states
id
integer<int64>
required
Unique identifier
Example:
4008
name
string
required
State name in English
Example:
"Maharashtra"
country_id
integer<int64>
required
Parent country ID
country_code
string
required
Parent country ISO2 code
Example:
"IN"
iso2
string | null
State/province ISO code
Example:
"MH"
latitude
string | null
Latitude coordinate
Example:
"19.75147980"
longitude
string | null
Longitude coordinate
Example:
"75.71388840"
timezone
string | null
IANA timezone identifier
Example:
"Asia/Kolkata"
fips_code
string | null
FIPS code. Coordinates tier and above.
iso3166_2
string | null
ISO 3166-2 subdivision code. Coordinates tier and above.
type
string | null
Administrative type (e.g., state, province, territory). Coordinates tier and above.
Example:
"state"
level
integer | null
Administrative level. Coordinates tier and above.
parent_id
integer<int64> | null
Parent subdivision ID (for nested administrative structures). Coordinates tier and above.
native
string | null
Name in native language. Coordinates tier and above.
population
integer<int64> | null
Population count. Coordinates tier and above.
translations
string | null
JSON string keyed by language code. Supporter+ plans only. Returned when include_translations=true or when fields=translations explicitly requests it.
wikiDataId
string | null
Wikidata item identifier. Full access level only.
Example:
"Q1191"
localized_name
string | null
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.
Example:
"Maharashtra"
matched_locale
string | null
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.