X-Git-Url: https://git.openstreetmap.org./nominatim.git/blobdiff_plain/41c4b51be5ff6f1d94e0899665b814a805691d8c..a92bd1e2db868548a6314fe981e1facebbe700a1:/docs/api/Output.md?ds=sidebyside diff --git a/docs/api/Output.md b/docs/api/Output.md index 5a339420..c8589f64 100644 --- a/docs/api/Output.md +++ b/docs/api/Output.md @@ -1,6 +1,6 @@ # Place Output -The [\reverse](Reverse.md), [\search](Search.md) and [\lookup](Lookup.md) +The [/reverse](Reverse.md), [/search](Search.md) and [/lookup](Lookup.md) API calls produce very similar output which is explained in this section. There is one section for each format which is selectable via the `format` parameter. @@ -46,15 +46,16 @@ a single place (for reverse) of the following format: The possible fields are: - * `place_id` - reference to the Nominatim internal database ID + * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id)) * `osm_type`, `osm_id` - reference to the OSM object - * `boundingbox` - area of corner coordinates + * `boundingbox` - area of corner coordinates ([see notes](#boundingbox)) * `lat`, `lon` - latitude and longitude of the centroid of the object * `display_name` - full comma-separated address * `class`, `type` - key and value of the main OSM tag * `importance` - computed importance rank * `icon` - link to class icon (if available) - * `address` - dictionary of address details (only with `addressdetails=1`) + * `address` - dictionary of address details (only with `addressdetails=1`, + [see notes](#addressdetails)) * `extratags` - dictionary with additional useful tags like website or maxspeed (only with `extratags=1`) * `namedetails` - dictionary with full list of available names including ref etc. @@ -70,20 +71,21 @@ This is the same as the JSON format with two changes: ### GeoJSON -This format follows the [RFC7946](http://geojson.org). Every feature includes +This format follows the [RFC7946](https://geojson.org). Every feature includes a bounding box (`bbox`). The feature list has the following fields: - * `place_id` - reference to the Nominatim internal database ID + * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id)) * `osm_type`, `osm_id` - reference to the OSM object * `category`, `type` - key and value of the main OSM tag * `display_name` - full comma-separated address * `place_rank` - class search rank * `importance` - computed importance rank * `icon` - link to class icon (if available) - * `address` - dictionary of address details (only with `addressdetails=1`) - * `extratags` - dictionary with additional useful tags like website or maxspeed + * `address` - dictionary of address details (only with `addressdetails=1`, + [see notes](#addressdetails)) + * `extratags` - dictionary with additional useful tags like `website` or `maxspeed` (only with `extratags=1`) * `namedetails` - dictionary with full list of available names including ref etc. @@ -100,12 +102,9 @@ The following feature attributes are implemented: * `type` - value of the main tag of the object (e.g. residential, restaurant, ...) * `label` - full comma-separated address * `name` - localised name of the place - * `housenumber`, `street`, `locality`, `postcode`, `city`, - `district`, `county`, `state`, `country` - + * `housenumber`, `street`, `locality`, `district`, `postcode`, `city`, + `county`, `state`, `country` - provided when it can be determined from the address - (see [this issue](https://github.com/openstreetmap/Nominatim/issues/1080) for - current limitations on the correctness of the address) and `addressdetails=1` - was given * `admin` - list of localised names of administrative boundaries (only with `addressdetails=1`) Use `polygon_geojson` to output the full geometry of the object instead @@ -120,7 +119,7 @@ formats depending on the API call. ``` @@ -203,11 +202,11 @@ generic information about the query: The place information can be found in the `place` elements, of which there may be more than one. The attributes of that element contain: - * `place_id` - reference to the Nominatim internal database ID + * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id)) * `osm_type`, `osm_id` - reference to the OSM object * `ref` - content of `ref` tag if it exists * `lat`, `lon` - latitude and longitude of the centroid of the object - * `boundingbox` - comma-separated list of corner coordinates + * `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox)) * `place_rank` - class search rank * `display_name` - full comma-separated address * `class`, `type` - key and value of the main OSM tag @@ -220,3 +219,56 @@ as subelements with the type of the address part. Additional information requested with `extratags=1` and `namedetails=1` can be found in extra elements as sub-element of each place. + +## Notes on field values + +### place_id is not a persistent id + +The `place_id` is created when a Nominatim database gets installed. A +single place will have a different value on another server or even when +the same data gets re-imported. It's thus not useful to treat it as +permanent for later use. + +The combination `osm_type`+`osm_id` is slighly better but remember in +OpenStreetMap mappers can delete, split, recreate places (and those +get a new `osm_id`), there is no link between those old and new ids. +Places can also change their meaning without changing their `osm_id`, +e.g. when a restaurant is retagged as supermarket. For a more in-depth +discussion see [Permanent ID](https://wiki.openstreetmap.org/wiki/Permanent_ID). + +Nominatim merges some places (e.g. center node of a city with the boundary +relation) so `osm_type`+`osm_id`+`class_name` would be more unique. + +### boundingbox + +Comma separated list of min latitude, max latitude, min longitude, max longitude. +The whole planet would be `-90,90,-180,180`. + +Can we used to pan and center the map on the result, for example with leafletjs +mapping library +`map.fitBounds([[bbox[0],bbox[2]],[bbox[1],bbox[3]]], {padding: [20, 20], maxzoom: 16});` + +Bounds crossing the antimeridian have a min latitude -180 and max latitude 180, +essentially covering the planet (See [issue 184](https://github.com/openstreetmap/Nominatim/issues/184)). + +### addressdetails + +Address details in the xml and json formats return a list of names together +with a designation label. Per default the following labels may appear: + + * continent + * country, country_code + * region, state, state_district, county + * municipality, city, town, village + * city_district, district, borough, suburb, subdivision + * hamlet, croft, isolated_dwelling + * neighbourhood, allotments, quarter + * city_block, residental, farm, farmyard, industrial, commercial, retail + * road + * house_number, house_name + * emergency, historic, military, natural, landuse, place, railway, + man_made, aerialway, boundary, amenity, aeroway, club, craft, leisure, + office, mountain_pass, shop, tourism, bridge, tunnel, waterway + +They roughly correspond to the classification of the OpenStreetMap data +according to either the `place` tag or the main key of the object.