Direct API

Localities Search

Search for localities/cities within a specific country

GET
/search/localities/{country_code}/{search}

Advanced locality search with sophisticated matching including: reversed county-city queries, complex punctuation handling, multiple normalization approaches, and intelligent sorting. Results are cached globally for 5 seconds.

Parameters

Name Type Required Description
country_codestringYesISO 3166-1 alpha-2 country code (e.g., "RO", "BG") - Path parameter
searchstringYesSearch term for locality name. Supports: diacritics, complex punctuation, reversed county-city queries (e.g., "Sibiu Medias" finds "Medias (Sibiu)"), and mixed normalization. Minimum 2 characters, maximum 100 characters. - Path parameter
per_pagenumberNoNumber of results per page. Allowed values: 15, 50, 100, 200 (default: 15) - Query parameter

Response Codes

Code Status Description
200SuccessLocalities found successfully
400Bad RequestInvalid request parameters (e.g., country code must be exactly 2 letters)
401UnauthorizedInvalid or missing API key
404Not FoundNo localities found
422Validation ErrorValidation error (search field required, min 2 chars, per_page invalid, etc.)
429Too Many RequestsRate limit exceeded
500Internal Server ErrorAn unexpected error occurred

Response Format

Field Type Description
dataarrayArray of locality objects
metaobjectPagination and search metadata
data[].idintegerUnique locality identifier
data[].namestringLocality name
data[].countystringCounty name
data[].name_and_countystringCombined display name
data[].county_codestringCounty code abbreviation
meta.countintegerTotal number of results
meta.per_pageintegerResults per page
meta.country_codestringRequested country code
meta.search_termstringRequested search term

Response Example

RESPONSEJSON
{
  "data": [
    {
      "id": 13891,
      "name": "Sector 1",
      "county": "Bucuresti",
      "name_and_county": "Bucuresti (Sector 1)",
      "county_code": "B"
    },
    {
      "id": 13892,
      "name": "Sector 2",
      "county": "Bucuresti",
      "name_and_county": "Bucuresti (Sector 2)",
      "county_code": "B"
    }
  ],
  "meta": {
    "count": 7,
    "per_page": 15,
    "country_code": "RO",
    "search_term": "Bucuresti"
  }
}

Complete API Reference

For interactive testing and additional technical details, visit our complete Swagger documentation.

View in Swagger Documentation