> ## 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 Country Details

> Retrieve detailed information for a specific country using its ISO2 code

Retrieve detailed information for a specific country using its ISO2 code, including extended geographical, currency, and timezone data.

<Note>**Availability:** All plans (Community and above). The fields returned vary by tier — see **Tier-Based Field Availability** below.</Note>

## Path Parameters

<ParamField path="iso2" type="string" required>
  ISO2 code of the country (e.g., "IN" for India, "US" for United States)
</ParamField>

<Tip>
  **Trim response columns:** Add `?fields=name,iso2,...` to receive only the columns you need. Available on **Supporter+** plans. See the [Field Filtering & Sorting](/api/field-filtering-and-sorting) guide for syntax.
</Tip>

## Authentication

<ParamField header="X-CSCAPI-KEY" type="string" required>
  Your API key for authentication
</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="numeric_code" type="string">
  Three-digit numeric 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="currency_name" type="string">
  Full name of the currency
</ResponseField>

<ResponseField name="currency_symbol" type="string">
  Currency symbol (e.g., \$, €, ₹)
</ResponseField>

<ResponseField name="tld" type="string">
  Top-level domain for the country
</ResponseField>

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

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

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

<ResponseField name="nationality" type="string">
  Demonym for the country's residents
</ResponseField>

<ResponseField name="timezones" type="string">
  JSON string containing timezone information
</ResponseField>

<ResponseField name="translations" type="string">
  JSON string containing country name translations
</ResponseField>

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

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

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

<ResponseField name="emojiU" type="string">
  Unicode representation of the flag emoji. **Coordinates tier and above.**
</ResponseField>

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

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

<ResponseField name="population" type="integer">
  Population estimate. **Coordinates tier and above.**
</ResponseField>

<ResponseField name="gdp" type="integer">
  Nominal GDP in USD. **Coordinates tier and above.**
</ResponseField>

<ResponseField name="area_sq_km" type="integer">
  Surface area in square kilometres. **Coordinates tier and above.**
</ResponseField>

<ResponseField name="postal_code_format" type="string">
  Display template for postal codes (`#` = digit, `@` = letter). **Coordinates tier and above.**
</ResponseField>

<ResponseField name="postal_code_regex" type="string">
  Regex for postal-code validation. **Coordinates tier and above.**
</ResponseField>

<ResponseField name="wikiDataId" type="string">
  Wikidata item identifier. **Full tier only.**
</ResponseField>

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

  ```python Python theme={null}
  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)
  ```

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

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

  ```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 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");
          }
      }
  }
  ```

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

<ResponseExample>
  ```json 200 - Full tier (Professional, Business) theme={null}
  {
    "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"
  }
  ```

  ```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 404 - Not Found theme={null}
  {
    "error": "Country not found."
  }
  ```

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

## Common Use Cases

<AccordionGroup>
  <Accordion title="Localization and Translations">
    Use native names and translations for multi-language applications.

    ```javascript theme={null}
    const getLocalizedCountryName = (country, language = 'en') => {
      if (language === 'native') return country.native;
      
      const translations = JSON.parse(country.translations || '{}');
      return translations[language] || country.name;
    };
    ```
  </Accordion>

  <Accordion title="Timezone Information">
    Parse and use timezone data for scheduling applications.

    ```javascript theme={null}
    const getTimezoneInfo = (country) => {
      const timezones = JSON.parse(country.timezones || '[]');
      return timezones.map(tz => ({
        name: tz.zoneName,
        offset: tz.gmtOffsetName,
        abbreviation: tz.abbreviation
      }));
    };
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  Use this endpoint when you need detailed country information for user profiles, shipping calculations, or localization features.
</Tip>

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