X-Git-Url: https://git.openstreetmap.org./nominatim.git/blobdiff_plain/41c4b51be5ff6f1d94e0899665b814a805691d8c..d856788bf5cf7b4b3e2b4de10f37cf3002ae6826:/docs/api/Output.md?ds=inline diff --git a/docs/api/Output.md b/docs/api/Output.md index 5a339420..75220cf5 100644 --- a/docs/api/Output.md +++ b/docs/api/Output.md @@ -1,20 +1,18 @@ # 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. +There is one section for each format. The format correspond to what was +selected via the `format` parameter. -## Formats - -### JSON +## JSON The JSON format returns an array of places (for search and lookup) or a single place (for reverse) of the following format: ``` { - "place_id": "100149", + "place_id": 100149, "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright", "osm_type": "node", "osm_id": "107775", @@ -30,6 +28,7 @@ a single place (for reverse) of the following format: "city": "London", "state_district": "Greater London", "state": "England", + "ISO3166-2-lvl4": "GB-ENG", "postcode": "SW1A 2DU", "country": "United Kingdom", "country_code": "gb" @@ -41,94 +40,97 @@ a single place (for reverse) of the following format: "wikipedia": "en:London", "population": "8416535" } - }, + } ``` The possible fields are: - * `place_id` - reference to the Nominatim internal database ID - * `osm_type`, `osm_id` - reference to the OSM object - * `boundingbox` - area of corner coordinates + * `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 ([see notes](#osm-reference)) + * `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. * `geojson`, `svg`, `geotext`, `geokml` - full geometry (only with the appropriate `polygon_*` parameter) -### JSONv2 +## JSONv2 This is the same as the JSON format with two changes: * `class` renamed to `category` * additional field `place_rank` with the search rank of the object -### GeoJSON +## 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: +The properties object has the following fields: - * `place_id` - reference to the Nominatim internal database ID - * `osm_type`, `osm_id` - reference to the OSM object + * `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 ([see notes](#osm-reference)) * `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. Use `polygon_geojson` to output the full geometry of the object instead of the centroid. -### GeocodeJSON +## GeocodeJSON The GeocodeJSON format follows the [GeocodeJSON spec 0.1.0](https://github.com/geocoders/geocodejson-spec). The following feature attributes are implemented: - * `osm_type`, `osm_id` - reference to the OSM object (unofficial extension) - * `type` - value of the main tag of the object (e.g. residential, restaurant, ...) + * `osm_type`, `osm_id` - reference to the OSM object (unofficial extension, [see notes](#osm-reference)) + * `type` - the 'address level' of the object ('house', 'street', `district`, `city`, + `county`, `state`, `country`, `locality`) + * `osm_key`- key of the main tag of the OSM object (e.g. boundary, highway, amenity) + * `osm_value` - value of the main tag of the OSM 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 of the centroid. -### XML +## XML The XML response returns one or more place objects in slightly different formats depending on the API call. -#### Reverse +### Reverse ``` - Bavaria, Germany Bavaria + DE-BY Germany de @@ -148,28 +150,28 @@ attribution to OSM and the original querystring. The place information can be found in the `result` element. The attributes of that element contain: - * `place_id` - reference to the Nominatim internal database ID - * `osm_type`, `osm_id` - reference to the OSM object + * `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 ([see notes](#osm-reference)) * `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)) -The full address address of the result can be found in the content of the +The full address of the result can be found in the content of the `result` element as a comma-separated list. Additional information requested with `addressdetails=1`, `extratags=1` and `namedetails=1` can be found in extra elements. -#### Search and Lookup +### Search and Lookup ``` - + @@ -182,6 +184,7 @@ Additional information requested with `addressdetails=1`, `extratags=1` and London Greater London England + GB-ENG SW1A 2DU United Kingdom gb @@ -203,12 +206,13 @@ 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 - * `osm_type`, `osm_id` - reference to the OSM object + * `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 ([see notes](#osm-reference)) * `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 - * `place_rank` - class search rank + * `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox)) + * `place_rank` - class [search rank](../customize/Ranking.md#search-rank) + * `address_rank` - place [address rank](../customize/Ranking.md#address-rank) * `display_name` - full comma-separated address * `class`, `type` - key and value of the main OSM tag * `importance` - computed importance rank @@ -218,5 +222,81 @@ When `addressdetails=1` is requested, the localised address parts appear 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. - +be found in extra elements as sub-element of `extratags` and `namedetails` +respectively. + + +## Notes on field values + +### place_id is not a persistent id + +The `place_id` is an internal identifier that is assigned data is imported +into a Nominatim database. The same OSM object will have a different value +on another server. It may even change its ID on the same server when it is +removed and reimported while updating the database with fresh OSM data. +It is thus not useful to treat it as permanent for later use. + +The combination `osm_type`+`osm_id` is slightly 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). + +If you need an ID that is consistent over multiple installations of Nominatim, +then you should use the combination of `osm_type`+`osm_id`+`class`. + +### OSM reference + +Nominatim may sometimes return special objects that do not correspond directly +to an object in OpenStreetMap. These are: + +* **Postcodes**. Nominatim returns an postcode point created from all mapped + postcodes of the same name. The class and type of these object is `place=postcdode`. + No `osm_type` and `osm_id` are included in the result. +* **Housenumber interpolations**. Nominatim returns a single interpolated + housenumber from the interpolation way. The class and type are `place=house` + and `osm_type` and `osm_id` correspond to the interpolation way in OSM. +* **TIGER housenumber.** Nominatim returns a single interpolated housenumber + from the TIGER data. The class and type are `place=house` + and `osm_type` and `osm_id` correspond to the street mentioned in the result. + +Please note that the `osm_type` and `osm_id` returned may be changed in the +future. You should not expect to only find `node`, `way` and `relation` for +the type. + +### boundingbox + +Comma separated list of min latitude, max latitude, min longitude, max longitude. +The whole planet would be `-90,90,-180,180`. + +Can be 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 entire 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, ISO3166-2-lvl + * municipality, city, town, village + * city_district, district, borough, suburb, subdivision + * hamlet, croft, isolated_dwelling + * neighbourhood, allotments, quarter + * city_block, residential, 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 + * postcode + +They roughly correspond to the classification of the OpenStreetMap data +according to either the `place` tag or the main key of the object.