From 41c4b51be5ff6f1d94e0899665b814a805691d8c Mon Sep 17 00:00:00 2001 From: Sarah Hoffmann Date: Sat, 11 Aug 2018 14:17:41 +0200 Subject: [PATCH] add description of output of API --- docs/api/Lookup.md | 2 +- docs/api/Output.md | 222 ++++++++++++++++++++++++++++++++++++++++++++ docs/api/Reverse.md | 2 +- docs/api/Search.md | 2 +- docs/mkdocs.yml | 1 + 5 files changed, 226 insertions(+), 3 deletions(-) create mode 100644 docs/api/Output.md diff --git a/docs/api/Lookup.md b/docs/api/Lookup.md index 0f13df45..57bf7b5f 100644 --- a/docs/api/Lookup.md +++ b/docs/api/Lookup.md @@ -21,7 +21,7 @@ Additional optional parameters are explained below. * `format=[html|xml|json|jsonv2|geojson|geocodejson]` -See below for details on each format. (Default: xml) +See [Place Output Formats](Output.md) for details on each format. (Default: xml) * `json_callback=` diff --git a/docs/api/Output.md b/docs/api/Output.md new file mode 100644 index 00000000..5a339420 --- /dev/null +++ b/docs/api/Output.md @@ -0,0 +1,222 @@ +# Place Output + +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. + +## Formats + +### 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", + "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright", + "osm_type": "node", + "osm_id": "107775", + "boundingbox": ["51.3473219", "51.6673219", "-0.2876474", "0.0323526"], + "lat": "51.5073219", + "lon": "-0.1276474", + "display_name": "London, Greater London, England, SW1A 2DU, United Kingdom", + "class": "place", + "type": "city", + "importance": 0.9654895765402, + "icon": "https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png", + "address": { + "city": "London", + "state_district": "Greater London", + "state": "England", + "postcode": "SW1A 2DU", + "country": "United Kingdom", + "country_code": "gb" + }, + "extratags": { + "capital": "yes", + "website": "http://www.london.gov.uk", + "wikidata": "Q84", + "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 + * `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`) + * `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 + +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 + +This format follows the [RFC7946](http://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 + * `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 + (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 + +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, ...) + * `label` - full comma-separated address + * `name` - localised name of the place + * `housenumber`, `street`, `locality`, `postcode`, `city`, + `district`, `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 + +The XML response returns one or more place objects in slightly different +formats depending on the API call. + +#### Reverse + +``` + + + Bavaria, Germany + + + Bavaria + Germany + de + + + + + + + + + +``` + +The attributes of the outer `reversegeocode` element return generic information +about the query, including the time when the response was sent (in UTC), +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 + * `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 + +The full address 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 + +``` + + + + + + + + + + London + Greater London + England + SW1A 2DU + United Kingdom + gb + + +``` + +The attributes of the outer `searchresults` or `lookupresults` element return +generic information about the query: + + * `timestamp` - UTC time when the response was sent + * `attribution` - OSM licensing information + * `querystring` - original query + * `polygon` - true when extra geometry information was requested + * `exclude_place_ids` - IDs of places that should be ignored in a follow-up request + * `more_url` - search call that will yield additional results for the query + just sent + +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 + * `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 + * `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) + +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. + diff --git a/docs/api/Reverse.md b/docs/api/Reverse.md index b3c75efc..ae368e1c 100644 --- a/docs/api/Reverse.md +++ b/docs/api/Reverse.md @@ -30,7 +30,7 @@ below. * `format=[xml|json|jsonv2|geojson|geocodejson]` -See below for details on each format. (Default: html) +See [Place Output Formats](Output.md) for details on each format. (Default: html) * `json_callback=` diff --git a/docs/api/Search.md b/docs/api/Search.md index 1cb6cef0..ab702379 100644 --- a/docs/api/Search.md +++ b/docs/api/Search.md @@ -55,7 +55,7 @@ All three query forms accept the additional paramters listed below. * `format=[html|xml|json|jsonv2|geojson|geocodejson]` -See below for details on each format. (Default: html) +See [Place Output Formats](Output.md) for details on each format. (Default: html) * `json_callback=` diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index b11d5d98..4018433f 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -10,6 +10,7 @@ pages: - 'Search': 'api/Search.md' - 'Reverse': 'api/Reverse.md' - 'Address Lookup': 'api/Lookup.md' + - 'Place Output Formats': 'api/Output.md' - 'Administration Guide': - 'Basic Installation': 'admin/Installation.md' - 'Importing and Updating' : 'admin/Import-and-Update.md' -- 2.39.5