X-Git-Url: https://git.openstreetmap.org./nominatim.git/blobdiff_plain/a09f2a698707c366a0e93a81c84268a83bf7d7ea..40cb17d2995baaba6bec299d4e6dc65b25dbdc28:/docs/api/Output.md diff --git a/docs/api/Output.md b/docs/api/Output.md index df78ed7d..a37cbe0b 100644 --- a/docs/api/Output.md +++ b/docs/api/Output.md @@ -2,12 +2,10 @@ 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: @@ -41,48 +39,50 @@ 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 (see notes below) - * `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](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 (see notes below) - * `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`) + * `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. @@ -90,39 +90,36 @@ The feature list has the following fields: 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) + * `osm_type`, `osm_id` - reference to the OSM object (unofficial extension, [see notes](#osm-reference)) * `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 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 @@ -148,11 +145,11 @@ 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 (see notes below) - * `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 of the result can be found in the content of the `result` element as a comma-separated list. @@ -160,14 +157,14 @@ The full address of the result can be found in the content of the Additional information requested with `addressdetails=1`, `extratags=1` and `namedetails=1` can be found in extra elements. -#### Search and Lookup +### Search and Lookup ``` -