Fuzzy Search

curl -X GET 'https://api.countrystatecity.in/v1/search/fuzzy?q=Mumbay&type=city&country=IN' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

curl -X GET 'https://api.countrystatecity.in/v1/search/fuzzy?q=Deutschlnd&type=country' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

curl -X GET 'https://api.countrystatecity.in/v1/search/fuzzy?q=Munchen&type=city&threshold=0.2&limit=5' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

const params = new URLSearchParams({ q: 'Mumbay', type: 'city', country: 'IN' });
const response = await fetch(
  `https://api.countrystatecity.in/v1/search/fuzzy?${params}`,
  { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);

const matches = await response.json();
matches.forEach((m) => console.log(`${m.name} (${m.match_score})`));

import requests

response = requests.get(
  'https://api.countrystatecity.in/v1/search/fuzzy',
  params={'q': 'Mumbay', 'type': 'city', 'country': 'IN'},
  headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)

for match in response.json():
    print(f"{match['name']} -> {match['match_score']}")

[
  {
    "id": 132649,
    "name": "Mumbai",
    "state_id": 4008,
    "state_code": "MH",
    "country_id": 101,
    "country_code": "IN",
    "latitude": "19.07283000",
    "longitude": "72.88261000",
    "timezone": "Asia/Kolkata",
    "native": "मुंबई",
    "match_score": 0.87,
    "matched_alias": null
  }
]

[
  {
    "id": 132649,
    "name": "Mumbai",
    "native": "मुंबई",
    "match_score": 1,
    "matched_alias": "मुंबई"
  }
]

{
  "status": "error",
  "message": "Invalid query parameters: q: Search query must be at least 2 characters"
}

{
  "status": "error",
  "message": "Invalid query parameters: country: country is not a valid filter when type=country"
}

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

GET

fuzzy

curl -X GET 'https://api.countrystatecity.in/v1/search/fuzzy?q=Mumbay&type=city&country=IN' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

curl -X GET 'https://api.countrystatecity.in/v1/search/fuzzy?q=Deutschlnd&type=country' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

curl -X GET 'https://api.countrystatecity.in/v1/search/fuzzy?q=Munchen&type=city&threshold=0.2&limit=5' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

const params = new URLSearchParams({ q: 'Mumbay', type: 'city', country: 'IN' });
const response = await fetch(
  `https://api.countrystatecity.in/v1/search/fuzzy?${params}`,
  { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);

const matches = await response.json();
matches.forEach((m) => console.log(`${m.name} (${m.match_score})`));

import requests

response = requests.get(
  'https://api.countrystatecity.in/v1/search/fuzzy',
  params={'q': 'Mumbay', 'type': 'city', 'country': 'IN'},
  headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)

for match in response.json():
    print(f"{match['name']} -> {match['match_score']}")

[
  {
    "id": 132649,
    "name": "Mumbai",
    "state_id": 4008,
    "state_code": "MH",
    "country_id": 101,
    "country_code": "IN",
    "latitude": "19.07283000",
    "longitude": "72.88261000",
    "timezone": "Asia/Kolkata",
    "native": "मुंबई",
    "match_score": 0.87,
    "matched_alias": null
  }
]

[
  {
    "id": 132649,
    "name": "Mumbai",
    "native": "मुंबई",
    "match_score": 1,
    "matched_alias": "मुंबई"
  }
]

{
  "status": "error",
  "message": "Invalid query parameters: q: Search query must be at least 2 characters"
}

{
  "status": "error",
  "message": "Invalid query parameters: country: country is not a valid filter when type=country"
}

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

Search cities, states, and countries by an approximate query that tolerates misspellings, transliterations, native-script variants, and stored translations. Unlike the exact/substring inline search (?q=), fuzzy search ranks results by how similar they are to your query, so Mumbay still resolves to Mumbai and Beijng to Beijing. Matching uses PostgreSQL trigram similarity over both the English name and the native name, returning a match_score so you can decide how confident a hit is.

Availability: Supporter plan and above. Returns 403 on Community and Starter plans.

Each result is scored against the English and native names. Queries with at least 3 characters also check stored translations. Responses are cached separately by query, filters, plan, locale, and translation output.

Response

Returns an array sorted by match_score descending. Each item carries the standard fields for the entity (city, state, or country) at your plan’s data-access level — every plan with fuzzy search access (Supporter, Professional, Business) resolves to the full field set — plus two fuzzy-specific fields:

A result found only through a translation can have a low match_score. The score compares the query with the English and native names, not with the translation that matched.

curl -X GET 'https://api.countrystatecity.in/v1/search/fuzzy?q=Mumbay&type=city&country=IN' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

curl -X GET 'https://api.countrystatecity.in/v1/search/fuzzy?q=Deutschlnd&type=country' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

curl -X GET 'https://api.countrystatecity.in/v1/search/fuzzy?q=Munchen&type=city&threshold=0.2&limit=5' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

const params = new URLSearchParams({ q: 'Mumbay', type: 'city', country: 'IN' });
const response = await fetch(
  `https://api.countrystatecity.in/v1/search/fuzzy?${params}`,
  { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);

const matches = await response.json();
matches.forEach((m) => console.log(`${m.name} (${m.match_score})`));

import requests

response = requests.get(
  'https://api.countrystatecity.in/v1/search/fuzzy',
  params={'q': 'Mumbay', 'type': 'city', 'country': 'IN'},
  headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)

for match in response.json():
    print(f"{match['name']} -> {match['match_score']}")

[
  {
    "id": 132649,
    "name": "Mumbai",
    "state_id": 4008,
    "state_code": "MH",
    "country_id": 101,
    "country_code": "IN",
    "latitude": "19.07283000",
    "longitude": "72.88261000",
    "timezone": "Asia/Kolkata",
    "native": "मुंबई",
    "match_score": 0.87,
    "matched_alias": null
  }
]

[
  {
    "id": 132649,
    "name": "Mumbai",
    "native": "मुंबई",
    "match_score": 1,
    "matched_alias": "मुंबई"
  }
]

{
  "status": "error",
  "message": "Invalid query parameters: q: Search query must be at least 2 characters"
}

{
  "status": "error",
  "message": "Invalid query parameters: country: country is not a valid filter when type=country"
}

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

Autocomplete — deterministic exact/starts-with/fuzzy ranking with a ready-to-display label, built for type-ahead UIs
Get All Countries — exact/substring inline search via ?q=
Get Cities by Country — list cities, filterable by ?q=
Lookup Country by ISO Code — resolve a known ISO code to a country

Authorizations

X-CSCAPI-KEY

string

header

required

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

Query Parameters

string

required

Search query — 2 to 100 characters. Case-insensitive.

Required string length: 2 - 100

Example:

"Mumbay"

type

enum<string>

default:city

Entity type to search

Available options:

city,

state,

country

Example:

"city"

country

string

ISO 3166-1 alpha-2 country code to narrow the search (e.g., IN). Ignored when type=country.

Example:

"IN"

limit

integer

default:10

Maximum number of results to return (1–50)

Required range: 1 <= x <= 50

Example:

10

threshold

number

default:0.3

Minimum trigram similarity score (0.1–1.0). Lower values yield looser matches.

Required range: 0.1 <= x <= 1

Example:

0.3

locale

string

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 string length: 2 - 7

Pattern: ^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$

Example:

"ja"

include_translations

boolean

default:false

When true, includes the full translation JSON string. Supporter+ plans only.

Example:

true

Response

List of matching results ranked by similarity score

integer

required

Entity ID (city, state, or country)

Example:

57606

name

string

required

English name of the matched entity

Example:

"Mumbai"

match_score

number

required

Trigram similarity score (0–1, rounded to 2 decimals). Higher is a closer match.

Example:

0.85

iso2

string | null

ISO 3166-1 alpha-2 code (country results) or state ISO code (state results); not present on city results.

iso3

string | null

ISO 3166-1 alpha-3 code. Country results only.

numeric_code

string | null

ISO 3166-1 numeric code. Country results only. Coordinates tier and above.

phonecode

string | null

International dialling code. Country results only.

capital

string | null

Capital city name. Country results only.

currency

string | null

Currency code. Country results only.

currency_name

string | null

Full currency name. Country results only. Coordinates tier and above.

currency_symbol

string | null

Currency symbol. Country results only. Coordinates tier and above.

tld

string | null

Top-level domain. Country results only. Coordinates tier and above.

nationality

string | null

Nationality/demonym. Country results only. Coordinates tier and above.

region

string | null

Geographic region. Country results only.

region_id

integer | null

Region identifier. Country results only.

subregion

string | null

Geographic subregion. Country results only.

subregion_id

integer | null

Subregion identifier. Country results only.

timezones

string | null

JSON string of timezone objects. Country results only.

emoji

string | null

Flag emoji. Country results only.

emojiU

string | null

Flag emoji Unicode points. Country results only. Coordinates tier and above.

gdp

integer<int64> | null

Gross domestic product (USD). Country results only. Coordinates tier and above.

area_sq_km

string | null

Area in square kilometres. Country results only. Coordinates tier and above.

postal_code_format

string | null

Postal code format pattern. Country results only. Coordinates tier and above.

postal_code_regex

string | null

Postal code validation regex. Country results only. Coordinates tier and above.

country_id

integer<int64> | null

Parent country ID. State/city results only. Ungated on state results; Coordinates tier and above on city results.

country_code

string | null

Parent country ISO2 code. State/city results only. Ungated on state results; Coordinates tier and above on city results.

country_name

string | null

Parent country name. State/city results only. Always present regardless of plan tier.

state_id

integer<int64> | null

Parent state ID. City results only. Coordinates tier and above.

state_code

string | null

Parent state ISO2 code. City results only. Coordinates tier and above.

state_name

string | null

Parent state name. City results only. Always present regardless of plan tier.

fips_code

string | null

FIPS code. State results only. Coordinates tier and above.

iso3166_2

string | null

ISO 3166-2 subdivision code. State results only. Coordinates tier and above.

type

string | null

Administrative type (state results) or settlement type (city results). Coordinates tier and above.

level

integer | null

Administrative level. State/city results only. Coordinates tier and above.

parent_id

integer<int64> | null

Parent subdivision ID (state results) or parent city ID (city results). Coordinates tier and above.

native

string | null

Name in native language. Ungated on country results; Coordinates tier and above on state/city results.

population

integer<int64> | null

Population count. Coordinates tier and above.

latitude

string | null

Latitude coordinate. Ungated on country/state results; Coordinates tier and above on city results.

longitude

string | null

Longitude coordinate. Ungated on country/state results; Coordinates tier and above on city results.

timezone

string | null

IANA timezone identifier. State/city results only. Ungated on state results; Coordinates tier and above on city results.

translations

string | null

JSON string of translations. Supporter+ plans only, and only when include_translations=true is passed.

wikiDataId

string | null

Wikidata item identifier. Full access level only.

localized_name

string | null

Localized display name selected by locale. The English name remains unchanged. Supporter+ plans only.

Example:

"ムンバイ"

matched_locale

string | null

Translation or fallback used for localized_name: the exact locale, base language, native, or en. Supporter+ plans only.

Example:

"ja"

matched_alias

string | null

Native-script name if it scored higher than the English name; null otherwise

Example:

null

Countries

States

Cities

Postcodes

Regions

Timezones

Currencies

Phone

ISO Codes

Search

Data Changes

GraphQL API

Meta

Response

Authorizations

Query Parameters

Response

​Response

​Related Endpoints

Authorizations

Query Parameters

Response

Response

Related Endpoints