--- /dev/null
+# 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
+
+```
+<reversegeocode timestamp="Sat, 11 Aug 18 11:53:21 +0000"
+ attribution="Data © OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright"
+ querystring="lat=48.400381&lon=11.745876&zoom=5&format=xml">
+ <result place_id="179509537" osm_type="relation" osm_id="2145268" ref="BY"
+ lat="48.9467562" lon="11.4038717"
+ boundingbox="47.2701114,50.5647142,8.9763497,13.8396373">
+ Bavaria, Germany
+ </result>
+ <addressparts>
+ <state>Bavaria</state>
+ <country>Germany</country>
+ <country_code>de</country_code>
+ </addressparts>
+ <extratags>
+ <tag key="place" value="state"/>
+ <tag key="wikidata" value="Q980"/>
+ <tag key="wikipedia" value="de:Bayern"/>
+ <tag key="population" value="12520000"/>
+ <tag key="name:prefix" value="Freistaat"/>
+ </extratags>
+</reversegeocode>
+```
+
+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
+
+```
+<searchresults timestamp="Sat, 11 Aug 18 11:55:35 +0000"
+ attribution="Data © OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright"
+ querystring="london" polygon="false" exclude_place_ids="100149"
+ more_url="https://nominatim.openstreetmap.org/search.php?q=london&addressdetails=1&extratags=1&exclude_place_ids=100149&format=xml&accept-language=en-US%2Cen%3Bq%3D0.7%2Cde%3Bq%3D0.3">
+ <place place_id="100149" osm_type="node" osm_id="107775" place_rank="15"
+ 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">
+ <extratags>
+ <tag key="capital" value="yes"/>
+ <tag key="website" value="http://www.london.gov.uk"/>
+ <tag key="wikidata" value="Q84"/>
+ <tag key="wikipedia" value="en:London"/>
+ <tag key="population" value="8416535"/>
+ </extratags>
+ <city>London</city>
+ <state_district>Greater London</state_district>
+ <state>England</state>
+ <postcode>SW1A 2DU</postcode>
+ <country>United Kingdom</country>
+ <country_code>gb</country_code>
+ </place>
+</searchresults>
+```
+
+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.
+
projects / nominatim.git / commitdiff