Direct API
Localities Search
Search for localities/cities within a specific country
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_code | string | Yes | ISO 3166-1 alpha-2 country code (e.g., "RO", "BG") - Path parameter |
| search | string | Yes | Search 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_page | number | No | Number of results per page. Allowed values: 15, 50, 100, 200 (default: 15) - Query parameter |
Response Codes
| Code | Status | Description |
|---|---|---|
| 200 | Success | Localities found successfully |
| 400 | Bad Request | Invalid request parameters (e.g., country code must be exactly 2 letters) |
| 401 | Unauthorized | Invalid or missing API key |
| 404 | Not Found | No localities found |
| 422 | Validation Error | Validation error (search field required, min 2 chars, per_page invalid, etc.) |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | An unexpected error occurred |
Response Format
| Field | Type | Description |
|---|---|---|
| data | array | Array of locality objects |
| meta | object | Pagination and search metadata |
| data[].id | integer | Unique locality identifier |
| data[].name | string | Locality name |
| data[].county | string | County name |
| data[].name_and_county | string | Combined display name |
| data[].county_code | string | County code abbreviation |
| meta.count | integer | Total number of results |
| meta.per_page | integer | Results per page |
| meta.country_code | string | Requested country code |
| meta.search_term | string | Requested search term |
Response Example
{
"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
