Geocoding API endpoint
Looks up OpenStreetMap objects by the required `osm_ids`, a comma-separated list prefixed `N` (node), `W` (way) or `R` (relation), such as `W34633854,N123`. Each place has its display name, category and type, coordinates, bounding box, importance and address parts; `addressdetails` defaults to true, and `extratags`, `namedetails` and `accept_language` are optional. Malformed ids return `400`; no match returns `404`.
/geocoding/lookupReturns typed Nominatim JSONv2 places for one or more OpenStreetMap object ids.
Query parameters: osm_ids is required and must be a comma-separated list such as W34633854,N123,R456, where the prefix is N for node, W for way, or R for relation. Optional parameters are accept_language, addressdetails, extratags, and namedetails. addressdetails defaults to true.
Notable response behavior: malformed OSM ids return 400. Empty Nominatim result sets return 404. Upstream rate limits, non-2xx responses, Nominatim error payloads, and malformed JSON return 503.
| Field | Filled in, of 1 checked | Values in the sample |
|---|---|---|
| place_id | 1 | |
| licence | 1 | “Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org…” |
| osm_type | 1 | “way” |
| osm_id | 1 | |
| lat | 1 | |
| lon | 1 | |
| category | 1 | “office” |
| type | 1 | “yes” |
| place_rank | 1 | 30 |
| importance | 1 | 0.58 |
| addresstype | 1 | “office” |
| name | 1 | “Empire State Building” |
| display_name | 1 | median 138 characters |
| address | 1 | |
| boundingbox | 1 | median 4 entries |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| osm_ids | string | Yes | Comma-separated OSM ids such as W34633854,N123,R456 | W34633854 | |
| accept_language | string | No | Preferred result language, forwarded to Nominatim | ||
| addressdetails | boolean | No | true | Include address details, defaults to true | |
| extratags | boolean | No | Include OSM extra tags | ||
| namedetails | boolean | No | Include multilingual name details | ||
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/geocoding/lookup?osm_ids=W34633854&addressdetails=true&extratags=true&namedetails=true" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"query": "W34633854",
"results": [
{
"place_id": 358220252,
"osm_type": "way",
"osm_id": 34633854,
"lat": "40.7484421",
"lon": "-73.9856589",
"category": "office",
"type": "yes",
"place_rank": 30,
"importance": 0.5803438355141769,
"addresstype": "office",
"name": "Empire State Building",
"display_name": "Empire State Building, 350, 5th Avenue, New York, United States",
"address": {
"office": "Empire State Building",
"house_number": "350",
"road": "5th Avenue",
"city": "New York",
"state": "New York",
"postcode": "10118",
"country": "United States",
"country_code": "us"
},
"extratags": {
"website": "https://www.esbnyc.com",
"wikidata": "Q9188"
},
"namedetails": {
"name": "Empire State Building",
"name:en": "Empire State Building"
}
}
]
}
}Request schema
No body schema
Response schema
#/definitions/geocoding.lookupResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | geocoding.LookupResponse | No | ||||
| data.query | string | No | W34633854,N123 | |||
| data.results | array | No | Place record, 33 fields: address, addresstype, boundingbox, category, display_name, extratags, importance, lat, licence, lon, name, namedetails and 5 more. Described under Geocoding Reverse API. | |||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 404 | Not Found | #/definitions/app.Response |
| 502 | Bad Gateway | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/geocoding/lookup?osm_ids=W34633854&addressdetails=true&extratags=true&namedetails=true" \
-H "x-api-key: $CRAWLORA_API_KEY"