Fuzzy Search

Typo-tolerant search for cities, states, and countries using trigram similarity

GET /v1/search/fuzzy

cURL (typo)

curl -X GET 'https://api.countrystatecity.in/v1/search/fuzzy?q=Banglore&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: 'Banglore', 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': 'Banglore', 'type': 'city', 'country': 'IN'},
  headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)

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

200 - City match (Professional / Business)

[
  {
    "id": 57885,
    "name": "Bangalore",
    "state_id": 4026,
    "state_code": "KA",
    "country_id": 101,
    "country_code": "IN",
    "latitude": "12.97194000",
    "longitude": "77.59369000",
    "timezone": "Asia/Kolkata",
    "native": "ಬೆಂಗಳೂರು",
    "match_score": 0.87,
    "matched_alias": null
  }
]

[
  {
    "id": 57885,
    "name": "Bangalore",
    "native": "ಬೆಂಗಳೂರು",
    "match_score": 1,
    "matched_alias": "ಬೆಂಗಳೂರು"
  }
]

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

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

{
  "error": "This feature is not available on your current plan.",
  "feature": "fuzzySearch",
  "upgradeUrl": "https://app.countrystatecity.in/pricing"
}

Search cities, states, and countries by an approximate query that tolerates misspellings, transliterations, and native-script variants. Unlike the exact/substring inline search (?q=), fuzzy search ranks results by how similar they are to your query, so Banglore still resolves to Bangalore 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: Professional plan and above. Returns 403 on Community, Starter, and Supporter plans.

Each result is scored against both the English and native names; the higher of the two wins. Responses are cached server-side, keyed by query, type, country filter, limit, threshold, and your plan’s data-access level.

Authentication

X-CSCAPI-KEY · string · required

Your API key for authentication

Query Parameters

q · string · required

The search text. 2–100 characters. Matched case-insensitively against the English and native names.

type · string · default: "city"

What to search. One of city, state, or country.

country · string

Restrict results to a single country by ISO 3166-1 alpha-2 code, e.g. IN, US. Case-insensitive (auto-uppercased). Applies to type=city and type=state only — sending it with type=country returns 400.

limit · integer · default: "10"

Maximum number of results to return. 1–50.

threshold · number · default: "0.3"

Minimum trigram similarity a row must reach to be returned. 0.1–1. Lower values are more permissive (more, looser matches); higher values are stricter. The default 0.3 is a good balance for typo tolerance.

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 — Professional and Business resolve to the full field set — plus two fuzzy-specific fields:

match_score · number

Trigram similarity of the best-matching name (English or native), from 0 to 1, rounded to 2 decimals. Higher means a closer match.

matched_alias · string | null

The native name when it scored higher than the English name (e.g. a Devanagari or Han query that matched the local spelling). null when the English name was the better match.

cURL (typo)

curl -X GET 'https://api.countrystatecity.in/v1/search/fuzzy?q=Banglore&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: 'Banglore', 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': 'Banglore', 'type': 'city', 'country': 'IN'},
  headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)

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

200 - City match (Professional / Business)

[
  {
    "id": 57885,
    "name": "Bangalore",
    "state_id": 4026,
    "state_code": "KA",
    "country_id": 101,
    "country_code": "IN",
    "latitude": "12.97194000",
    "longitude": "77.59369000",
    "timezone": "Asia/Kolkata",
    "native": "ಬೆಂಗಳೂರು",
    "match_score": 0.87,
    "matched_alias": null
  }
]

[
  {
    "id": 57885,
    "name": "Bangalore",
    "native": "ಬೆಂಗಳೂರು",
    "match_score": 1,
    "matched_alias": "ಬೆಂಗಳೂರು"
  }
]

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

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

{
  "error": "This feature is not available on your current plan.",
  "feature": "fuzzySearch",
  "upgradeUrl": "https://app.countrystatecity.in/pricing"
}

Related Endpoints

• 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