Data Change Feed

curl 'https://api.countrystatecity.in/v1/changes?start_date=2026-08-01T00:00:00Z&country_code=IN&limit=100' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

import requests

response = requests.get(
    'https://api.countrystatecity.in/v1/changes',
    params={'start_date': '2026-08-01T00:00:00Z', 'country_code': 'IN'},
    headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'},
)
response.raise_for_status()
page = response.json()

{
  "results": [
    {
      "change_id": "6b30c790-c46f-4a0f-b7f2-ea1a1a9d8362",
      "data_version": "v3.2-export.7-2026.08.24",
      "changed_at": "2026-08-24T08:15:00.000Z",
      "place_type": "city",
      "place_id": "57606",
      "change_type": "renamed",
      "old_values": {},
      "new_values": {}
    }
  ],
  "next_page_token": "<string>"
}

{
  "status": "error",
  "message": "start_date is older than the earliest available change. Changes are kept for 90 days.",
  "details": {
    "earliestAvailableDate": "2026-05-26T00:00:00.000Z"
  }
}

{
  "error": "Unauthorized. You shouldn't be here."
}

{
  "status": "error",
  "message": "This feature is not available on your current plan.",
  "details": {
    "feature": "dataChangeFeed",
    "currentTier": "supporter",
    "requiredTier": "professional",
    "upgradeUrl": "https://countrystatecity.in/pricing"
  }
}

{
  "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"
}

GET

changes

curl 'https://api.countrystatecity.in/v1/changes?start_date=2026-08-01T00:00:00Z&country_code=IN&limit=100' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

import requests

response = requests.get(
    'https://api.countrystatecity.in/v1/changes',
    params={'start_date': '2026-08-01T00:00:00Z', 'country_code': 'IN'},
    headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'},
)
response.raise_for_status()
page = response.json()

{
  "results": [
    {
      "change_id": "6b30c790-c46f-4a0f-b7f2-ea1a1a9d8362",
      "data_version": "v3.2-export.7-2026.08.24",
      "changed_at": "2026-08-24T08:15:00.000Z",
      "place_type": "city",
      "place_id": "57606",
      "change_type": "renamed",
      "old_values": {},
      "new_values": {}
    }
  ],
  "next_page_token": "<string>"
}

{
  "status": "error",
  "message": "start_date is older than the earliest available change. Changes are kept for 90 days.",
  "details": {
    "earliestAvailableDate": "2026-05-26T00:00:00.000Z"
  }
}

{
  "error": "Unauthorized. You shouldn't be here."
}

{
  "status": "error",
  "message": "This feature is not available on your current plan.",
  "details": {
    "feature": "dataChangeFeed",
    "currentTier": "supporter",
    "requiredTier": "professional",
    "upgradeUrl": "https://countrystatecity.in/pricing"
  }
}

{
  "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"
}

If your app stores Country State City data in its own database, a full download is wasteful when only a few places changed. The change feed returns the countries, states, and cities that were added, removed, or updated so you can apply only those changes.

Available on Professional and Business plans. Returns 403 on Community, Starter, Supporter, and Legacy plans. Compare plans to add the change feed to your API key.

When to use it

Use the feed to keep a local search index, checkout form, analytics database, or cached copy up to date. Every change has a stable change_id, the affected place_id, and the data_version that produced it. Changes are available for 90 days. Run your sync regularly and save the change_id values you have applied so retrying a page cannot create duplicates.

Change types

Value	Meaning
`added`	A new place was added.
`removed`	A place was removed.
`renamed`	Its name changed.
`place_group_changed`	Its region, administrative type, or city kind changed.
`parent_changed`	A state moved to another country, or a city moved to another state/country.
`coordinates_changed`	Its latitude or longitude changed.
`other_fields_changed`	Another public field changed.

When several fields change in one release, the record has one main change_type, but old_values and new_values include every changed field.

Response

The API returns changes from oldest to newest.

200 - Renamed city

{
  "results": [
    {
      "change_id": "6b30c790-c46f-4a0f-b7f2-ea1a1a9d8362",
      "data_version": "v3.2-export.7-2026.08.24",
      "changed_at": "2026-08-24T08:15:00.000Z",
      "place_type": "city",
      "place_id": "132649",
      "change_type": "renamed",
      "old_values": { "name": "Bombay" },
      "new_values": { "name": "Mumbai" }
    }
  ],
  "next_page_token": "H2gwOstvc3hy5O7cW1bK0T5S1m4f8h2wYQ"
}

