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

# Convert ISO Code

> Translate a country code between ISO 3166-1 alpha-2, alpha-3, and numeric formats

Convert a country code between the three ISO 3166-1 formats in a single call:

* alpha-2 ↔ alpha-3 (e.g. `US` ↔ `USA`)
* alpha-2 ↔ numeric (e.g. `US` ↔ `840`)
* alpha-3 ↔ numeric (e.g. `USA` ↔ `840`)

Useful when an upstream system gives you one format and a downstream service expects another.

<Note>**Availability:** Starter plan and above. Returns `403` on Community plan.</Note>

<Info>
  **Cache reuse:** Conversions share the same cache slot as [`/v1/iso/country`](/api/endpoints/lookup-country-by-iso). A previous `?iso2=US` lookup serves any `?from=iso2&value=US&to=...` conversion without a fresh database hit. The target column is extracted after the cache read, so different `to` values reuse the same slot.

  Numeric inputs `4` and `004` resolve to the same cache slot.
</Info>

## Authentication

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

## Query Parameters

<ParamField query="from" type="string" required>
  Source format. One of `iso2`, `iso3`, `numeric`.
</ParamField>

<ParamField query="to" type="string" required>
  Target format. One of `iso2`, `iso3`, `numeric`. Must differ from `from`.
</ParamField>

<ParamField query="value" type="string" required>
  The code to convert. Must match the format named in `from`:

  * `from=iso2` → 2 letters (e.g. `US`)
  * `from=iso3` → 3 letters (e.g. `USA`)
  * `from=numeric` → 1–3 digits, non-zero (e.g. `840` or `4`)

  Letter codes are auto-uppercased.
</ParamField>

## Response

<ResponseField name="from" type="string">
  Echo of the source format you requested.
</ResponseField>

<ResponseField name="to" type="string">
  Echo of the target format you requested.
</ResponseField>

<ResponseField name="input" type="string">
  Echo of the `value` you sent — useful for matching responses to requests when batching.
</ResponseField>

<ResponseField name="result" type="string">
  The converted code. For `to=numeric`, returned zero-padded to 3 digits (e.g. `"840"`).
</ResponseField>

<RequestExample>
  ```bash cURL (alpha-2 → alpha-3) theme={null}
  curl -X GET 'https://api.countrystatecity.in/v1/iso/country/convert?from=iso2&to=iso3&value=US' \
    -H 'X-CSCAPI-KEY: YOUR_API_KEY'
  ```

  ```bash cURL (alpha-3 → numeric) theme={null}
  curl -X GET 'https://api.countrystatecity.in/v1/iso/country/convert?from=iso3&to=numeric&value=IND' \
    -H 'X-CSCAPI-KEY: YOUR_API_KEY'
  ```

  ```bash cURL (numeric → alpha-2) theme={null}
  curl -X GET 'https://api.countrystatecity.in/v1/iso/country/convert?from=numeric&to=iso2&value=840' \
    -H 'X-CSCAPI-KEY: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ from: 'iso2', to: 'iso3', value: 'DE' });
  const response = await fetch(
    `https://api.countrystatecity.in/v1/iso/country/convert?${params}`,
    { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
  );

  const { result } = await response.json();
  console.log(result); // "DEU"
  ```

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

  response = requests.get(
    'https://api.countrystatecity.in/v1/iso/country/convert',
    params={'from': 'iso2', 'to': 'numeric', 'value': 'JP'},
    headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
  )

  print(response.json()['result'])  # "392"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success (alpha-2 → alpha-3) theme={null}
  {
    "from": "iso2",
    "to": "iso3",
    "input": "US",
    "result": "USA"
  }
  ```

  ```json 200 - Success (alpha-3 → numeric) theme={null}
  {
    "from": "iso3",
    "to": "numeric",
    "input": "IND",
    "result": "356"
  }
  ```

  ```json 400 - Same from/to theme={null}
  {
    "error": "Invalid query parameters: from and to must be different"
  }
  ```

  ```json 400 - Value doesn't match from theme={null}
  {
    "error": "Invalid query parameters: value does not match the format required by from"
  }
  ```

  ```json 400 - Invalid format name theme={null}
  {
    "error": "Invalid query parameters: from: must be one of: iso2, iso3, numeric"
  }
  ```

  ```json 403 - Feature Restricted theme={null}
  {
    "error": "This feature is not available on your current plan.",
    "feature": "isoLookup",
    "upgradeUrl": "https://app.countrystatecity.in/pricing"
  }
  ```

  ```json 404 - Source code unknown theme={null}
  {
    "error": "Country not found for the given code"
  }
  ```

  ```json 404 - Target column null theme={null}
  {
    "error": "No iso3 code available for this country"
  }
  ```
</ResponseExample>

## Related Endpoints

* [Lookup Country by ISO Code](/api/endpoints/lookup-country-by-iso) — return the full country record instead of just the converted code
* [Lookup State by ISO Code](/api/endpoints/lookup-state-by-iso) — ISO 3166-2 subdivision lookup