> ## Documentation Index
> Fetch the complete documentation index at: https://docs.countrystatecity.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Get All States

> Retrieve a complete list of all states, provinces, and regions worldwide

Retrieve a complete list of all states, provinces, regions, and territories from around the world with basic geographical information.

<Note>**Availability:** Supporter plan and above. Calling `/states` without filtering by country (`bulkStates`) is gated to Supporter+. Community/Starter users must call `/countries/{iso2}/states` instead. The fields returned also vary by tier — see **Tier-Based Field Availability** below.</Note>

<Tip>
  **Trim and order results:** Add `?fields=` to limit columns returned, or `?sort=` to order the list. Both are available on **Supporter+** plans. See the [Field Filtering & Sorting](/api/field-filtering-and-sorting) guide for syntax and per-entity sortable fields.
</Tip>

## Authentication

<ParamField header="X-CSCAPI-KEY" type="string" required>
  Your API key for authentication
</ParamField>

## Query Parameters

<ParamField query="q" type="string">
  Search filter on name. Case-insensitive match on `name` and `native` fields. Minimum 2 characters. **Requires Supporter+ plan.** Without this parameter, all results are returned (no plan restriction for search).
</ParamField>

## Response

<ResponseField name="id" type="integer">
  Unique identifier for the state/province
</ResponseField>

<ResponseField name="name" type="string">
  Official name of the state/province
</ResponseField>

<ResponseField name="country_id" type="integer">
  Unique identifier of the parent country
</ResponseField>

<ResponseField name="country_code" type="string">
  ISO2 code of the parent country
</ResponseField>

<ResponseField name="iso2" type="string">
  ISO2 code for the state/province
</ResponseField>

<ResponseField name="latitude" type="string">
  Approximate latitude coordinate of the state/province center
</ResponseField>

<ResponseField name="longitude" type="string">
  Approximate longitude coordinate of the state/province center
</ResponseField>

<ResponseField name="timezone" type="string">
  IANA timezone identifier (e.g., `"Asia/Kolkata"`)
</ResponseField>

<ResponseField name="type" type="string">
  Administrative division type (e.g., `"state"`, `"province"`, `"region"`). **Coordinates tier and above.**
</ResponseField>

<Info>Additional fields like `fips_code`, `iso3166_2`, `level`, `parent_id`, `native`, `population`, `translations`, and `wikiDataId` are returned on higher tiers. See **Tier-Based Field Availability** below.</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://api.countrystatecity.in/v1/states' \
    -H 'X-CSCAPI-KEY: YOUR_API_KEY'
  ```

  ```bash cURL (with search) theme={null}
  curl -X GET 'https://api.countrystatecity.in/v1/states?q=texas' \
    -H 'X-CSCAPI-KEY: YOUR_API_KEY'
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
    'https://api.countrystatecity.in/v1/states',
    headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
  )

  states = response.json()
  print(f'Found {len(states)} states')
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.countrystatecity.in/v1/states', {
    headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
  });

  const states = await response.json();
  console.log(`Found ${states.length} states`);
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

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

  $response = curl_exec($curl);
  curl_close($curl);

  $states = json_decode($response, true);
  echo "Found " . count($states) . " states\n";
  ?>
  ```

  ```go Go theme={null}
  package main

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

  func main() {
      url := "https://api.countrystatecity.in/v1/states"
      
      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)
      
      var states []map[string]interface{}
      json.Unmarshal(body, &states)
      
      fmt.Printf("Found %d states\n", len(states))
  }
  ```

  ```java Java theme={null}
  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 AllStates {
      public static void main(String[] args) throws Exception {
          HttpClient client = HttpClient.newHttpClient();
          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create("https://api.countrystatecity.in/v1/states"))
              .header("X-CSCAPI-KEY", "YOUR_API_KEY")
              .build();

          HttpResponse<String> response = client.send(request,
              HttpResponse.BodyHandlers.ofString());
              
          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");
      }
  }
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'

  uri = URI("https://api.countrystatecity.in/v1/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)
  states = JSON.parse(response.body)

  puts "Found #{states.length} states"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Basic tier (Community, Starter, Legacy) theme={null}
  [
    {
      "id": 4008,
      "name": "Maharashtra",
      "country_id": 101,
      "country_code": "IN",
      "iso2": "MH",
      "latitude": "19.75147980",
      "longitude": "75.71388840",
      "timezone": "Asia/Kolkata"
    }
  ]
  ```

  ```json 200 - Coordinates tier (Supporter) — basic plus theme={null}
  [
    {
      "id": 4008,
      "name": "Maharashtra",
      "country_id": 101,
      "country_code": "IN",
      "iso2": "MH",
      "latitude": "19.75147980",
      "longitude": "75.71388840",
      "timezone": "Asia/Kolkata",
      "fips_code": "16",
      "iso3166_2": "IN-MH",
      "type": "state",
      "level": 1,
      "parent_id": null,
      "native": "महाराष्ट्र",
      "population": 112374333
    }
  ]
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "error": "Unauthorized. You shouldn't be here."
  }
  ```
</ResponseExample>

## Common Use Cases

<AccordionGroup>
  <Accordion title="Global State Analysis">
    Analyze administrative divisions across different countries.

    ```javascript theme={null}
    const analyzeStateTypes = (states) => {
      const typeCount = states.reduce((acc, state) => {
        acc[state.type] = (acc[state.type] || 0) + 1;
        return acc;
      }, {});
      
      console.log('State types distribution:', typeCount);
      return typeCount;
    };
    ```
  </Accordion>

  <Accordion title="Geographic Mapping">
    Use coordinate data for mapping applications.

    ```javascript theme={null}
    const getStatesBounds = (states) => {
      const lats = states.map(s => parseFloat(s.latitude));
      const lngs = states.map(s => parseFloat(s.longitude));
      
      return {
        north: Math.max(...lats),
        south: Math.min(...lats),
        east: Math.max(...lngs),
        west: Math.min(...lngs)
      };
    };
    ```
  </Accordion>
</AccordionGroup>

<Warning>
  This endpoint returns a large dataset (5,299+ states). Consider using the filtered endpoints for better performance in most applications.
</Warning>

## Tier-Based Field Availability

| Tier            | Plans                      | Fields                                                                                         |
| --------------- | -------------------------- | ---------------------------------------------------------------------------------------------- |
| **Basic**       | Community, Starter, Legacy | `id`, `name`, `iso2`, `country_id`, `country_code`, `latitude`, `longitude`, `timezone`        |
| **Coordinates** | Supporter                  | All Basic **+** `fips_code`, `iso3166_2`, `type`, `level`, `parent_id`, `native`, `population` |
| **Full**        | Professional, Business     | All Coordinates **+** `translations`, `wikiDataId`                                             |

See [Pricing](https://app.countrystatecity.in/pricing) for plan details.