Datasets API endpoint
Searches the composite Numbeo cities dataset, merged from the current global rankings of all seven index families (cost of living, quality of life, crime, health care, pollution, traffic, property investment). A city appears once it is ranked by at least one family; coverage varies per city. Sort enum: `name_asc`, `cost_of_living_asc`, `cost_of_living_desc`, `quality_of_life_desc`, `safety_desc`, `crime_asc`, `health_care_desc`, `pollution_asc`, `traffic_asc`. Billing: this search costs 1 credit per record returned, with a minimum of 2 (an empty result costs 2, a full page of 100 costs 100).
/datasets/numbeo-cities/searchDataset id enum:
numbeo-citiesQuery parameters:
q: optional full-text query over the city name, max 256 characters.country: optional exact country filter, max 128 characters.min_cost_of_living_index / max_cost_of_living_index: optional Cost of Living Index bounds (New York = 100).min_quality_of_life_index: optional minimum Quality of Life Index.min_crime_index / max_crime_index: optional Crime Index bounds.min_safety_index: optional minimum Safety Index.min_health_care_index: optional minimum Health Care Index.max_pollution_index: optional maximum Pollution Index.max_traffic_index: optional maximum Traffic Index.sort: optional. Allowed values: name_asc, cost_of_living_asc, cost_of_living_desc, quality_of_life_desc, safety_desc, crime_asc, health_care_desc, pollution_asc, traffic_asc. Defaults to relevance with q, otherwise name_asc.page: optional, default 1.page_size: optional, default 20, max 100; page * page_size must not exceed 10000.Response includes dataset, items[] (each a numbeo-cities record — see
Get a Numbeo city from the dataset for the
full field list), page, page_size, total, sort.
1 credit per record returned, minimum 2. A search that returns 20 records costs 20 credits, a full page of 100 costs 100, and an empty or one-record result costs 2. You are charged for what comes back, not for the page_size you ask for, but your balance must cover the requested page_size for the call to be accepted. The response header x-credit-cost shows what a call was charged.
| Field | Filled in, of 2 checked | Values in the sample |
|---|---|---|
| city_slug | 2 | |
| city | 2 | |
| country | 2 | |
| coverage | 2 | median 1 entry |
| cost_of_living_index | 1 | |
| rent_index | 1 | |
| cost_of_living_plus_rent_index | 1 | |
| groceries_index | 1 | |
| restaurant_price_index | 1 | |
| local_purchasing_power_index | 1 | |
| quality_of_life_index | 1 | |
| climate_index | 1 | |
| crime_index | 1 | |
| safety_index | 1 | |
| health_care_index | 1 | |
| health_care_exp_index | 1 | |
| pollution_index | 1 | |
| pollution_exp_index | 1 | |
| traffic_index | 1 | |
| traffic_time_index_minutes | 1 | |
| traffic_time_exp_index | 1 | |
| traffic_inefficiency_index | 1 | |
| traffic_co2_emission_index | 1 | |
| property_price_to_income_ratio | 2 | 8.9 to 23.4, median 8.9 |
| property_gross_rental_yield_city_centre | 2 | 3.3 to 8.3, median 3.3 |
| property_gross_rental_yield_outside_centre | 2 | 7.3 to 7.4, median 7.3 |
| property_price_to_rent_ratio_city_centre | 2 | 12.1 to 30.1, median 12.1 |
| property_price_to_rent_ratio_outside_centre | 2 | 13.6 |
| property_mortgage_pct_of_income | 2 | 82.2 to 252.6, median 82.2 |
| property_affordability_index | 2 | |
| synced_at | 2 | 2026-07-15 to 2026-10-13 |
| schema_version | 2 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| q | string | No | Full-text query over the city name, max 256 characters | ||
| country | string | No | Exact country filter, max 128 characters | ||
| min_cost_of_living_index | number | No | Minimum Cost of Living Index (New York = 100) | ||
| max_cost_of_living_index | number | No | Maximum Cost of Living Index (New York = 100) | ||
| min_quality_of_life_index | number | No | Minimum Quality of Life Index | ||
| min_crime_index | number | No | Minimum Crime Index | ||
| max_crime_index | number | No | Maximum Crime Index | ||
| min_safety_index | number | No | Minimum Safety Index | ||
| min_health_care_index | number | No | Minimum Health Care Index | ||
| max_pollution_index | number | No | Maximum Pollution Index | ||
| max_traffic_index | number | No | Maximum Traffic Index | ||
| sort | string | No | Sort enum: name_asc, cost_of_living_asc, cost_of_living_desc, quality_of_life_desc, safety_desc, crime_asc, health_care_desc, pollution_asc, traffic_asc Allowed values: name_asc, cost_of_living_asc, cost_of_living_desc, quality_of_life_desc, safety_desc, crime_asc, health_care_desc, pollution_asc, traffic_asc. | ||
| page | integer | No | 1 | Page number, defaults to 1 | |
| page_size | integer | No | 20 and maxes at 100 | Page size, defaults to 20 and maxes at 100; page * page_size must be <= 10000 | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/datasets/numbeo-cities/search?q=coffee&country=us&sort=name_asc&page=1" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"dataset": "numbeo-cities",
"items": [
{
"city_slug": "Zurich",
"city": "Zurich, Switzerland",
"country": "Switzerland",
"coverage": [
"cost-of-living",
"quality-of-life",
"crime"
],
"cost_of_living_index": 123.5,
"quality_of_life_index": 193.7,
"crime_index": 24.1,
"safety_index": 75.9,
"synced_at": "2026-07-13T00:00:00Z",
"schema_version": 1
}
],
"page": 1,
"page_size": 20,
"total": 550,
"sort": "name_asc"
}
}Request schema
No body schema
Response schema
#/definitions/datasets.numbeoCitiesSearchResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.NumbeoCitySearchResponse | No | ||||
| data.dataset | string | No | ||||
| data.items | array | No | NumbeoCityRecord record, 35 fields: city, city_slug, climate_index, cost_of_living_index, cost_of_living_plus_rent_index, country, coverage, crime_index, extra_indices, groceries_index, health_care_exp_index, health_care_index and 21 more. Described under Get a Numbeo city from the dataset API. | |||
| data.page | integer | No | ||||
| data.page_size | integer | No | ||||
| data.sort | string | No | ||||
| data.total | integer | No | ||||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/datasets/numbeo-cities/search?q=coffee&country=us&sort=name_asc&page=1" \
-H "x-api-key: $CRAWLORA_API_KEY"