Geocoding API endpoint
Returns the nearest OpenStreetMap place for the required `lat` and `lon`. `zoom` (0 to 18, default 18) sets the level of detail; `addressdetails` defaults to true, and `extratags`, `namedetails` and `accept_language` are optional. The place has its display name, category and type, OSM type and id, bounding box, importance and address parts. Out-of-range coordinates return `400`; no place found returns `404`.
/geocoding/reverseQuery parameters: lat and lon are required. Optional parameters are zoom, accept_language, addressdetails, extratags, and namedetails. zoom defaults to 18 and must be between 0 and 18; addressdetails defaults to true.
Notable response behavior: missing or out-of-range coordinates return 400. Empty reverse geocoding results and an Unable to geocode response return 404. Connection failures, rate limits, overloads, unknown provider error payloads, and malformed responses remain upstream failures.
| Field | In the sample | Value in the sample |
|---|---|---|
| place_id | Has a value | |
| licence | Has a value | “Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org…” |
| osm_type | Has a value | “node” |
| osm_id | Has a value | |
| lat | Has a value | |
| lon | Has a value | |
| category | Has a value | “tourism” |
| type | Has a value | “viewpoint” |
| place_rank | Has a value | 30 |
| importance | Has a value | 0 |
| addresstype | Has a value | “tourism” |
| name | Empty | |
| display_name | Has a value | 115 characters |
| address | Has a value | |
| boundingbox | Has a value | 4 entries |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| lat | number | Yes | Latitude | 40.7484257 | |
| lon | number | Yes | Longitude | -73.98567 | |
| zoom | integer | No | 18 | Nominatim address zoom, defaults to 18 | |
| 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/reverse?lat=40.7484257&lon=-73.98567&addressdetails=true&extratags=true&namedetails=true" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"place_id": 359125914,
"osm_type": "node",
"osm_id": 13306330095,
"lat": "40.7484257",
"lon": "-73.9856700",
"category": "tourism",
"type": "viewpoint",
"place_rank": 30,
"importance": 0.0000917593652246436,
"addresstype": "tourism",
"name": "",
"display_name": "350, 5th Avenue, Koreatown, Manhattan, New York, 10118, United States",
"address": {
"house_number": "350",
"road": "5th Avenue",
"neighbourhood": "Koreatown",
"suburb": "Manhattan",
"city": "New York",
"state": "New York",
"postcode": "10118",
"country": "United States",
"country_code": "us"
},
"boundingbox": [
"40.7483757",
"40.7484757",
"-73.9857200",
"-73.9856200"
]
}
}Request schema
No body schema
Response schema
#/definitions/geocoding.reverseResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | geocoding.Place | No | ||||
| data.address | object | No | Structured address breakdown of the place. | |||
| data.address.ISO3166-2-lvl4 | string | No | US-NY | ISO 3166-2 code for the state or region level, such as `US-NY`. | ||
| data.address.ISO3166-2-lvl6 | string | No | ISO 3166-2 code for the level-6 administrative area, when one exists. | |||
| data.address.city | string | No | New York | City of the place. | ||
| data.address.country | string | No | United States | Country name of the place. | ||
| data.address.country_code | string | No | us | Two-letter country code of the place in lowercase, such as `us`. | ||
| data.address.county | string | No | New York County | County of the place. | ||
| data.address.house_number | string | No | 350 | House number of the place. | ||
| data.address.neighbourhood | string | No | Koreatown | Neighbourhood of the place. | ||
| data.address.office | string | No | Empire State Building | Office name of the place, such as `Empire State Building`. | ||
| data.address.postcode | string | No | 10118 | Postal code of the place. | ||
| data.address.road | string | No | 5th Avenue | Street name of the place. | ||
| data.address.state | string | No | New York | State or region of the place. | ||
| data.address.state_district | string | No | State district of the place. | |||
| data.address.suburb | string | No | Manhattan | Suburb or borough of the place. | ||
| data.address.town | string | No | Town of the place. | |||
| data.address.village | string | No | Village of the place. | |||
| data.addresstype | string | No | office | Type of address the place represents, such as `office`. | ||
| data.boundingbox | array | No | 40.7479255,40.7489585,-73.9865012,-73.9848166 | Bounding box of the place as four decimal-degree strings: south latitude, north latitude, west longitude, east longitude. | ||
| data.category | string | No | office | OpenStreetMap category of the place, such as `office`. | ||
| data.display_name | string | No | Empire State Building, 350, 5th Avenue, New York, United States | Full address of the place as a comma-separated string. | ||
| data.extratags | object | No | Additional OpenStreetMap tags of the place. Present only when `extratags` is requested. | |||
| data.importance | number | No | 0.5803438355141769 | Importance score of the place; higher values mean a more prominent place. | ||
| data.lat | string | No | 40.7484421 | Latitude of the place in decimal degrees, as a string. | ||
| data.licence | string | No | Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright | Licence notice for the OpenStreetMap data. | ||
| data.lon | string | No | -73.9856589 | Longitude of the place in decimal degrees, as a string. | ||
| data.name | string | No | Empire State Building | Name of the place. | ||
| data.namedetails | object | No | Alternative names of the place. Present only when `namedetails` is requested. | |||
| data.osm_id | integer | No | 34633854 | OpenStreetMap id of the object. | ||
| data.osm_type | string | No | way | OpenStreetMap object type, such as `way`. | ||
| data.place_id | integer | No | 358220252 | Numeric id of the place in the geocoding results. | ||
| data.place_rank | integer | No | 30 | Address rank of the place; for example `30` for a building. | ||
| data.type | string | No | yes | OpenStreetMap type of the place within its `category`, such as `yes`. | ||
| 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/reverse?lat=40.7484257&lon=-73.98567&addressdetails=true&extratags=true&namedetails=true" \
-H "x-api-key: $CRAWLORA_API_KEY"