> ## 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 Countries

> Retrieve a complete list of all countries with basic information

Retrieve a complete list of all countries with basic information including ISO codes, phone codes, currencies, and regional data.

<Note>**Availability:** All plans (Community and above). The fields returned 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 country
</ResponseField>

<ResponseField name="name" type="string">
  Official country name in English
</ResponseField>

<ResponseField name="iso2" type="string">
  Two-letter ISO 3166-1 alpha-2 country code
</ResponseField>

<ResponseField name="iso3" type="string">
  Three-letter ISO 3166-1 alpha-3 country code
</ResponseField>

<ResponseField name="phonecode" type="string">
  International dialing code for the country
</ResponseField>

<ResponseField name="capital" type="string">
  Capital city of the country
</ResponseField>

<ResponseField name="currency" type="string">
  Three-letter ISO 4217 currency code
</ResponseField>

<ResponseField name="native" type="string">
  Country name in the native language
</ResponseField>

<ResponseField name="emoji" type="string">
  Flag emoji representation
</ResponseField>

<ResponseField name="latitude" type="string">
  Country's approximate latitude
</ResponseField>

<ResponseField name="longitude" type="string">
  Country's approximate longitude
</ResponseField>

<ResponseField name="region" type="string">
  Geographic region name (e.g., Asia, Europe)
</ResponseField>

<ResponseField name="region_id" type="integer">
  Geographic region ID (foreign key into `/regions`)
</ResponseField>

<ResponseField name="subregion" type="string">
  Geographic subregion name (e.g., Southern Asia)
</ResponseField>

<ResponseField name="subregion_id" type="integer">
  Geographic subregion ID (foreign key into `/subregions`)
</ResponseField>

<ResponseField name="timezones" type="string">
  JSON string of timezones (array of `{zoneName, gmtOffset, gmtOffsetName, abbreviation, tzName}`)
</ResponseField>

<Info>Additional fields like `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.</Info>

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

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

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

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

  countries = response.json()
  print(countries)
  ```

  ```javascript JavaScript theme={null}
  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 PHP theme={null}
  <?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);
  ?>
  ```

  ```go Go theme={null}
  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))
  }
  ```

  ```java Java theme={null}
  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());
      }
  }
  ```

  ```ruby Ruby theme={null}
  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)
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Basic tier (Community, Starter, Legacy) theme={null}
  [
    {
      "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\"}]"
    }
  ]
  ```

  ```json 200 - Coordinates tier (Supporter) — basic plus theme={null}
  [
    {
      "id": 101,
      "name": "India",
      "...": "...all basic fields above...",
      "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"
    }
  ]
  ```

  ```json 200 - Full tier (Professional, Business) — coordinates plus theme={null}
  [
    {
      "id": 101,
      "name": "India",
      "...": "...all coordinates fields above...",
      "translations": "{\"kr\":\"인도\",\"de\":\"Indien\",\"es\":\"India\",\"fr\":\"Inde\",\"ja\":\"インド\"}",
      "wikiDataId": "Q668"
    }
  ]
  ```

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

## 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`    |
| **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`                                                                                                                               |

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

## Common Use Cases

<AccordionGroup>
  <Accordion title="Country Selector Dropdown">
    Use this endpoint to populate country selection dropdowns in forms.

    ```javascript theme={null}
    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);
      });
    };
    ```
  </Accordion>

  <Accordion title="Currency Context">
    Get currency information for financial applications.

    ```javascript theme={null}
    const getCurrencyInfo = (countries, countryCode) => {
      const country = countries.find(c => c.iso2 === countryCode);
      return {
        code: country.currency,
        symbol: country.emoji
      };
    };
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  Cache country data locally as it rarely changes. This reduces API calls and improves application performance.
</Tip>