old_values and new_values contain only fields allowed for your API key. The endpoint is not cached, so it does not return ETag or X-Cache.

Read every page safely

The first request fixes the result set. Later pages do not suddenly include a release published while you are syncing. After the last page, start a new request to collect newer changes. For page two and later, send the token by itself. Do not change the original filters.

JavaScript

let url = new URL('https://api.countrystatecity.in/v1/changes');
url.searchParams.set('start_date', '2026-08-01T00:00:00Z');
url.searchParams.set('country_code', 'IN');
url.searchParams.set('limit', '100');

while (url) {
  const response = await fetch(url, {
    headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
  });

  if (!response.ok) throw new Error(await response.text());
  const page = await response.json();

  for (const change of page.results) {
    console.log(change);
    // Apply it to your database and save change.change_id.
  }

  url = page.next_page_token
    ? new URL(`https://api.countrystatecity.in/v1/changes?next_page_token=${encodeURIComponent(page.next_page_token)}`)
    : null;
}

curl 'https://api.countrystatecity.in/v1/changes?start_date=2026-08-01T00:00:00Z&country_code=IN&limit=100' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

import requests

response = requests.get(
    'https://api.countrystatecity.in/v1/changes',
    params={'start_date': '2026-08-01T00:00:00Z', 'country_code': 'IN'},
    headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'},
)
response.raise_for_status()
page = response.json()

Recover from errors

If start_date is older than the retained data, use details.earliestAvailableDate to restart from the oldest available change:

400 - Start date is too old

{
  "status": "error",
  "message": "start_date is older than the earliest available change. Changes are kept for 90 days.",
  "details": {
    "earliestAvailableDate": "2026-05-26T00:00:00.000Z"
  }
}

If a token expires, is changed, or is invalid, start again with start_date and no token. Reusing saved change_id values prevents duplicate work. If your sync has been offline for more than 90 days, download a fresh full dataset before continuing. Lower plans receive a plan-gate response:

403 - Professional plan required

{
  "status": "error",
  "message": "This feature is not available on your current plan.",
  "details": {
    "feature": "dataChangeFeed",
    "currentTier": "supporter",
    "requiredTier": "professional",
    "upgradeUrl": "https://app.countrystatecity.in/pricing"
  }
}

Start syncing changes

Compare API plans

Choose Professional or Business to keep your database current with small incremental requests.

Get Data Version

Check which dataset release your API responses use.

Authorizations

X-CSCAPI-KEY

string

header

required

API key for authentication. Get your free key at app.countrystatecity.in.

Query Parameters

start_date

string<date-time>

Return changes at or after this ISO 8601 timestamp. A date older than the earliest retained change returns 400 with details.earliestAvailableDate.

Example:

"2026-08-01T00:00:00Z"

place_type

enum<string>

Return changes for one place type

Available options:

country,

state,

city

Example:

"city"

country_code

string

Return changes for a country and its states and cities. Uses an ISO 3166-1 alpha-2 code.

Required string length: 2

Pattern: ^[A-Za-z]{2}$

Example:

"IN"

change_type

enum<string>

Return one kind of change

Available options:

added,

removed,

renamed,

place_group_changed,

parent_changed,

coordinates_changed,

other_fields_changed

Example:

"renamed"

limit

integer

default:50

Maximum records per page (1–100)

Required range: 1 <= x <= 100

Example:

50

next_page_token

string

Opaque cursor returned by the previous page. It expires after 24 hours. Omit the original filters, or resend all of them unchanged.

Required string length: 1 - 4096

Pattern: ^[A-Za-z0-9_-]+$

Response

A page from the fixed change-feed snapshot. This endpoint is not cached and does not return Cache-Control, ETag, or X-Cache.

results

object[]

required

Show child attributes

next_page_token

string | null

required

Opaque cursor for the next page, or null after the last page.

Maximum string length: 4096

Pattern: ^[A-Za-z0-9_-]+$

Countries

States

Cities

Postcodes

Regions

Timezones

Currencies

Phone

ISO Codes

Search

Data Changes

GraphQL API

Meta

When to use it

Change types

Response

Read every page safely

Recover from errors

Start syncing changes

Compare API plans

Get Data Version

Authorizations

Query Parameters

Response

​When to use it

​Change types

​Response

​Read every page safely

​Recover from errors

​Start syncing changes

Compare API plans

Get Data Version

Authorizations

Query Parameters

Response

When to use it

Change types

Response

Read every page safely

Recover from errors

Start syncing changes