> ## 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 Data Version

> Check which geographic data release your API responses are currently served from

Returns the version of the underlying geographic dataset currently live behind the API — which upstream release it was exported from, when that release was imported, and a record-count snapshot taken at import time.

<Note>**Availability:** All plans (Community and above) — no tier restriction. The request still counts toward your daily/monthly usage quota like any other endpoint.</Note>

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

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

  def get_data_version():
      """Fetch the geographic data release currently live behind the API."""
      response = requests.get(
        'https://api.countrystatecity.in/v1/meta/data-version',
        headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
      )

      if response.ok:
          return response.json()
      else:
          print('Data version temporarily unavailable')
          return None

  version = get_data_version()
  ```

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

    if (response.ok) {
      return await response.json();
    } else {
      console.error('Data version temporarily unavailable');
      return null;
    }
  };

  getDataVersion();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "dataVersion": "v3.2-export.7-2026.07.30",
    "sourceRelease": "v3.2-export.7",
    "updatedAt": "2026-07-30T09:01:18.000Z",
    "recordCounts": {
      "regions": 6,
      "subregions": 22,
      "countries": 250,
      "states": 5308,
      "cities": 152970
    }
  }
  ```

  ```json 503 - Temporarily unavailable theme={null}
  {
    "status": "error",
    "message": "Data version information is temporarily unavailable."
  }
  ```
</ResponseExample>

## Response headers on every request

Two of the fields above are also stamped as headers on **every** `/v1/*` response, not just this endpoint — so you can track the live data version without an extra request:

| Header | Meaning |
| - | - |
| `X-CSC-Data-Version` | Same value as `dataVersion` above |
| `X-CSC-Data-Updated-At` | Same value as `updatedAt` above |
| `X-Request-ID` | Server-generated UUID, unique per request — include it when contacting support about a specific request |

<Note>
  **This metadata is cached, so it can trail a fresh import.** This route reads through a 5-minute-TTL cache backed by Redis, so right after an import it can report the previous release for up to about 5 minutes while the new data is already being served. The headers are stamped from an in-memory copy that refreshes every 30 seconds on top of that same cache, so they can trail the imported data by about 5.5 minutes — a deliberate tradeoff so stamping them never adds latency or a new failure mode to every request. Both catch up on their own; no action is needed on your side.

  `X-Request-ID` is always present. The two `X-CSC-Data-*` headers are omitted until the in-memory copy has warmed after a server restart. All three appear on error responses too, because they're set before routing rather than per endpoint — see [Errors & Rate Limits](/api/errors).
</Note>

## npm package parity

