{ "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.\n\n## Authentication\nAll endpoints require an API key passed via the `X-CSCAPI-KEY` header. Get your free key at [app.countrystatecity.in](https://app.countrystatecity.in).\n\n## Pricing & Limits\nThe fields returned, endpoints available, and request quotas depend on your plan. See current tiers and limits at:\n\n**[countrystatecity.in/pricing](https://countrystatecity.in/pricing)**\n\n## Data Access Levels\nEach plan includes a data access level that controls which fields are returned:\n\n- **Basic** — Core fields: id, name, iso2, iso3, phonecode, capital, currency, coordinates, region, timezones, emoji\n- **Coordinates** — Basic + extended metadata (population, tld, nationality, currency details, postal codes, etc.)\n- **Full** — All fields including translations (18+ languages) and wikiDataId\n\nFields restricted to higher tiers are marked in each schema below.\n\n## Feature Gating\nSome 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.\n\n## Rate Limiting\nRequests exceeding your daily or monthly quota receive a `429` response with your current limit, period, tier, and an upgrade URL.\n\n## Caching\nCacheable 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.\n\n## Usage Headers\nAll `/v1/*` responses include usage and plan headers:\n- `X-CSC-Plan` — your current tier\n- `X-CSC-Daily-Used` / `X-CSC-Daily-Limit` — today's usage vs limit\n- `X-CSC-Monthly-Used` / `X-CSC-Monthly-Limit` — this month's usage vs limit\n\nUse 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" } ], "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": { "/countries": { "get": { "tags": ["Countries"], "summary": "Get all countries", "description": "Returns a list of all countries. Fields returned depend on your plan's data access level.\n\n**Availability:** All tiers", "operationId": "getCountries", "parameters": [ { "name": "q", "in": "query", "description": "Search filter. Case-insensitive match on `name` and `native` fields. Min 2 characters. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 100, "example": "india" } }, { "name": "fields", "in": "query", "description": "Comma-separated list of fields to include in the response. `id` is always included. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name,iso2,iso3" } }, { "name": "sort", "in": "query", "description": "Comma-separated sort tokens: `field` or `field:asc|desc`. E.g. `name:asc,iso2:desc`. **Requires Starter+ plan**; you can sort only by fields your plan returns (e.g. `population` needs Supporter+).", "required": false, "schema": { "type": "string", "example": "name:asc" } }, { "name": "locale", "in": "query", "description": "BCP 47 locale code (e.g. `pt-BR`) to request a localized name. Adds `localized_name` (resolved via exact locale → base language → native name → English name fallback) and `matched_locale` (which tier matched) to each result; `name` is unaffected. **Supporter+ plans only** — silently omitted (not an error) on lower tiers. A malformed value is rejected with a `400` on every tier.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$", "example": "pt-BR" } }, { "name": "include_translations", "in": "query", "description": "When `true`, includes the full `translations` field (JSON string keyed by language code). **Supporter+ plans only** — silently omitted (not an error) on lower tiers. Note that an explicit `fields=translations` also returns the field and takes precedence over this flag.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "List of countries", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/countries/{ciso}": { "get": { "tags": ["Countries"], "summary": "Get country by ISO2 code or ID", "description": "Returns detailed information for a single country. Accepts ISO2 code (e.g., `IN`, `US`) or numeric ID.\n\n**Availability:** All tiers", "operationId": "getCountry", "parameters": [ { "name": "ciso", "in": "path", "description": "ISO2 code (e.g., `IN`) or numeric ID of the country", "required": true, "schema": { "type": "string", "example": "IN" } }, { "name": "fields", "in": "query", "description": "Comma-separated list of fields to include in the response. `id` is always included. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name,iso2,capital" } }, { "name": "locale", "in": "query", "description": "BCP 47 locale code (e.g. `pt-BR`) to request a localized name. Adds `localized_name` (resolved via exact locale → base language → native name → English name fallback) and `matched_locale` (which tier matched) to the result; `name` is unaffected. **Supporter+ plans only** — silently omitted (not an error) on lower tiers. A malformed value is rejected with a `400` on every tier.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$", "example": "pt-BR" } }, { "name": "include_translations", "in": "query", "description": "When `true`, includes the full `translations` field (JSON string keyed by language code). **Supporter+ plans only** — silently omitted (not an error) on lower tiers. Note that an explicit `fields=translations` also returns the field and takes precedence over this flag.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "Country details", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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/Country" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/countries/{ciso}/states": { "get": { "tags": ["States"], "summary": "Get states of a country", "description": "Returns all states/provinces/regions for the specified country.\n\n**Availability:** All tiers", "operationId": "getCountryStates", "parameters": [ { "name": "ciso", "in": "path", "description": "ISO2 code of the country (e.g., `IN`)", "required": true, "schema": { "type": "string", "example": "IN" } }, { "name": "q", "in": "query", "description": "Search filter. Case-insensitive match on `name` and `native` fields. Min 2 characters. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 100, "example": "maha" } }, { "name": "fields", "in": "query", "description": "Comma-separated list of fields to include in the response. `id` is always included. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name,iso2" } }, { "name": "sort", "in": "query", "description": "Comma-separated sort tokens: `field` or `field:asc|desc`. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name:asc" } }, { "name": "locale", "in": "query", "description": "BCP 47 locale code (e.g. `pt-BR`) to request a localized name. Adds `localized_name` (resolved via exact locale → base language → native name → English name fallback) and `matched_locale` (which tier matched) to each result; `name` is unaffected. **Supporter+ plans only** — silently omitted (not an error) on lower tiers. A malformed value is rejected with a `400` on every tier.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$", "example": "pt-BR" } }, { "name": "include_translations", "in": "query", "description": "When `true`, includes the full `translations` field (JSON string keyed by language code). **Supporter+ plans only** — silently omitted (not an error) on lower tiers. Note that an explicit `fields=translations` also returns the field and takes precedence over this flag.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "List of states", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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": { "type": "array", "items": { "$ref": "#/components/schemas/State" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/countries/{ciso}/states/{siso}": { "get": { "tags": ["States"], "summary": "Get state detail", "description": "Returns detailed information for a single state identified by country and state ISO2 codes.\n\n**Availability:** All tiers", "operationId": "getCountryStateDetail", "parameters": [ { "name": "ciso", "in": "path", "description": "ISO2 code of the country (e.g., `IN`)", "required": true, "schema": { "type": "string", "example": "IN" } }, { "name": "siso", "in": "path", "description": "ISO2 code of the state (e.g., `MH`)", "required": true, "schema": { "type": "string", "example": "MH" } }, { "name": "fields", "in": "query", "description": "Comma-separated list of fields to include in the response. `id` is always included. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name,iso2,country_code" } }, { "name": "locale", "in": "query", "description": "BCP 47 locale code (e.g. `pt-BR`) to request a localized name. Adds `localized_name` (resolved via exact locale → base language → native name → English name fallback) and `matched_locale` (which tier matched) to the result; `name` is unaffected. **Supporter+ plans only** — silently omitted (not an error) on lower tiers. A malformed value is rejected with a `400` on every tier.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$", "example": "pt-BR" } }, { "name": "include_translations", "in": "query", "description": "When `true`, includes the full `translations` field (JSON string keyed by language code). **Supporter+ plans only** — silently omitted (not an error) on lower tiers. Note that an explicit `fields=translations` also returns the field and takes precedence over this flag.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "State details", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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/State" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/countries/{ciso}/states/{siso}/cities": { "get": { "tags": ["Cities"], "summary": "Get cities of a state", "description": "Returns all cities for a specific state within a country.\n\n**Availability:** All tiers", "operationId": "getCountryStateCities", "parameters": [ { "name": "ciso", "in": "path", "description": "ISO2 code of the country (e.g., `IN`)", "required": true, "schema": { "type": "string", "example": "IN" } }, { "name": "siso", "in": "path", "description": "ISO2 code of the state (e.g., `MH`)", "required": true, "schema": { "type": "string", "example": "MH" } }, { "name": "q", "in": "query", "description": "Search filter. Case-insensitive match on `name` and `native` fields. Min 2 characters. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 100, "example": "mum" } }, { "name": "kind", "in": "query", "required": false, "description": "Filter by derived place classification. Comma-separated list of `settlement`, `administrative`, `section`, `unknown`. Free on every plan. Invalid values return `400` listing the accepted values.", "schema": { "type": "string", "example": "settlement" } }, { "name": "type", "in": "query", "required": false, "description": "Filter by the raw source `type` value. Comma-separated, e.g. `city,adm2`. **Requires Supporter+ plan** (`type` is an extended field); lower plans receive `400` rather than the filter being ignored. Unrecognised values match zero rows.", "schema": { "type": "string", "example": "city" } }, { "name": "fields", "in": "query", "description": "Comma-separated list of fields to include in the response. `id` is always included. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name,latitude,longitude" } }, { "name": "sort", "in": "query", "description": "Comma-separated sort tokens: `field` or `field:asc|desc`. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name:asc" } }, { "name": "locale", "in": "query", "description": "BCP 47 locale code (e.g. `pt-BR`) to request a localized name. Adds `localized_name` (resolved via exact locale → base language → native name → English name fallback) and `matched_locale` (which tier matched) to each result; `name` is unaffected. **Supporter+ plans only** — silently omitted (not an error) on lower tiers. A malformed value is rejected with a `400` on every tier.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$", "example": "pt-BR" } }, { "name": "include_translations", "in": "query", "description": "When `true`, includes the full `translations` field (JSON string keyed by language code). **Supporter+ plans only** — silently omitted (not an error) on lower tiers. Note that an explicit `fields=translations` also returns the field and takes precedence over this flag.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "List of cities", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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": { "type": "array", "items": { "$ref": "#/components/schemas/City" } } } } }, "400": { "description": "Invalid `kind` value, or `type` used on a plan below Supporter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" }, "example": { "status": "error", "message": "Field \"type\" is not available on your current plan." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/countries/{ciso}/cities": { "get": { "tags": ["Cities"], "summary": "Get all cities of a country", "description": "Returns all cities for an entire country. This can be a large response (e.g., India has 48,000+ cities).\n\n**Availability:** Starter+ plan required. Returns `403` on Community tier. See [pricing](https://countrystatecity.in/pricing) for details.", "operationId": "getCountryCities", "parameters": [ { "name": "ciso", "in": "path", "description": "ISO2 code of the country (e.g., `IN`)", "required": true, "schema": { "type": "string", "example": "IN" } }, { "name": "q", "in": "query", "description": "Search filter. Case-insensitive match on `name` and `native` fields. Min 2 characters. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 100, "example": "mum" } }, { "name": "kind", "in": "query", "required": false, "description": "Filter by derived place classification. Comma-separated list of `settlement`, `administrative`, `section`, `unknown`. Free on every plan. Invalid values return `400` listing the accepted values.", "schema": { "type": "string", "example": "settlement" } }, { "name": "type", "in": "query", "required": false, "description": "Filter by the raw source `type` value. Comma-separated, e.g. `city,adm2`. **Requires Supporter+ plan** (`type` is an extended field); lower plans receive `400` rather than the filter being ignored. Unrecognised values match zero rows.", "schema": { "type": "string", "example": "city" } }, { "name": "fields", "in": "query", "description": "Comma-separated list of fields to include in the response. `id` is always included. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name,latitude,longitude" } }, { "name": "sort", "in": "query", "description": "Comma-separated sort tokens: `field` or `field:asc|desc`. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name:asc" } }, { "name": "locale", "in": "query", "description": "BCP 47 locale code (e.g. `pt-BR`) to request a localized name. Adds `localized_name` (resolved via exact locale → base language → native name → English name fallback) and `matched_locale` (which tier matched) to each result; `name` is unaffected. **Supporter+ plans only** — silently omitted (not an error) on lower tiers. A malformed value is rejected with a `400` on every tier.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$", "example": "pt-BR" } }, { "name": "include_translations", "in": "query", "description": "When `true`, includes the full `translations` field (JSON string keyed by language code). **Supporter+ plans only** — silently omitted (not an error) on lower tiers. Note that an explicit `fields=translations` also returns the field and takes precedence over this flag.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "List of cities", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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": { "type": "array", "items": { "$ref": "#/components/schemas/City" } } } } }, "400": { "description": "Invalid `kind` value, or `type` used on a plan below Supporter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" }, "example": { "status": "error", "message": "Field \"type\" is not available on your current plan." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/states": { "get": { "tags": ["States"], "summary": "Get all states globally", "description": "Returns all states/provinces across all countries. This is a large response (5,000+ records).\n\n**Availability:** Starter+ plan required. Returns `403` on Community tier. See [pricing](https://countrystatecity.in/pricing) for details.", "operationId": "getAllStates", "parameters": [ { "name": "q", "in": "query", "description": "Search filter. Case-insensitive match on `name` and `native` fields. Min 2 characters. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 100, "example": "maha" } }, { "name": "fields", "in": "query", "description": "Comma-separated list of fields to include in the response. `id` is always included. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name,iso2,country_code" } }, { "name": "sort", "in": "query", "description": "Comma-separated sort tokens: `field` or `field:asc|desc`. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name:asc" } }, { "name": "locale", "in": "query", "description": "BCP 47 locale code (e.g. `pt-BR`) to request a localized name. Adds `localized_name` (resolved via exact locale → base language → native name → English name fallback) and `matched_locale` (which tier matched) to each result; `name` is unaffected. **Supporter+ plans only** — silently omitted (not an error) on lower tiers. A malformed value is rejected with a `400` on every tier.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$", "example": "pt-BR" } }, { "name": "include_translations", "in": "query", "description": "When `true`, includes the full `translations` field (JSON string keyed by language code). **Supporter+ plans only** — silently omitted (not an error) on lower tiers. Note that an explicit `fields=translations` also returns the field and takes precedence over this flag.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "List of all states globally", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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": { "type": "array", "items": { "$ref": "#/components/schemas/State" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/regions": { "get": { "tags": ["Regions"], "summary": "Get all regions", "description": "Returns all geographic regions (e.g., Africa, Americas, Asia, Europe, Oceania).\n\n**Availability:** Starter+ plan required.", "operationId": "getRegions", "parameters": [ { "name": "q", "in": "query", "description": "Search filter on region name. Min 2 characters. **Requires Starter+ plan with search feature.**", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "fields", "in": "query", "description": "Comma-separated list of fields to include in the response. `id` is always included. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name" } }, { "name": "sort", "in": "query", "description": "Comma-separated sort tokens: `field` or `field:asc|desc`. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name:asc" } }, { "name": "locale", "in": "query", "description": "BCP 47 locale code (e.g. `pt-BR`) to request a localized name. Adds `localized_name` (resolved via exact locale → base language → native name → English name fallback) and `matched_locale` (which tier matched) to each result; `name` is unaffected. **Supporter+ plans only** — silently omitted (not an error) on lower tiers. A malformed value is rejected with a `400` on every tier.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$", "example": "pt-BR" } }, { "name": "include_translations", "in": "query", "description": "When `true`, includes the full `translations` field (JSON string keyed by language code). **Supporter+ plans only** — silently omitted (not an error) on lower tiers. Note that an explicit `fields=translations` also returns the field and takes precedence over this flag.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "List of regions", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/regions/{id}": { "get": { "tags": ["Regions"], "summary": "Get region by ID", "description": "Returns a single region by its numeric ID.\n\n**Availability:** Starter+ plan required.", "operationId": "getRegion", "parameters": [ { "name": "id", "in": "path", "description": "Numeric region ID", "required": true, "schema": { "type": "integer", "example": 3 } }, { "name": "fields", "in": "query", "description": "Comma-separated list of fields to include in the response. `id` is always included. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name,wikiDataId" } }, { "name": "locale", "in": "query", "description": "BCP 47 locale code (e.g. `pt-BR`) to request a localized name. Adds `localized_name` (resolved via exact locale → base language → native name → English name fallback) and `matched_locale` (which tier matched) to the result; `name` is unaffected. **Supporter+ plans only** — silently omitted (not an error) on lower tiers. A malformed value is rejected with a `400` on every tier.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$", "example": "pt-BR" } }, { "name": "include_translations", "in": "query", "description": "When `true`, includes the full `translations` field (JSON string keyed by language code). **Supporter+ plans only** — silently omitted (not an error) on lower tiers. Note that an explicit `fields=translations` also returns the field and takes precedence over this flag.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "Region details", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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/Region" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/regions/{id}/subregions": { "get": { "tags": ["Regions"], "summary": "Get subregions of a region", "description": "Returns all subregions within a geographic region.\n\n**Availability:** Starter+ plan required.", "operationId": "getRegionSubregions", "parameters": [ { "name": "id", "in": "path", "description": "Numeric region ID", "required": true, "schema": { "type": "integer", "example": 3 } }, { "name": "q", "in": "query", "description": "Search filter on subregion name. Min 2 characters.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "fields", "in": "query", "description": "Comma-separated list of fields to include in the response. `id` is always included. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name,region_id" } }, { "name": "sort", "in": "query", "description": "Comma-separated sort tokens: `field` or `field:asc|desc`. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name:asc" } }, { "name": "locale", "in": "query", "description": "BCP 47 locale code (e.g. `pt-BR`) to request a localized name. Adds `localized_name` (resolved via exact locale → base language → native name → English name fallback) and `matched_locale` (which tier matched) to each result; `name` is unaffected. **Supporter+ plans only** — silently omitted (not an error) on lower tiers. A malformed value is rejected with a `400` on every tier.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$", "example": "pt-BR" } }, { "name": "include_translations", "in": "query", "description": "When `true`, includes the full `translations` field (JSON string keyed by language code). **Supporter+ plans only** — silently omitted (not an error) on lower tiers. Note that an explicit `fields=translations` also returns the field and takes precedence over this flag.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "List of subregions", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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": { "type": "array", "items": { "$ref": "#/components/schemas/Subregion" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/subregions/{id}": { "get": { "tags": ["Regions"], "summary": "Get subregion by ID", "description": "Returns a single subregion by its numeric ID.\n\n**Availability:** Starter+ plan required.", "operationId": "getSubregion", "parameters": [ { "name": "id", "in": "path", "description": "Numeric subregion ID", "required": true, "schema": { "type": "integer", "example": 14 } }, { "name": "fields", "in": "query", "description": "Comma-separated list of fields to include in the response. `id` is always included. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name,region_id" } }, { "name": "locale", "in": "query", "description": "BCP 47 locale code (e.g. `pt-BR`) to request a localized name. Adds `localized_name` (resolved via exact locale → base language → native name → English name fallback) and `matched_locale` (which tier matched) to the result; `name` is unaffected. **Supporter+ plans only** — silently omitted (not an error) on lower tiers. A malformed value is rejected with a `400` on every tier.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$", "example": "pt-BR" } }, { "name": "include_translations", "in": "query", "description": "When `true`, includes the full `translations` field (JSON string keyed by language code). **Supporter+ plans only** — silently omitted (not an error) on lower tiers. Note that an explicit `fields=translations` also returns the field and takes precedence over this flag.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "Subregion details", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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/Subregion" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/subregions/{id}/countries": { "get": { "tags": ["Regions"], "summary": "Get countries in a subregion", "description": "Returns all countries belonging to a subregion.\n\n**Availability:** Starter+ plan required.", "operationId": "getSubregionCountries", "parameters": [ { "name": "id", "in": "path", "description": "Numeric subregion ID", "required": true, "schema": { "type": "integer", "example": 14 } }, { "name": "q", "in": "query", "description": "Search filter on country name. Min 2 characters.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "fields", "in": "query", "description": "Comma-separated list of fields to include in the response. `id` is always included. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name,iso2" } }, { "name": "sort", "in": "query", "description": "Comma-separated sort tokens: `field` or `field:asc|desc`. **Requires Starter+ plan.**", "required": false, "schema": { "type": "string", "example": "name:asc" } }, { "name": "locale", "in": "query", "description": "BCP 47 locale code (e.g. `pt-BR`) to request a localized name. Adds `localized_name` (resolved via exact locale → base language → native name → English name fallback) and `matched_locale` (which tier matched) to each result; `name` is unaffected. **Supporter+ plans only** — silently omitted (not an error) on lower tiers. A malformed value is rejected with a `400` on every tier.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$", "example": "pt-BR" } }, { "name": "include_translations", "in": "query", "description": "When `true`, includes the full `translations` field (JSON string keyed by language code). **Supporter+ plans only** — silently omitted (not an error) on lower tiers. Note that an explicit `fields=translations` also returns the field and takes precedence over this flag.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "List of countries in subregion", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/timezone/{ciso}": { "get": { "tags": ["Timezones"], "summary": "Get timezone by country", "description": "Returns the canonical IANA timezone for a country, resolved via the capital city. Includes current UTC offset and DST status.\n\n**Availability:** All plans (Community and above). Responses cached server-side for 24 hours.", "operationId": "getTimezoneByCountry", "parameters": [ { "name": "ciso", "in": "path", "description": "ISO 3166-1 alpha-2 (e.g., `IN`), alpha-3 (e.g., `IND`), or numeric country ID (e.g., `101`)", "required": true, "schema": { "type": "string", "example": "IN" } } ], "responses": { "200": { "description": "Timezone information for the country", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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/TimezoneInfo" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Country not found, or no timezone data for it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" }, "example": { "status": "error", "message": "Country not found." } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/timezone/{ciso}/{siso}": { "get": { "tags": ["Timezones"], "summary": "Get timezone by state", "description": "Returns the canonical IANA timezone for a specific state or province within a country.\n\n**Availability:** All plans (Community and above). Responses cached server-side for 24 hours.", "operationId": "getTimezoneByState", "parameters": [ { "name": "ciso", "in": "path", "description": "ISO 3166-1 alpha-2 (e.g., `US`), alpha-3 (e.g., `USA`), or numeric country ID", "required": true, "schema": { "type": "string", "example": "US" } }, { "name": "siso", "in": "path", "description": "State/province code in local subdivision format (e.g., `CA` for California)", "required": true, "schema": { "type": "string", "example": "CA" } } ], "responses": { "200": { "description": "Timezone information for the state", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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/TimezoneInfo" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "State not found, or no timezone data for it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" }, "example": { "status": "error", "message": "State not found." } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/timezone/{ciso}/{siso}/{city_id}": { "get": { "tags": ["Timezones"], "summary": "Get timezone by city", "description": "Returns the canonical IANA timezone for a specific city. The city ID is validated against the given country and state to prevent cross-jurisdiction lookups.\n\n**Availability:** All plans (Community and above). Responses cached server-side for 24 hours.", "operationId": "getTimezoneByCity", "parameters": [ { "name": "ciso", "in": "path", "description": "ISO 3166-1 alpha-2 (e.g., `US`), alpha-3, or numeric country ID", "required": true, "schema": { "type": "string", "example": "US" } }, { "name": "siso", "in": "path", "description": "State/province code (e.g., `CA`)", "required": true, "schema": { "type": "string", "example": "CA" } }, { "name": "city_id", "in": "path", "description": "Numeric city ID (from the cities endpoints)", "required": true, "schema": { "type": "integer", "example": 24295 } } ], "responses": { "200": { "description": "Timezone information for the city", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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/TimezoneInfo" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "City not found, or no timezone data for it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" }, "example": { "status": "error", "message": "City not found." } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/currency": { "get": { "tags": ["Currencies"], "summary": "List all currencies", "description": "Returns currency data for all countries. Use the optional `?code=` parameter for a reverse lookup — returns all countries using that ISO 4217 currency code.\n\n**Availability:** Starter+ plan required. Responses cached server-side for 24 hours.", "operationId": "listCurrencies", "parameters": [ { "name": "code", "in": "query", "description": "ISO 4217 currency code to filter by (e.g., `EUR`). Returns all countries using this currency.", "required": false, "schema": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } } ], "responses": { "200": { "description": "List of currency entries ordered by country ISO2 code", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyInfo" } } } } }, "400": { "description": "Invalid currency code format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/currency/{ciso}": { "get": { "tags": ["Currencies"], "summary": "Get currency by country", "description": "Returns the official ISO 4217 currency for a single country.\n\n**Availability:** Starter+ plan required. Responses cached server-side for 24 hours.", "operationId": "getCurrencyByCountry", "parameters": [ { "name": "ciso", "in": "path", "description": "ISO 3166-1 alpha-2 (e.g., `IN`), alpha-3 (e.g., `IND`), or numeric country ID (e.g., `101`)", "required": true, "schema": { "type": "string", "example": "IN" } } ], "responses": { "200": { "description": "Currency data for the country", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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/CurrencyInfo" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/phone": { "get": { "tags": ["Phone"], "summary": "List all dial codes", "description": "Returns international dial codes for all countries. Use the optional `?code=` parameter for a reverse lookup — returns all countries sharing a given dial code (useful for NANP `+1` territories which are grouped by area code).\n\n**Availability:** Starter+ plan required. Responses cached server-side for 24 hours.", "operationId": "listDialCodes", "parameters": [ { "name": "code", "in": "query", "description": "Dial code to filter by. Accepts with or without `+` prefix (`+91` or `91`), 1–4 digits, leading zeros are stripped.", "required": false, "schema": { "type": "string", "example": "+1" } } ], "responses": { "200": { "description": "List of dial code entries ordered by country ISO2 code", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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": { "type": "array", "items": { "$ref": "#/components/schemas/DialCode" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/phone/{ciso}": { "get": { "tags": ["Phone"], "summary": "Get dial code by country", "description": "Returns the international dial code for a single country.\n\n**Availability:** Starter+ plan required. Responses cached server-side for 24 hours.", "operationId": "getDialCodeByCountry", "parameters": [ { "name": "ciso", "in": "path", "description": "ISO 3166-1 alpha-2 (e.g., `IN`), alpha-3 (e.g., `IND`), or numeric country ID (e.g., `101`). Case-insensitive.", "required": true, "schema": { "type": "string", "example": "IN" } } ], "responses": { "200": { "description": "Dial code for the country", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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/DialCode" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "404": { "description": "Country not found, or no dial code for it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" }, "example": { "status": "error", "message": "Country not found." } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/phone/parse": { "get": { "tags": ["Phone"], "summary": "Parse phone number", "description": "Parses an E.164-formatted phone number to identify the originating country and extract the national number. Uses a hierarchical prefix system; for NANP (`+1`) numbers, performs area-code matching to distinguish territories.\n\n**Note:** The response echoes the phone number (`e164`) which is PII. This endpoint returns `Cache-Control: no-store` and no `ETag` header to prevent caching.\n\n**Availability:** Starter+ plan required.", "operationId": "parsePhoneNumber", "parameters": [ { "name": "number", "in": "query", "description": "E.164-formatted phone number — `+` followed by 5–15 digits (e.g., `+14155552671`)", "required": true, "schema": { "type": "string", "example": "+14155552671" } } ], "responses": { "200": { "description": "Parsed phone number with country identification", "headers": { "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/PhoneParsed" } } } }, "400": { "description": "Invalid E.164 format (missing `+`, wrong digit count)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" }, "example": { "status": "error", "message": "Phone number must be in E.164 format starting with + (e.g., +14155552671)." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "404": { "description": "No country matches the number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" }, "example": { "status": "error", "message": "Could not identify a country for the given phone number." } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/iso/country": { "get": { "tags": ["ISO"], "summary": "Lookup country by ISO code", "description": "Resolves a country record from any ISO 3166-1 identifier. Provide **exactly one** of `iso2`, `iso3`, or `numeric`; sending zero or more than one returns `400`.\n\n**Availability:** Starter+ plan required. Responses cached server-side for 1 hour.", "operationId": "lookupCountryByIso", "parameters": [ { "name": "iso2", "in": "query", "description": "ISO 3166-1 alpha-2 code (e.g., `US`). Provide exactly one of `iso2`, `iso3`, or `numeric`.", "required": false, "schema": { "type": "string", "example": "US" } }, { "name": "iso3", "in": "query", "description": "ISO 3166-1 alpha-3 code (e.g., `USA`). Provide exactly one of `iso2`, `iso3`, or `numeric`.", "required": false, "schema": { "type": "string", "example": "USA" } }, { "name": "numeric", "in": "query", "description": "ISO 3166-1 numeric code, 1–3 digits (e.g., `840`). Provide exactly one of `iso2`, `iso3`, or `numeric`.", "required": false, "schema": { "type": "string", "example": "840" } } ], "responses": { "200": { "description": "Country record with all ISO identifiers", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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/IsoCountry" } } } }, "400": { "description": "Zero or multiple ISO parameters provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "404": { "description": "No country matches the code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" }, "example": { "status": "error", "message": "Country not found for the given code" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/iso/state": { "get": { "tags": ["ISO"], "summary": "Lookup state by ISO 3166-2 code", "description": "Resolves a state/province record from its ISO 3166-2 subdivision code (e.g., `US-CA`, `IN-MH`). Case-insensitive. Falls back to the legacy `iso2` column for older entries where `iso3166_2` is null.\n\n**Availability:** Starter+ plan required. Responses cached server-side for 1 hour.", "operationId": "lookupStateByIso", "parameters": [ { "name": "iso", "in": "query", "description": "ISO 3166-2 subdivision code (e.g., `US-CA` or `IN-MH`). Case-insensitive.", "required": true, "schema": { "type": "string", "example": "US-CA" } } ], "responses": { "200": { "description": "State record with ISO identifiers and country reference", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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/IsoState" } } } }, "400": { "description": "Missing or malformed `iso` parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "404": { "description": "No state matches the ISO code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" }, "example": { "status": "error", "message": "State not found for the given ISO code" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/iso/country/convert": { "get": { "tags": ["ISO"], "summary": "Convert ISO country code", "description": "Translates a country code between ISO 3166-1 formats: alpha-2 ↔ alpha-3 ↔ numeric. All three conversion directions are supported.\n\n**Availability:** Starter+ plan required.", "operationId": "convertIsoCountryCode", "parameters": [ { "name": "from", "in": "query", "description": "Source format", "required": true, "schema": { "type": "string", "enum": ["iso2", "iso3", "numeric"], "example": "iso2" } }, { "name": "to", "in": "query", "description": "Target format (must differ from `from`)", "required": true, "schema": { "type": "string", "enum": ["iso2", "iso3", "numeric"], "example": "iso3" } }, { "name": "value", "in": "query", "description": "The code to convert (e.g., `US` when `from=iso2`)", "required": true, "schema": { "type": "string", "example": "US" } } ], "responses": { "200": { "description": "Converted ISO code", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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/IsoConvert" } } } }, "400": { "description": "Mismatched `from`/`to` formats, invalid value, or `from` equals `to`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FeatureRestricted" }, "404": { "description": "No country matches the value, or it has no code in the requested format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" }, "example": { "status": "error", "message": "Country not found for the given code" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/search/fuzzy": { "get": { "tags": ["Search"], "summary": "Fuzzy search", "description": "Typo-tolerant search for cities, states, or countries. It searches English and native names, plus translations for queries of at least 3 characters. Use `locale` to add a localized display name to each result. Results are ranked by `match_score` descending.\n\nExample: `?q=ムンバイ&type=city&locale=ja` finds Mumbai by its Japanese translation while keeping the English `name` and stable `id`.\n\n**Availability:** Supporter+ plans. [Compare plans](https://countrystatecity.in/pricing?source=api_playground&campaign=localized_search).", "operationId": "fuzzySearch", "parameters": [ { "name": "q", "in": "query", "description": "Search query — 2 to 100 characters. Case-insensitive.", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 100, "example": "Mumbay" } }, { "name": "type", "in": "query", "description": "Entity type to search", "required": false, "schema": { "type": "string", "enum": ["city", "state", "country"], "default": "city", "example": "city" } }, { "name": "country", "in": "query", "description": "ISO 3166-1 alpha-2 country code to narrow the search (e.g., `IN`). Ignored when `type=country`.", "required": false, "schema": { "type": "string", "example": "IN" } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return (1–50)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "example": 10 } }, { "name": "threshold", "in": "query", "description": "Minimum trigram similarity score (0.1–1.0). Lower values yield looser matches.", "required": false, "schema": { "type": "number", "minimum": 0.1, "maximum": 1.0, "default": 0.3, "example": 0.3 } }, { "name": "locale", "in": "query", "description": "Adds `localized_name` and `matched_locale` using exact locale → base language → native name → English name fallback. The English `name` and `id` stay unchanged. **Supporter+ plans only.**", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$", "example": "ja" } }, { "name": "include_translations", "in": "query", "description": "When `true`, includes the full translation JSON string. **Supporter+ plans only.**", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "List of matching results ranked by similarity score", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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": { "type": "array", "items": { "$ref": "#/components/schemas/FuzzyResult" } } } } }, "400": { "description": "Missing or invalid query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Feature not available on your current plan. Requires Supporter+.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureError" }, "example": { "status": "error", "message": "This feature is not available on your current plan.", "details": { "feature": "fuzzySearch", "currentTier": "starter", "requiredTier": "supporter", "upgradeUrl": "https://countrystatecity.in/pricing" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/search/autocomplete": { "get": { "tags": ["Search"], "summary": "Location autocomplete", "description": "As-you-type search for cities, states, or countries. It searches English and native names, plus translations for queries of at least 3 characters. Results rank exact matches first, then starts-with, then fuzzy matches. Each result includes a ready-to-display `label`; when `locale` is set, that label starts with the localized name.\n\nExample: `?q=ムンバイ&type=city&locale=ja` finds Mumbai and returns a Japanese label while preserving the English `name` and stable `id`.\n\n**Availability:** Supporter+ plans for production use; other plans can try basic autocomplete in the public playground. [Compare plans](https://countrystatecity.in/pricing?source=api_playground&campaign=localized_autocomplete).", "operationId": "autocompleteSearch", "parameters": [ { "name": "q", "in": "query", "description": "Search query — 2 to 100 characters. Case-insensitive.", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 100, "example": "Mumbay" } }, { "name": "type", "in": "query", "description": "Entity type to search", "required": false, "schema": { "type": "string", "enum": ["city", "state", "country"], "default": "city", "example": "city" } }, { "name": "country", "in": "query", "description": "ISO 3166-1 alpha-2 country code to narrow the search (e.g., `IN`). Invalid when `type=country` — supplying both returns a `400`.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Za-z]{2}$", "example": "IN" } }, { "name": "state", "in": "query", "description": "State/province ISO code to narrow a city search further (e.g., `MH`). State codes are not globally unique, so this requires `country` to also be set and is valid only when `type=city`.", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 20, "example": "MH" } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return (1–50)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "example": 10 } }, { "name": "locale", "in": "query", "description": "Adds `localized_name` and `matched_locale`, and starts `label` with the localized name. The English `name` and `id` stay unchanged. **Supporter+ plans only.**", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$", "example": "ja" } }, { "name": "include_translations", "in": "query", "description": "When `true`, includes the full translation JSON string. **Supporter+ plans only.**", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "List of matching results ranked by relevance", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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": { "type": "array", "items": { "$ref": "#/components/schemas/AutocompleteResult" } } } } }, "400": { "description": "Missing or invalid query parameter, `state` used without `country` or with a non-city type, or `country` supplied together with `type=country`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Feature not available on your current plan. Requires Supporter+.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureError" }, "example": { "status": "error", "message": "This feature is not available on your current plan.", "details": { "feature": "autocomplete", "currentTier": "starter", "requiredTier": "supporter", "upgradeUrl": "https://countrystatecity.in/pricing" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/search/nearby": { "get": { "tags": ["Search"], "summary": "Nearby search", "description": "Find the nearest cities, states, or countries to a coordinate pair. Results are sorted by `distance_km`, nearest first.\n\nThis is **not** street-address search, map-boundary containment, road distance, or travel time. It measures straight-line distance to known place points.\n\nExample: `?lat=19.076&lng=72.878&type=city&kind=settlement` finds settlements near Mumbai.\n\n**Availability:** Supporter+ plans for production use. Other plans can try it in the public playground. [Compare plans](https://countrystatecity.in/pricing?source=api_playground&campaign=nearby_search).", "operationId": "nearbySearch", "parameters": [ { "name": "lat", "in": "query", "description": "Latitude of the search origin", "required": true, "schema": { "type": "number", "minimum": -90, "maximum": 90, "example": 19.076 } }, { "name": "lng", "in": "query", "description": "Longitude of the search origin", "required": true, "schema": { "type": "number", "minimum": -180, "maximum": 180, "example": 72.878 } }, { "name": "type", "in": "query", "description": "Entity type to search", "required": false, "schema": { "type": "string", "enum": ["city", "state", "country"], "default": "city", "example": "city" } }, { "name": "kind", "in": "query", "description": "City classification filter. Valid only when `type=city`.", "required": false, "schema": { "type": "string", "enum": ["settlement", "administrative", "section", "unknown"], "example": "settlement" } }, { "name": "country", "in": "query", "description": "ISO 3166-1 alpha-2 country code. Invalid when `type=country`.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Za-z]{2}$", "example": "IN" } }, { "name": "state", "in": "query", "description": "State or province code for a city search. Requires `country` and is valid only when `type=city`.", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 20, "example": "MH" } }, { "name": "min_population", "in": "query", "description": "Minimum population a result must have", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9007199254740991, "example": 100000 } }, { "name": "radius", "in": "query", "description": "Search radius in kilometers (1–500)", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 500, "default": 25, "example": 25 } }, { "name": "limit", "in": "query", "description": "Maximum number of results (1–100)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "example": 20 } }, { "name": "locale", "in": "query", "description": "Adds `localized_name` and `matched_locale` using exact locale → base language → native name → English name fallback. The English `name`, stable `id`, and distance stay unchanged. **Supporter+ plans only.**", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$", "example": "ja" } }, { "name": "include_translations", "in": "query", "description": "When `true`, includes the full translation JSON string. **Supporter+ plans only.**", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "Matching results sorted from nearest to farthest", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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": { "type": "array", "items": { "$ref": "#/components/schemas/NearbyResult" } } } } }, "400": { "description": "Missing or invalid query parameter, or a country, state, or kind filter used with an invalid entity type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Feature not available on your current plan. Requires Supporter+.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureError" }, "example": { "status": "error", "message": "This feature is not available on your current plan.", "details": { "feature": "nearbySearch", "currentTier": "starter", "requiredTier": "supporter", "upgradeUrl": "https://countrystatecity.in/pricing" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/changes": { "get": { "tags": ["Changes"], "summary": "List data changes", "description": "Returns additions, removals, and updates to country, state, and city records, oldest first. Changes are retained for 90 days. Use this feed to keep a local copy in sync instead of downloading the full dataset again.\n\nPagination is stable: the first request fixes the result set, and every `next_page_token` continues through that same snapshot. Changes published after page one are not added to later pages; start a new request to receive them. The token also carries the original filters, is valid for 24 hours, and must be treated as opaque.\n\nFields inside `old_values` and `new_values` follow the caller's data access level.\n\n**Availability:** Professional and Business plans only. [Compare plans](https://countrystatecity.in/pricing?source=api_playground&campaign=data_change_feed).", "operationId": "listChanges", "parameters": [ { "name": "start_date", "in": "query", "description": "Return changes at or after this ISO 8601 timestamp. A date older than the earliest retained change returns `400` with `details.earliestAvailableDate`.", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2026-08-01T00:00:00Z" } }, { "name": "place_type", "in": "query", "description": "Return changes for one place type", "required": false, "schema": { "type": "string", "enum": ["country", "state", "city"], "example": "city" } }, { "name": "country_code", "in": "query", "description": "Return changes for a country and its states and cities. Uses an ISO 3166-1 alpha-2 code.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Za-z]{2}$", "example": "IN" } }, { "name": "change_type", "in": "query", "description": "Return one kind of change", "required": false, "schema": { "type": "string", "enum": ["added", "removed", "renamed", "place_group_changed", "parent_changed", "coordinates_changed", "other_fields_changed"], "example": "renamed" } }, { "name": "limit", "in": "query", "description": "Maximum records per page (1–100)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "example": 50 } }, { "name": "next_page_token", "in": "query", "description": "Opaque cursor returned by the previous page. It expires after 24 hours. Omit the original filters, or resend all of them unchanged.", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "description": "A page from the fixed change-feed snapshot. This endpoint is not cached and does not return `Cache-Control`, `ETag`, or `X-Cache`.", "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/ChangeFeedResponse" } } } }, "400": { "description": "Invalid parameter or token, filters that disagree with the token, or a start date outside the retained window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeFeedError" }, "example": { "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" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key's plan does not include the data change feed. Professional is the standard required tier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeFeedFeatureError" }, "example": { "status": "error", "message": "This feature is not available on your current plan.", "details": { "feature": "dataChangeFeed", "currentTier": "supporter", "requiredTier": "professional", "upgradeUrl": "https://countrystatecity.in/pricing" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [{ "ApiKeyAuth": [] }] } }, "/countries/{ciso}/postcodes": { "get": { "tags": ["Postcodes"], "summary": "List or search postcodes in a country", "operationId": "listPostcodesByCountry", "description": "Page through a country's postcodes, or narrow them with a code/locality search, state, city or type filter. Cursor-paginated; there is no total count.\n\nInformational data only: this is not an address verification or mail-deliverability service.\n\n**Availability:** Starter+ plan required, including a bare list with no filters.", "parameters": [ { "name": "ciso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code, case-insensitive (e.g. `LK`). Numeric IDs and ISO3 codes are not accepted on postcode endpoints.", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "example": "LK" } }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive search: codes starting with `q`, or locality names containing it. 2 to 100 characters.", "schema": { "type": "string", "minLength": 2, "maxLength": 100, "example": "1100" } }, { "name": "state_code", "in": "query", "required": false, "description": "Exact, case-insensitive state/province code filter.", "schema": { "type": "string", "example": "DL" } }, { "name": "city_id", "in": "query", "required": false, "description": "Exact city ID filter (positive integer).", "schema": { "type": "integer", "minimum": 1, "example": 129881 } }, { "name": "type", "in": "query", "required": false, "description": "Exact, case-insensitive postcode type filter. Not a fixed enum; unrecognised values match zero rows.", "schema": { "type": "string", "maxLength": 32, "example": "full" } }, { "name": "fields", "in": "query", "required": false, "description": "Comma-separated fields to include. `id` is always included. There is no `sort` on this endpoint.", "schema": { "type": "string", "example": "code,locality_name" } }, { "name": "limit", "in": "query", "required": false, "description": "Records per page, 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque `pagination.next_cursor` from the previous page. Resend the same filters, or omit them and send only the cursor.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of postcodes", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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/PostcodeListResponse" } } } }, "304": { "description": "Not modified (sent `If-None-Match` matched the current `ETag`)" }, "400": { "description": "Invalid country code or parameter, or a cursor that is expired, tampered with, from another country, or used with different filters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Plan below Starter. Returned for every request to this endpoint, including a bare list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" }, "example": { "status": "error", "message": "This feature is not available on your current plan.", "details": { "feature": "searchEndpoint", "currentTier": "community", "requiredTier": "starter", "upgradeUrl": "https://countrystatecity.in/pricing" } } } } }, "404": { "description": "Unknown country (`details.reason`: `country_not_found`). A known country with no postcodes, or a filter with no matches, returns `200` with an empty `data` array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" }, "example": { "status": "error", "message": "Country not found.", "details": { "reason": "country_not_found" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/countries/{ciso}/postcodes/{code}": { "get": { "tags": ["Postcodes"], "summary": "Get postcode by code", "operationId": "getPostcodeByCode", "description": "Exact postcode lookup within a country. Returns **every** matching record, because one code can cover several localities.\n\nInformational data only: this is not an address verification or mail-deliverability service.\n\n**Availability:** All tiers.", "parameters": [ { "name": "ciso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code, case-insensitive (e.g. `LK`). Numeric IDs and ISO3 codes are not accepted on postcode endpoints.", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "example": "LK" } }, { "name": "code", "in": "path", "required": true, "description": "Postcode to look up, 1 to 20 characters. Case-insensitive and tolerant of repeated internal spaces (`gy1 1aa` matches `GY1 1AA`). URL-encode spaces.", "schema": { "type": "string", "minLength": 1, "maxLength": 20, "example": "11104" } } ], "responses": { "200": { "description": "All records matching the code", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Cache": { "$ref": "#/components/headers/XCache" }, "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/PostcodeLookupResponse" } } } }, "304": { "description": "Not modified (sent `If-None-Match` matched the current `ETag`)" }, "400": { "description": "Invalid code (empty, over 20 characters, or containing `/`, `\\\\` or control characters)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" }, "example": { "status": "error", "message": "postcode must be at most 20 characters" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unknown country (`country_not_found`), no postcode coverage (`postcode_coverage_unavailable`), or no match (`postcode_not_found`). See `details.reason`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusError" }, "example": { "status": "error", "message": "No postcode matches the given code.", "details": { "reason": "postcode_not_found" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/meta/data-version": { "get": { "tags": ["Meta"], "summary": "Get data version", "operationId": "getDataVersion", "description": "Returns which geographic data release the API is currently serving. Cached for up to about 5 minutes after an import.\n\n**Availability:** All tiers (counts toward your quota).", "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": { "schemas": { "Country": { "type": "object", "description": "Country object. Fields returned depend on your plan's data access level.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier", "example": 101 }, "name": { "type": "string", "description": "Country name in English", "example": "India" }, "iso2": { "type": "string", "description": "ISO 3166-1 alpha-2 code", "example": "IN" }, "iso3": { "type": "string", "description": "ISO 3166-1 alpha-3 code", "example": "IND" }, "phonecode": { "type": "string", "description": "International dialling code", "example": "91" }, "capital": { "type": "string", "nullable": true, "description": "Capital city name", "example": "New Delhi" }, "currency": { "type": "string", "nullable": true, "description": "Currency code", "example": "INR" }, "native": { "type": "string", "nullable": true, "description": "Country name in native language", "example": "भारत" }, "emoji": { "type": "string", "nullable": true, "description": "Flag emoji", "example": "🇮🇳" }, "latitude": { "type": "string", "nullable": true, "description": "Latitude coordinate", "example": "20.00000000" }, "longitude": { "type": "string", "nullable": true, "description": "Longitude coordinate", "example": "77.00000000" }, "region": { "type": "string", "nullable": true, "description": "Geographic region", "example": "Asia" }, "region_id": { "type": "integer", "nullable": true, "description": "Region identifier" }, "subregion": { "type": "string", "nullable": true, "description": "Geographic subregion", "example": "Southern Asia" }, "subregion_id": { "type": "integer", "nullable": true, "description": "Subregion identifier" }, "timezones": { "type": "string", "nullable": true, "description": "JSON string of timezone objects with zoneName, gmtOffset, gmtOffsetName, abbreviation, tzName", "example": "[{\"zoneName\":\"Asia/Kolkata\",\"gmtOffset\":19800,\"gmtOffsetName\":\"UTC+05:30\",\"abbreviation\":\"IST\",\"tzName\":\"Indian Standard Time\"}]" }, "numeric_code": { "type": "string", "nullable": true, "description": "ISO 3166-1 numeric code. **Coordinates tier and above.**", "example": "356" }, "currency_name": { "type": "string", "nullable": true, "description": "Full currency name. **Coordinates tier and above.**", "example": "Indian rupee" }, "currency_symbol": { "type": "string", "nullable": true, "description": "Currency symbol. **Coordinates tier and above.**", "example": "₹" }, "tld": { "type": "string", "nullable": true, "description": "Top-level domain. **Coordinates tier and above.**", "example": ".in" }, "nationality": { "type": "string", "nullable": true, "description": "Nationality/demonym. **Coordinates tier and above.**", "example": "Indian" }, "population": { "type": "integer", "format": "int64", "nullable": true, "description": "Population count. **Coordinates tier and above.**" }, "gdp": { "type": "integer", "format": "int64", "nullable": true, "description": "Gross domestic product (USD). **Coordinates tier and above.**" }, "area_sq_km": { "type": "number", "nullable": true, "description": "Area in square kilometres. **Coordinates tier and above.**" }, "postal_code_format": { "type": "string", "nullable": true, "description": "Postal code format pattern. **Coordinates tier and above.**" }, "postal_code_regex": { "type": "string", "nullable": true, "description": "Postal code validation regex. **Coordinates tier and above.**" }, "emojiU": { "type": "string", "nullable": true, "description": "Flag emoji Unicode points. **Coordinates tier and above.**", "example": "U+1F1EE U+1F1F3" }, "translations": { "type": "string", "nullable": true, "description": "JSON string keyed by language code. **Supporter+ plans only.** Returned when `include_translations=true` or when `fields=translations` explicitly requests it." }, "wikiDataId": { "type": "string", "nullable": true, "description": "Wikidata item identifier. **Full access level only.**", "example": "Q668" }, "localized_name": { "type": "string", "nullable": true, "description": "Name resolved via the `locale` query param's fallback chain (exact locale → base language → native name → English name). Only present when `locale` was supplied. **Supporter+ plans only** — silently omitted on lower tiers.", "example": "Índia" }, "matched_locale": { "type": "string", "nullable": true, "description": "Which fallback tier satisfied the `locale` request: the exact locale (e.g. `pt-BR`), its base language (e.g. `pt`), `native`, or `en` (English fallback). Only present when `locale` was supplied. **Supporter+ plans only** — silently omitted on lower tiers.", "example": "pt" } }, "required": ["id", "name", "iso2", "iso3"] }, "State": { "type": "object", "description": "State/province/region object. Fields returned depend on your plan's data access level.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier", "example": 4008 }, "name": { "type": "string", "description": "State name in English", "example": "Maharashtra" }, "iso2": { "type": "string", "nullable": true, "description": "State/province ISO code", "example": "MH" }, "country_id": { "type": "integer", "format": "int64", "description": "Parent country ID" }, "country_code": { "type": "string", "description": "Parent country ISO2 code", "example": "IN" }, "latitude": { "type": "string", "nullable": true, "description": "Latitude coordinate", "example": "19.75147980" }, "longitude": { "type": "string", "nullable": true, "description": "Longitude coordinate", "example": "75.71388840" }, "timezone": { "type": "string", "nullable": true, "description": "IANA timezone identifier", "example": "Asia/Kolkata" }, "fips_code": { "type": "string", "nullable": true, "description": "FIPS code. **Coordinates tier and above.**" }, "iso3166_2": { "type": "string", "nullable": true, "description": "ISO 3166-2 subdivision code. **Coordinates tier and above.**" }, "type": { "type": "string", "nullable": true, "description": "Administrative type (e.g., state, province, territory). **Coordinates tier and above.**", "example": "state" }, "level": { "type": "integer", "nullable": true, "description": "Administrative level. **Coordinates tier and above.**" }, "parent_id": { "type": "integer", "format": "int64", "nullable": true, "description": "Parent subdivision ID (for nested administrative structures). **Coordinates tier and above.**" }, "native": { "type": "string", "nullable": true, "description": "Name in native language. **Coordinates tier and above.**" }, "population": { "type": "integer", "format": "int64", "nullable": true, "description": "Population count. **Coordinates tier and above.**" }, "translations": { "type": "string", "nullable": true, "description": "JSON string keyed by language code. **Supporter+ plans only.** Returned when `include_translations=true` or when `fields=translations` explicitly requests it." }, "wikiDataId": { "type": "string", "nullable": true, "description": "Wikidata item identifier. **Full access level only.**", "example": "Q1191" }, "localized_name": { "type": "string", "nullable": true, "description": "Name resolved via the `locale` query param's fallback chain (exact locale → base language → native name → English name). Only present when `locale` was supplied. **Supporter+ plans only** — silently omitted on lower tiers.", "example": "Maharashtra" }, "matched_locale": { "type": "string", "nullable": true, "description": "Which fallback tier satisfied the `locale` request: the exact locale (e.g. `pt-BR`), its base language (e.g. `pt`), `native`, or `en` (English fallback). Only present when `locale` was supplied. **Supporter+ plans only** — silently omitted on lower tiers.", "example": "en" } }, "required": ["id", "name", "country_id", "country_code"] }, "City": { "type": "object", "description": "City object. Fields returned depend on your plan's data access level. Basic tier plans receive `id`, `name` and `kind` by default.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier", "example": 57606 }, "name": { "type": "string", "description": "City name in English", "example": "Mumbai" }, "kind": { "type": "string", "enum": ["settlement", "administrative", "section", "unknown"], "description": "Derived classification of the place, computed from `type`. Returned on every tier, including **Basic**. See [City Types](https://docs.countrystatecity.in/database/city-types).", "example": "settlement" }, "state_id": { "type": "integer", "format": "int64", "description": "Parent state ID. **Coordinates tier and above.**" }, "state_code": { "type": "string", "description": "Parent state ISO2 code. **Coordinates tier and above.**", "example": "MH" }, "country_id": { "type": "integer", "format": "int64", "description": "Parent country ID. **Coordinates tier and above.**" }, "country_code": { "type": "string", "description": "Parent country ISO2 code. **Coordinates tier and above.**", "example": "IN" }, "latitude": { "type": "string", "description": "Latitude coordinate. **Coordinates tier and above.**", "example": "19.07283000" }, "longitude": { "type": "string", "description": "Longitude coordinate. **Coordinates tier and above.**", "example": "72.88261000" }, "timezone": { "type": "string", "nullable": true, "description": "IANA timezone identifier. **Coordinates tier and above.**", "example": "Asia/Kolkata" }, "population": { "type": "integer", "format": "int64", "nullable": true, "description": "Population count. **Coordinates tier and above.**" }, "type": { "type": "string", "nullable": true, "description": "Raw source settlement type, e.g. `city`, `adm2`. See [City Types](https://docs.countrystatecity.in/database/city-types). **Coordinates tier and above.**" }, "level": { "type": "integer", "nullable": true, "description": "Administrative level. **Coordinates tier and above.**" }, "parent_id": { "type": "integer", "format": "int64", "nullable": true, "description": "Parent city ID. **Coordinates tier and above.**" }, "native": { "type": "string", "nullable": true, "description": "Name in native language. **Coordinates tier and above.**" }, "translations": { "type": "string", "nullable": true, "description": "JSON string keyed by language code. **Supporter+ plans only.** Returned when `include_translations=true` or when `fields=translations` explicitly requests it." }, "wikiDataId": { "type": "string", "nullable": true, "description": "Wikidata item identifier. **Full access level only.**", "example": "Q1156" }, "localized_name": { "type": "string", "nullable": true, "description": "Name resolved via the `locale` query param's fallback chain (exact locale → base language → native name → English name). Only present when `locale` was supplied. **Supporter+ plans only** — silently omitted on lower tiers.", "example": "Mumbai" }, "matched_locale": { "type": "string", "nullable": true, "description": "Which fallback tier satisfied the `locale` request: the exact locale (e.g. `pt-BR`), its base language (e.g. `pt`), `native`, or `en` (English fallback). Only present when `locale` was supplied. **Supporter+ plans only** — silently omitted on lower tiers.", "example": "en" } }, "required": ["id", "name"] }, "Region": { "type": "object", "description": "Geographic region. Fields returned depend on your plan's data access level.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier", "example": 3 }, "name": { "type": "string", "description": "Region name", "example": "Asia" }, "translations": { "type": "string", "nullable": true, "description": "JSON string keyed by language code. **Supporter+ plans only.** Returned when `include_translations=true` or when `fields=translations` explicitly requests it." }, "localized_name": { "type": "string", "nullable": true, "description": "Name resolved via the `locale` query param's fallback chain (exact locale → base language → native name → English name). Only present when `locale` was supplied. **Supporter+ plans only** — silently omitted on lower tiers.", "example": "Ásia" }, "matched_locale": { "type": "string", "nullable": true, "description": "Which fallback tier satisfied the `locale` request: the exact locale (e.g. `pt-BR`), its base language (e.g. `pt`), `native`, or `en` (English fallback). Only present when `locale` was supplied. **Supporter+ plans only** — silently omitted on lower tiers.", "example": "pt" }, "wikiDataId": { "type": "string", "nullable": true, "description": "Wikidata item identifier. **Coordinates tier and above.**" } }, "required": ["id", "name"] }, "Subregion": { "type": "object", "description": "Geographic subregion within a region. Fields returned depend on your plan's data access level.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier", "example": 14 }, "name": { "type": "string", "description": "Subregion name", "example": "Southern Asia" }, "region_id": { "type": "integer", "format": "int64", "description": "Parent region ID", "example": 3 }, "translations": { "type": "string", "nullable": true, "description": "JSON string keyed by language code. **Supporter+ plans only.** Returned when `include_translations=true` or when `fields=translations` explicitly requests it." }, "localized_name": { "type": "string", "nullable": true, "description": "Name resolved via the `locale` query param's fallback chain (exact locale → base language → native name → English name). Only present when `locale` was supplied. **Supporter+ plans only** — silently omitted on lower tiers.", "example": "Ásia Meridional" }, "matched_locale": { "type": "string", "nullable": true, "description": "Which fallback tier satisfied the `locale` request: the exact locale (e.g. `pt-BR`), its base language (e.g. `pt`), `native`, or `en` (English fallback). Only present when `locale` was supplied. **Supporter+ plans only** — silently omitted on lower tiers.", "example": "pt" }, "wikiDataId": { "type": "string", "nullable": true, "description": "Wikidata item identifier. **Coordinates tier and above.**" } }, "required": ["id", "name", "region_id"] }, "TimezoneInfo": { "type": "object", "description": "IANA timezone with current UTC offset and DST status. Standard and DST offsets are sampled from Jan 1 and Jul 1 of the current year.", "properties": { "iana": { "type": "string", "description": "Canonical IANA timezone identifier", "example": "Asia/Kolkata" }, "abbreviation": { "type": "string", "description": "Locale-aware short code (display only — not unique across timezones)", "example": "IST" }, "offset_utc": { "type": "string", "description": "Standard UTC offset in ±HH:MM format", "example": "+05:30" }, "dst_offset_utc": { "type": "string", "description": "DST UTC offset in ±HH:MM format; equals `offset_utc` for zones without DST", "example": "+05:30" }, "is_dst_now": { "type": "boolean", "description": "Whether DST is currently active", "example": false } }, "required": ["iana", "abbreviation", "offset_utc", "dst_offset_utc", "is_dst_now"] }, "CurrencyInfo": { "type": "object", "description": "Currency data for a country. `currency.name` and `currency.symbol` may be null for a small number of entries.", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "IN" }, "currency": { "type": "object", "properties": { "code": { "type": "string", "description": "ISO 4217 currency code — always present", "example": "INR" }, "name": { "type": "string", "nullable": true, "description": "Full currency name", "example": "Indian rupee" }, "symbol": { "type": "string", "nullable": true, "description": "Unicode currency symbol; fall back to `code` if null", "example": "₹" } }, "required": ["code"] } }, "required": ["country", "currency"] }, "DialCode": { "type": "object", "description": "International dial code entry for a country. Follows ITU-T E.164 standards.", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "IN" }, "dial_code": { "type": "string", "description": "International dial code with `+` prefix", "example": "+91" }, "iso2": { "type": "string", "description": "ISO 3166-1 alpha-2 code", "example": "IN" }, "iso3": { "type": "string", "description": "ISO 3166-1 alpha-3 code", "example": "IND" }, "area_code": { "type": "string", "nullable": true, "description": "Fixed area code for NANP territories (e.g., `246` for Barbados). Present only when applicable.", "example": null } }, "required": ["country", "dial_code", "iso2", "iso3"] }, "PhoneParsed": { "type": "object", "description": "Result of parsing an E.164 phone number. Contains PII (the echoed phone number) — the endpoint returns `Cache-Control: no-store`.", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 code of the originating country", "example": "US" }, "dial_code": { "type": "string", "description": "Country dial code with `+` prefix", "example": "+1" }, "iso2": { "type": "string", "description": "ISO 3166-1 alpha-2 code", "example": "US" }, "iso3": { "type": "string", "description": "ISO 3166-1 alpha-3 code", "example": "USA" }, "national_number": { "type": "string", "description": "Digits after removing the country code", "example": "4155552671" }, "e164": { "type": "string", "description": "Normalized input echoed back", "example": "+14155552671" }, "area_code": { "type": "string", "nullable": true, "description": "Area code for NANP territories only", "example": null } }, "required": ["country", "dial_code", "iso2", "iso3", "national_number", "e164"] }, "IsoCountry": { "type": "object", "description": "Country record returned by the ISO lookup endpoint.", "properties": { "id": { "type": "integer", "description": "Internal CSC country ID", "example": 233 }, "name": { "type": "string", "description": "Official English country name", "example": "United States" }, "iso2": { "type": "string", "description": "ISO 3166-1 alpha-2 code", "example": "US" }, "iso3": { "type": "string", "description": "ISO 3166-1 alpha-3 code", "example": "USA" }, "numeric_code": { "type": "string", "nullable": true, "description": "Zero-padded 3-digit ISO 3166-1 numeric code", "example": "840" } }, "required": ["id", "name", "iso2", "iso3"] }, "IsoState": { "type": "object", "description": "State record returned by the ISO 3166-2 lookup endpoint.", "properties": { "id": { "type": "integer", "description": "Internal CSC state ID", "example": 1416 }, "name": { "type": "string", "description": "State name in English", "example": "California" }, "iso2": { "type": "string", "nullable": true, "description": "Legacy state ISO2 code", "example": "CA" }, "iso3166_2": { "type": "string", "nullable": true, "description": "ISO 3166-2 subdivision code", "example": "US-CA" }, "country_id": { "type": "integer", "description": "Parent country ID", "example": 233 }, "country_code": { "type": "string", "description": "Parent country ISO2 code", "example": "US" } }, "required": ["id", "name", "country_id", "country_code"] }, "IsoConvert": { "type": "object", "description": "Result of an ISO 3166-1 code conversion.", "properties": { "from": { "type": "string", "enum": ["iso2", "iso3", "numeric"], "description": "Source format", "example": "iso2" }, "to": { "type": "string", "enum": ["iso2", "iso3", "numeric"], "description": "Target format", "example": "iso3" }, "input": { "type": "string", "description": "The input code, echoed back from the `value` query parameter", "example": "US" }, "result": { "type": "string", "description": "The converted code. Numeric results are zero-padded to 3 digits.", "example": "USA" } }, "required": ["from", "to", "input", "result"] }, "FuzzyResult": { "type": "object", "description": "A single result from a fuzzy search, ranked by trigram similarity. Field set depends on the `type` search param (country/state/city) — the fields below note which result type(s) each applies to. Tier gating mirrors the same field on the `Country`/`State`/`City` schemas.", "properties": { "id": { "type": "integer", "description": "Entity ID (city, state, or country)", "example": 57606 }, "name": { "type": "string", "description": "English name of the matched entity", "example": "Mumbai" }, "iso2": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 code (country results) or state ISO code (state results); not present on city results." }, "iso3": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-3 code. Country results only." }, "numeric_code": { "type": "string", "nullable": true, "description": "ISO 3166-1 numeric code. Country results only. **Coordinates tier and above.**" }, "phonecode": { "type": "string", "nullable": true, "description": "International dialling code. Country results only." }, "capital": { "type": "string", "nullable": true, "description": "Capital city name. Country results only." }, "currency": { "type": "string", "nullable": true, "description": "Currency code. Country results only." }, "currency_name": { "type": "string", "nullable": true, "description": "Full currency name. Country results only. **Coordinates tier and above.**" }, "currency_symbol": { "type": "string", "nullable": true, "description": "Currency symbol. Country results only. **Coordinates tier and above.**" }, "tld": { "type": "string", "nullable": true, "description": "Top-level domain. Country results only. **Coordinates tier and above.**" }, "nationality": { "type": "string", "nullable": true, "description": "Nationality/demonym. Country results only. **Coordinates tier and above.**" }, "region": { "type": "string", "nullable": true, "description": "Geographic region. Country results only." }, "region_id": { "type": "integer", "nullable": true, "description": "Region identifier. Country results only." }, "subregion": { "type": "string", "nullable": true, "description": "Geographic subregion. Country results only." }, "subregion_id": { "type": "integer", "nullable": true, "description": "Subregion identifier. Country results only." }, "timezones": { "type": "string", "nullable": true, "description": "JSON string of timezone objects. Country results only." }, "emoji": { "type": "string", "nullable": true, "description": "Flag emoji. Country results only." }, "emojiU": { "type": "string", "nullable": true, "description": "Flag emoji Unicode points. Country results only. **Coordinates tier and above.**" }, "gdp": { "type": "integer", "format": "int64", "nullable": true, "description": "Gross domestic product (USD). Country results only. **Coordinates tier and above.**" }, "area_sq_km": { "type": "string", "nullable": true, "description": "Area in square kilometres. Country results only. **Coordinates tier and above.**" }, "postal_code_format": { "type": "string", "nullable": true, "description": "Postal code format pattern. Country results only. **Coordinates tier and above.**" }, "postal_code_regex": { "type": "string", "nullable": true, "description": "Postal code validation regex. Country results only. **Coordinates tier and above.**" }, "country_id": { "type": "integer", "format": "int64", "nullable": true, "description": "Parent country ID. State/city results only. Ungated on state results; **Coordinates tier and above** on city results." }, "country_code": { "type": "string", "nullable": true, "description": "Parent country ISO2 code. State/city results only. Ungated on state results; **Coordinates tier and above** on city results." }, "country_name": { "type": "string", "nullable": true, "description": "Parent country name. State/city results only. Always present regardless of plan tier." }, "state_id": { "type": "integer", "format": "int64", "nullable": true, "description": "Parent state ID. City results only. **Coordinates tier and above.**" }, "state_code": { "type": "string", "nullable": true, "description": "Parent state ISO2 code. City results only. **Coordinates tier and above.**" }, "state_name": { "type": "string", "nullable": true, "description": "Parent state name. City results only. Always present regardless of plan tier." }, "fips_code": { "type": "string", "nullable": true, "description": "FIPS code. State results only. **Coordinates tier and above.**" }, "iso3166_2": { "type": "string", "nullable": true, "description": "ISO 3166-2 subdivision code. State results only. **Coordinates tier and above.**" }, "type": { "type": "string", "nullable": true, "description": "Administrative type (state results) or settlement type (city results). **Coordinates tier and above.**" }, "level": { "type": "integer", "nullable": true, "description": "Administrative level. State/city results only. **Coordinates tier and above.**" }, "parent_id": { "type": "integer", "format": "int64", "nullable": true, "description": "Parent subdivision ID (state results) or parent city ID (city results). **Coordinates tier and above.**" }, "native": { "type": "string", "nullable": true, "description": "Name in native language. Ungated on country results; **Coordinates tier and above** on state/city results." }, "population": { "type": "integer", "format": "int64", "nullable": true, "description": "Population count. **Coordinates tier and above.**" }, "latitude": { "type": "string", "nullable": true, "description": "Latitude coordinate. Ungated on country/state results; **Coordinates tier and above** on city results." }, "longitude": { "type": "string", "nullable": true, "description": "Longitude coordinate. Ungated on country/state results; **Coordinates tier and above** on city results." }, "timezone": { "type": "string", "nullable": true, "description": "IANA timezone identifier. State/city results only. Ungated on state results; **Coordinates tier and above** on city results." }, "translations": { "type": "string", "nullable": true, "description": "JSON string of translations. **Supporter+ plans only, and only when `include_translations=true` is passed.**" }, "wikiDataId": { "type": "string", "nullable": true, "description": "Wikidata item identifier. **Full access level only.**" }, "localized_name": { "type": "string", "nullable": true, "description": "Localized display name selected by `locale`. The English `name` remains unchanged. **Supporter+ plans only.**", "example": "ムンバイ" }, "matched_locale": { "type": "string", "nullable": true, "description": "Translation or fallback used for `localized_name`: the exact locale, base language, `native`, or `en`. **Supporter+ plans only.**", "example": "ja" }, "match_score": { "type": "number", "description": "Trigram similarity score (0–1, rounded to 2 decimals). Higher is a closer match.", "example": 0.85 }, "matched_alias": { "type": "string", "nullable": true, "description": "Native-script name if it scored higher than the English name; `null` otherwise", "example": null } }, "required": ["id", "name", "match_score"] }, "AutocompleteResult": { "type": "object", "description": "A single result from a location autocomplete query, ranked by relevance (exact match, then starts-with, then fuzzy). Field set depends on `type`. Note: unlike most other city fields, `country_code` and `state_code` on city results are always returned regardless of plan tier, since the client needs them to disambiguate the `label`.", "properties": { "type": { "type": "string", "enum": ["country", "state", "city"], "description": "Entity type of the matched result", "example": "city" }, "label": { "type": "string", "description": "Ready-to-display label. When `locale` is supplied on a Supporter+ plan, the first place name is localized. Parent state and country names remain English.", "example": "ムンバイ, Maharashtra, India" }, "id": { "type": "integer", "format": "int64", "description": "Entity ID (city, state, or country)", "example": 57606 }, "name": { "type": "string", "description": "English name of the matched entity", "example": "Mumbai" }, "translations": { "type": "string", "nullable": true, "description": "JSON string of translations. **Supporter+ plans only, and only when `include_translations=true` is passed.**" }, "localized_name": { "type": "string", "nullable": true, "description": "Localized display name selected by `locale`. The English `name` remains unchanged. **Supporter+ plans only.**", "example": "ムンバイ" }, "matched_locale": { "type": "string", "nullable": true, "description": "Translation or fallback used for `localized_name`: the exact locale, base language, `native`, or `en`. **Supporter+ plans only.**", "example": "ja" }, "iso2": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 code (`type=country`) or state ISO code (`type=state`). Not present on `type=city` results.", "example": "IN" }, "iso3": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-3 code. Only present for `type=country`; not present otherwise.", "example": "IND" }, "state_code": { "type": "string", "nullable": true, "description": "Parent state ISO code. Always present for `type=city`; `null` otherwise.", "example": "MH" }, "country_code": { "type": "string", "nullable": true, "description": "Parent country ISO2 code. Always present for `type=city` and `type=state`; `null` for `type=country`.", "example": "IN" }, "match_score": { "type": "number", "description": "Relevance score (0–1, rounded to 2 decimals). Higher is a closer match.", "example": 0.95 }, "matched_field": { "type": "string", "enum": ["name", "native", "translation"], "description": "Which field the match was found against.", "example": "translation" } }, "required": ["type", "label", "id", "name", "match_score", "matched_field"] }, "NearbyResult": { "type": "object", "description": "One nearby result. Normal fields depend on the selected entity type and API plan.", "properties": { "type": { "type": "string", "nullable": true, "description": "Raw source type for a state or city. This is not the country/state/city query type. Available on the coordinates tier and above.", "example": "city" }, "kind": { "type": "string", "enum": ["settlement", "administrative", "section", "unknown"], "description": "Derived city classification. Present on city results for every plan.", "example": "settlement" }, "id": { "type": "integer", "format": "int64", "description": "Entity ID", "example": 57606 }, "name": { "type": "string", "description": "English place name", "example": "Mumbai" }, "translations": { "type": "string", "nullable": true, "description": "JSON string of translations. **Supporter+ plans only, and only when `include_translations=true` is passed.**" }, "localized_name": { "type": "string", "nullable": true, "description": "Localized display name selected by `locale`. The English `name` remains unchanged. **Supporter+ plans only.**", "example": "ムンバイ" }, "matched_locale": { "type": "string", "nullable": true, "description": "Translation or fallback used for `localized_name`: the exact locale, base language, `native`, or `en`. **Supporter+ plans only.**", "example": "ja" }, "iso2": { "type": "string", "nullable": true, "description": "Country ISO2 code for countries or state ISO code for states. Not present on city results.", "example": "IN" }, "iso3": { "type": "string", "nullable": true, "description": "Country ISO3 code. Present only on country results.", "example": "IND" }, "state_code": { "type": "string", "nullable": true, "description": "Parent state code for city results. Available on the coordinates tier and above.", "example": "MH" }, "country_code": { "type": "string", "nullable": true, "description": "Parent country code. Always present on state results; available on city results on the coordinates tier and above.", "example": "IN" }, "country_name": { "type": "string", "description": "Parent country name. Present on state and city results for every plan.", "example": "India" }, "state_name": { "type": "string", "nullable": true, "description": "Parent state name. Present on city results for every plan; null when there is no parent state.", "example": "Maharashtra" }, "distance_km": { "type": "number", "description": "Straight-line distance from the search origin in kilometers", "example": 3.42 } }, "required": ["id", "name", "distance_km"] }, "ChangeRecord": { "type": "object", "description": "One recorded change. Fields inside `old_values` and `new_values` are filtered to the caller's data access level.", "properties": { "change_id": { "type": "string", "format": "uuid", "description": "Unique ID for this change", "example": "6b30c790-c46f-4a0f-b7f2-ea1a1a9d8362" }, "data_version": { "type": "string", "description": "Dataset release that produced this change", "example": "v3.2-export.7-2026.08.24" }, "changed_at": { "type": "string", "format": "date-time", "description": "When the release was recorded", "example": "2026-08-24T08:15:00.000Z" }, "place_type": { "type": "string", "enum": ["country", "state", "city"], "example": "city" }, "place_id": { "type": "string", "description": "Stable ID of the changed place", "example": "57606" }, "change_type": { "type": "string", "enum": ["added", "removed", "renamed", "place_group_changed", "parent_changed", "coordinates_changed", "other_fields_changed"], "example": "renamed" }, "old_values": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Values before the change. `null` for an added place." }, "new_values": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Values after the change. `null` for a removed place." } }, "required": ["change_id", "data_version", "changed_at", "place_type", "place_id", "change_type", "old_values", "new_values"] }, "ChangeFeedResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeRecord" } }, "next_page_token": { "type": "string", "nullable": true, "maxLength": 4096, "pattern": "^[A-Za-z0-9_-]+$", "description": "Opaque cursor for the next page, or `null` after the last page." } }, "required": ["results", "next_page_token"] }, "ChangeFeedError": { "type": "object", "properties": { "status": { "type": "string", "enum": ["error"] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true, "description": "Extra context when available, including `earliestAvailableDate` for an expired retention window." } }, "required": ["status", "message"] }, "ChangeFeedFeatureError": { "type": "object", "properties": { "status": { "type": "string", "enum": ["error"] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "feature": { "type": "string", "enum": ["dataChangeFeed"] }, "currentTier": { "type": "string" }, "requiredTier": { "type": "string", "nullable": true }, "upgradeUrl": { "type": "string", "format": "uri" } }, "required": ["feature", "currentTier", "requiredTier", "upgradeUrl"] } }, "required": ["status", "message", "details"] }, "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"] }, "FeatureError": { "type": "object", "properties": { "status": { "type": "string", "enum": ["error"] }, "message": { "type": "string", "example": "This feature is not available on your current plan." }, "details": { "type": "object", "properties": { "feature": { "type": "string", "description": "The feature flag that was denied", "example": "bulkStates" }, "currentTier": { "type": "string", "example": "community" }, "requiredTier": { "type": "string", "nullable": true, "description": "Lowest plan that unlocks the feature; null when it cannot be determined", "example": "starter" }, "upgradeUrl": { "type": "string", "format": "uri", "example": "https://countrystatecity.in/pricing" } }, "required": ["feature", "currentTier", "requiredTier", "upgradeUrl"] } }, "required": ["status", "message", "details"] }, "Postcode": { "type": "object", "description": "A postcode record. `id` and foreign keys are numeric strings for 64-bit safety. Fields above the Basic tier are stripped, not nulled, for lower plans.", "properties": { "id": { "type": "string", "pattern": "^[0-9]+$", "description": "Unique identifier, as a numeric string", "example": "670115" }, "code": { "type": "string", "description": "Postcode as stored, original spacing and casing preserved", "example": "11104" }, "country_code": { "type": "string", "description": "ISO2 country code", "example": "LK" }, "state_code": { "type": "string", "nullable": true, "description": "State/province code, when linked", "example": "12" }, "locality_name": { "type": "string", "nullable": true, "description": "Place name associated with the postcode", "example": "Wattala" }, "type": { "type": "string", "nullable": true, "description": "Source-provided classification (not a fixed enum), e.g. `full`, `area`, `fsa`, `po_box`, `street`", "example": "full" }, "country_id": { "type": "string", "pattern": "^[0-9]+$", "description": "Country ID. **Coordinates tier and above.**", "example": "208" }, "state_id": { "type": "string", "pattern": "^[0-9]+$", "description": "State ID. **Coordinates tier and above.**", "nullable": true, "example": "2804" }, "city_id": { "type": "string", "pattern": "^[0-9]+$", "description": "City ID, when linked to a city. **Coordinates tier and above.**", "nullable": true }, "latitude": { "type": "number", "nullable": true, "description": "Latitude. **Coordinates tier and above.**", "example": 6.9906677 }, "longitude": { "type": "number", "nullable": true, "description": "Longitude. **Coordinates tier and above.**", "example": 79.8931709 }, "source": { "type": "string", "nullable": true, "description": "Originating data source. **Full tier only.**" }, "wikiDataId": { "type": "string", "nullable": true, "description": "Wikidata Q-ID. **Full tier only.**" } }, "required": ["id", "code", "country_code"] }, "PostcodeLookupResponse": { "type": "object", "properties": { "data": { "type": "array", "description": "Every record matching the code, ascending `id`. Never empty (no match is a `404`).", "items": { "$ref": "#/components/schemas/Postcode" } }, "meta": { "type": "object", "properties": { "country_code": { "type": "string", "example": "LK" }, "query": { "type": "string", "description": "Normalised code used for matching (trimmed, uppercased, repeated spaces collapsed)", "example": "11104" }, "match_count": { "type": "integer", "example": 3 } } } }, "required": ["data", "meta"] }, "PostcodeListResponse": { "type": "object", "properties": { "data": { "type": "array", "description": "Matching records for this page, ordered by code then `id`", "items": { "$ref": "#/components/schemas/Postcode" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque token for the next page, `null` on the last page" }, "has_more": { "type": "boolean" } } } }, "required": ["data", "pagination"] }, "DataVersion": { "type": "object", "properties": { "dataVersion": { "type": "string", "description": "`-`; 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"] } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized. You shouldn't be here." } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Country not found." } } } }, "FeatureRestricted": { "description": "Feature not available on your current plan. Upgrade to access this endpoint. `details.feature` names the denied feature and `details.requiredTier` the lowest plan that includes it (the example is for `/states`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureError" }, "example": { "status": "error", "message": "This feature is not available on your current plan.", "details": { "feature": "bulkStates", "currentTier": "community", "requiredTier": "starter", "upgradeUrl": "https://countrystatecity.in/pricing" } } } } }, "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" } } } } }, "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" } }, "CacheControl": { "description": "Cache directive", "schema": { "type": "string", "example": "public, max-age=3600" } }, "ETag": { "description": "Entity tag for conditional requests (use with `If-None-Match`)", "schema": { "type": "string", "example": "\"a3f2b8c1d4e5f6a7b8c9d0e1f2a3b4c5\"" } }, "XCache": { "description": "Whether the response was served from cache", "schema": { "type": "string", "enum": ["HIT", "MISS"], "example": "HIT" } }, "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" } } }, "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" } } } }