The [`@countrystatecity/countries`](https://www.npmjs.com/package/@countrystatecity/countries) and [`@countrystatecity/countries-browser`](https://www.npmjs.com/package/@countrystatecity/countries-browser) npm packages ship a `getDataVersion()` loader with the same `dataVersion`/`sourceRelease`/`updatedAt` fields, read from a small bundled `version.json` instead of a network call. See [npm Packages](/api/sdks/npm#data-updates) for usage.

<Warning>
  **Compare `sourceRelease`, not `dataVersion`.** Both sides build `dataVersion` from the same release tag, but they append different dates: the npm package uses the date the release was **published**, while the API uses the date that release was **imported**. An import lands after the release is published, so the two strings usually differ by a day or more even when both sides hold exactly the same data. `sourceRelease` is the same string on both sides, which makes it the reliable parity key.

  For example, the same `v3.2-export.7` release can read as `v3.2-export.7-2026.07.29` in the package and `v3.2-export.7-2026.07.30` from the API.
</Warning>

The package's `recordCounts` is also narrower than the API's: `countries`/`states`/`cities` only, no `regions`/`subregions`.

## Related

<CardGroup cols={2}>
  <Card title="Errors & Rate Limits" icon="triangle-exclamation" href="/api/errors">
    The `status`/`message` envelope used by the 503 response above, plus usage limits by tier.
  </Card>

  <Card title="npm Packages" icon="npm" href="/api/sdks/npm">
    Get the same version info without a network call via `getDataVersion()`.
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /meta/data-version
openapi: 3.0.3
info:
  title: Country State City API
  description: >-
    Geographic data API providing countries, states, cities, timezones,
    currencies, and phone dial codes with tiered access levels.


    ## Authentication

    All endpoints require an API key passed via the `X-CSCAPI-KEY` header. Get
    your free key at [app.countrystatecity.in](https://app.countrystatecity.in).


    ## Pricing & Limits

    The fields returned, endpoints available, and request quotas depend on your
    plan. See current tiers and limits at:


    **[countrystatecity.in/pricing](https://countrystatecity.in/pricing)**


    ## Data Access Levels

    Each plan includes a data access level that controls which fields are
    returned:


    - **Basic** — Core fields: id, name, iso2, iso3, phonecode, capital,
    currency, coordinates, region, timezones, emoji

    - **Coordinates** — Basic + extended metadata (population, tld, nationality,
    currency details, postal codes, etc.)

    - **Full** — All fields including translations (18+ languages) and
    wikiDataId


    Fields restricted to higher tiers are marked in each schema below.


    ## Feature Gating

    Some endpoints require a minimum tier. Restricted endpoints return `403`
    with an `upgradeUrl` when accessed on a lower plan. Check the [pricing
    page](https://countrystatecity.in/pricing) for current feature availability.


    ## Rate Limiting

    Requests exceeding your daily or monthly quota receive a `429` response with
    your current limit, period, tier, and an upgrade URL.


    ## Caching

    Cacheable geographic responses include `Cache-Control`, `ETag`, and
    `X-Cache` (HIT/MISS) headers; send `If-None-Match` on them to receive `304
    Not Modified`. Phone number parsing is never cached (`Cache-Control:
    no-store`, no `ETag`); see each endpoint for exceptions.


    ## Usage Headers

    All `/v1/*` responses include usage and plan headers:

    - `X-CSC-Plan` — your current tier

    - `X-CSC-Daily-Used` / `X-CSC-Daily-Limit` — today's usage vs limit

    - `X-CSC-Monthly-Used` / `X-CSC-Monthly-Limit` — this month's usage vs limit


    Use these to monitor consumption without a separate API call.
  contact:
    name: Darshan Gada (dr5hn)
    email: gadadarshan@gmail.com
    url: https://countrystatecity.in
  license:
    name: Creative Commons Attribution 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  version: 2.4.1
servers:
  - url: https://api.countrystatecity.in/v1
    description: Production API
security: []
tags:
  - name: Countries
    description: Country data — 250+ countries with metadata, coordinates, and translations
  - name: States
    description: State/province/region data — 5,000+ subdivisions
  - name: Cities
    description: City data — 150,000+ cities worldwide
  - name: Postcodes
    description: >-
      Postcode and ZIP code lookup and search. Informational data, not address
      verification.
  - name: Regions
    description: Geographic regions and subregions — continental groupings of countries
  - name: Timezones
    description: >-
      IANA timezone lookup by country, state, or city — includes UTC offset and
      DST status
  - name: Currencies
    description: ISO 4217 currency data — list all currencies or look up by country
  - name: Phone
    description: >-
      International dial codes — list, lookup by country, and E.164 phone number
      parsing
  - name: ISO
    description: >-
      ISO 3166 code lookup and conversion — country (alpha-2/3/numeric) and
      state (ISO 3166-2)
  - name: Search
    description: Typo-tolerant fuzzy search across cities, states, and countries
  - name: Changes
    description: >-
      Data change feed — track additions, removals, and updates to place records
      over time. **Professional and Business plans only.**
  - name: Meta
    description: Information about the dataset release currently served
paths:
  /meta/data-version:
    get:
      tags:
        - Meta
      summary: Get data version
      description: >-
        Returns which geographic data release the API is currently serving.
        Cached for up to about 5 minutes after an import.


        **Availability:** All tiers (counts toward your quota).
      operationId: getDataVersion
      responses:
        '200':
          description: Current data release
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-CSC-Data-Version:
              $ref: '#/components/headers/XCSCDataVersion'
            X-CSC-Data-Updated-At:
              $ref: '#/components/headers/XCSCDataUpdatedAt'
            X-CSC-Plan:
              $ref: '#/components/headers/XCSCPlan'
            X-CSC-Daily-Used:
              $ref: '#/components/headers/XCSCDailyUsed'
            X-CSC-Daily-Limit:
              $ref: '#/components/headers/XCSCDailyLimit'
            X-CSC-Monthly-Used:
              $ref: '#/components/headers/XCSCMonthlyUsed'
            X-CSC-Monthly-Limit:
              $ref: '#/components/headers/XCSCMonthlyLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: Version information temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusError'
              example:
                status: error
                message: Data version information is temporarily unavailable.
      security:
        - ApiKeyAuth: []
components:
  headers:
    XRequestId:
      description: Unique ID for this request
      schema:
        type: string
        format: uuid
        example: 8b4c01b8-60f1-4c29-a105-8dc65ca9925e
    XCSCDataVersion:
      description: Current dataset version. Present when version metadata is available.
      schema:
        type: string
        example: v3.2-export.7-2026.08.24
    XCSCDataUpdatedAt:
      description: >-
        When the current dataset version was published. Present when version
        metadata is available.
      schema:
        type: string
        format: date-time
        example: '2026-08-24T08:15:00.000Z'
    XCSCPlan:
      description: Your current pricing tier
      schema:
        type: string
        enum:
          - community
          - starter
          - supporter
          - professional
          - business
          - legacy
          - custom
        example: supporter
    XCSCDailyUsed:
      description: Number of requests used today
      schema:
        type: integer
        example: 42
    XCSCDailyLimit:
      description: Your daily request limit (or 'unlimited' for custom plans)
      schema:
        type: string
        example: '1000'
    XCSCMonthlyUsed:
      description: Number of requests used this month
      schema:
        type: integer
        example: 850
    XCSCMonthlyLimit:
      description: Your monthly request limit (or 'unlimited' for custom plans)
      schema:
        type: string
        example: '30000'
  schemas:
    DataVersion:
      type: object
      properties:
        dataVersion:
          type: string
          description: >-
            `<source-release>-<YYYY.MM.DD>`; the date is when the release was
            imported into the API. Same value as the `X-CSC-Data-Version`
            header.
          example: v3.2-export.7-2026.07.30
        sourceRelease:
          type: string
          description: >-
            Upstream release tag. Compare this, not `dataVersion`, to check
            parity with the npm packages.
          example: v3.2-export.7
        updatedAt:
          type: string
          format: date-time
          description: When the release was imported (UTC)
          example: '2026-07-30T09:01:18.000Z'
        recordCounts:
          type: object
          description: Row counts snapshotted at import time
          properties:
            regions:
              type: integer
              example: 6
            subregions:
              type: integer
              example: 22
            countries:
              type: integer
              example: 250
            states:
              type: integer
              example: 5308
            cities:
              type: integer
              example: 152970
      required:
        - dataVersion
        - sourceRelease
        - updatedAt
        - recordCounts
    StatusError:
      type: object
      description: Error envelope used by the postcode and meta endpoints.
      properties:
        status:
          type: string
          example: error
        message:
          type: string
        details:
          type: object
          nullable: true
          properties:
            reason:
              type: string
              description: >-
                Machine-readable reason. Check this instead of parsing
                `message`.
          additionalProperties: true
      required:
        - status
        - message
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
        - error
    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: >-
            Daily usage limit exceeded. Please try again tomorrow or contact
            support for higher limits.
        limit:
          type: integer
          description: Your plan's limit for the exceeded period
          example: 100
        period:
          type: string
          enum:
            - daily
            - monthly
          example: daily
        tier:
          type: string
          description: Your current tier
          example: community
        upgradeUrl:
          type: string
          description: URL to upgrade your plan
          example: https://countrystatecity.in/pricing
      required:
        - error
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized. You shouldn't be here.
    RateLimited:
      description: Daily or monthly usage limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            error: >-
              Daily usage limit exceeded. Please try again tomorrow or contact
              support for higher limits.
            limit: 100
            period: daily
            tier: community
            upgradeUrl: https://countrystatecity.in/pricing
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: >-
        API key for authentication. Get your free key at
        [app.countrystatecity.in](https://app.countrystatecity.in).
      name: X-CSCAPI-KEY
      in: header

````

## Related topics

- [TypeScript SDK](/api/sdks/typescript.md)
- [npm Packages](/api/sdks/npm.md)
- [Data Change Feed](/api/endpoints/get-data-changes.md)
- [FAQ](/tools/export-tool/faq.md)
- [Self-hosting and extending CSC data](/database/self-hosting-and-custom-data.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.