docs/api/Output.md

   1 # Place Output
   2
   3 The [/reverse](Reverse.md), [/search](Search.md) and [/lookup](Lookup.md)
   4 API calls produce very similar output which is explained in this section.
   5 There is one section for each format which is selectable via the `format`
   6 parameter.
   7
   8 ## Formats
   9
  10 ### JSON
  11
  12 The JSON format returns an array of places (for search and lookup) or
  13 a single place (for reverse) of the following format:
  14
  15 ```
  16   {
  17     "place_id": "100149",
  18     "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
  19     "osm_type": "node",
  20     "osm_id": "107775",
  21     "boundingbox": ["51.3473219", "51.6673219", "-0.2876474", "0.0323526"],
  22     "lat": "51.5073219",
  23     "lon": "-0.1276474",
  24     "display_name": "London, Greater London, England, SW1A 2DU, United Kingdom",
  25     "class": "place",
  26     "type": "city",
  27     "importance": 0.9654895765402,
  28     "icon": "https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png",
  29     "address": {
  30       "city": "London",
  31       "state_district": "Greater London",
  32       "state": "England",
  33       "postcode": "SW1A 2DU",
  34       "country": "United Kingdom",
  35       "country_code": "gb"
  36     },
  37     "extratags": {
  38       "capital": "yes",
  39       "website": "http://www.london.gov.uk",
  40       "wikidata": "Q84",
  41       "wikipedia": "en:London",
  42       "population": "8416535"
  43     }
  44   },
  45 ```
  46
  47 The possible fields are:
  48
  49  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
  50  * `osm_type`, `osm_id` - reference to the OSM object
  51  * `boundingbox` - area of corner coordinates ([see notes](#boundingbox))
  52  * `lat`, `lon` - latitude and longitude of the centroid of the object
  53  * `display_name` - full comma-separated address
  54  * `class`, `type` - key and value of the main OSM tag
  55  * `importance` - computed importance rank
  56  * `icon` - link to class icon (if available)
  57  * `address` - dictionary of address details (only with `addressdetails=1`,
  58    [see notes](#addressdetails))
  59  * `extratags` - dictionary with additional useful tags like website or maxspeed
  60    (only with `extratags=1`)
  61  * `namedetails` - dictionary with full list of available names including ref etc.
  62  * `geojson`, `svg`, `geotext`, `geokml` - full geometry
  63    (only with the appropriate `polygon_*` parameter)
  64
  65 ### JSONv2
  66
  67 This is the same as the JSON format with two changes:
  68
  69  * `class` renamed to `category`
  70  * additional field `place_rank` with the search rank of the object
  71
  72 ### GeoJSON
  73
  74 This format follows the [RFC7946](https://geojson.org). Every feature includes
  75 a bounding box (`bbox`).
  76
  77 The feature list has the following fields:
  78
  79  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
  80  * `osm_type`, `osm_id` - reference to the OSM object
  81  * `category`, `type` - key and value of the main OSM tag
  82  * `display_name` - full comma-separated address
  83  * `place_rank` - class search rank
  84  * `importance` - computed importance rank
  85  * `icon` - link to class icon (if available)
  86  * `address` - dictionary of address details (only with `addressdetails=1`,
  87    [see notes](#addressdetails))
  88  * `extratags` - dictionary with additional useful tags like `website` or `maxspeed`
  89    (only with `extratags=1`)
  90  * `namedetails` - dictionary with full list of available names including ref etc.
  91
  92 Use `polygon_geojson` to output the full geometry of the object instead
  93 of the centroid.
  94
  95 ### GeocodeJSON
  96
  97 The GeocodeJSON format follows the
  98 [GeocodeJSON spec 0.1.0](https://github.com/geocoders/geocodejson-spec).
  99 The following feature attributes are implemented:
 100
 101  * `osm_type`, `osm_id` - reference to the OSM object (unofficial extension)
 102  * `type` - value of the main tag of the object (e.g. residential, restaurant, ...)
 103  * `label` - full comma-separated address
 104  * `name` - localised name of the place
 105  * `housenumber`, `street`, `locality`, `district`, `postcode`, `city`,
 106    `county`, `state`, `country` -
 107    provided when it can be determined from the address
 108  * `admin` - list of localised names of administrative boundaries (only with `addressdetails=1`)
 109
 110 Use `polygon_geojson` to output the full geometry of the object instead
 111 of the centroid.
 112
 113 ### XML
 114
 115 The XML response returns one or more place objects in slightly different
 116 formats depending on the API call.
 117
 118 #### Reverse
 119
 120 ```
 121 <reversegeocode timestamp="Sat, 11 Aug 18 11:53:21 +0000"
 122                 attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
 123                 querystring="lat=48.400381&lon=11.745876&zoom=5&format=xml">
 124   <result place_id="179509537" osm_type="relation" osm_id="2145268" ref="BY"
 125           lat="48.9467562" lon="11.4038717"
 126           boundingbox="47.2701114,50.5647142,8.9763497,13.8396373">
 127        Bavaria, Germany
 128   </result>
 129   <addressparts>
 130      <state>Bavaria</state>
 131      <country>Germany</country>
 132      <country_code>de</country_code>
 133   </addressparts>
 134   <extratags>
 135     <tag key="place" value="state"/>
 136     <tag key="wikidata" value="Q980"/>
 137     <tag key="wikipedia" value="de:Bayern"/>
 138     <tag key="population" value="12520000"/>
 139     <tag key="name:prefix" value="Freistaat"/>
 140   </extratags>
 141 </reversegeocode>
 142 ```
 143
 144 The attributes of the outer `reversegeocode` element return generic information
 145 about the query, including the time when the response was sent (in UTC),
 146 attribution to OSM and the original querystring.
 147
 148 The place information can be found in the `result` element. The attributes of that element contain:
 149
 150  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
 151  * `osm_type`, `osm_id` - reference to the OSM object
 152  * `ref` - content of `ref` tag if it exists
 153  * `lat`, `lon` - latitude and longitude of the centroid of the object
 154  * `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox))
 155
 156 The full address of the result can be found in the content of the
 157 `result` element as a comma-separated list.
 158
 159 Additional information requested with `addressdetails=1`, `extratags=1` and
 160 `namedetails=1` can be found in extra elements.
 161
 162 #### Search and Lookup
 163
 164 ```
 165 <searchresults timestamp="Sat, 11 Aug 18 11:55:35 +0000"
 166                attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
 167                querystring="london" polygon="false" exclude_place_ids="100149"
 168                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">
 169   <place place_id="100149" osm_type="node" osm_id="107775" place_rank="15"
 170          boundingbox="51.3473219,51.6673219,-0.2876474,0.0323526" lat="51.5073219" lon="-0.1276474"
 171          display_name="London, Greater London, England, SW1A 2DU, United Kingdom"
 172          class="place" type="city" importance="0.9654895765402"
 173          icon="https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png">
 174     <extratags>
 175       <tag key="capital" value="yes"/>
 176       <tag key="website" value="http://www.london.gov.uk"/>
 177       <tag key="wikidata" value="Q84"/>
 178       <tag key="wikipedia" value="en:London"/>
 179       <tag key="population" value="8416535"/>
 180     </extratags>
 181     <city>London</city>
 182     <state_district>Greater London</state_district>
 183     <state>England</state>
 184     <postcode>SW1A 2DU</postcode>
 185     <country>United Kingdom</country>
 186     <country_code>gb</country_code>
 187   </place>
 188 </searchresults>
 189 ```
 190
 191 The attributes of the outer `searchresults` or `lookupresults` element return
 192 generic information about the query:
 193
 194  * `timestamp` - UTC time when the response was sent
 195  * `attribution` - OSM licensing information
 196  * `querystring` - original query
 197  * `polygon` - true when extra geometry information was requested
 198  * `exclude_place_ids` - IDs of places that should be ignored in a follow-up request
 199  * `more_url` - search call that will yield additional results for the query
 200    just sent
 201
 202 The place information can be found in the `place` elements, of which there may
 203 be more than one. The attributes of that element contain:
 204
 205  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
 206  * `osm_type`, `osm_id` - reference to the OSM object
 207  * `ref` - content of `ref` tag if it exists
 208  * `lat`, `lon` - latitude and longitude of the centroid of the object
 209  * `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox))
 210  * `place_rank` - class search rank
 211  * `display_name` - full comma-separated address
 212  * `class`, `type` - key and value of the main OSM tag
 213  * `importance` - computed importance rank
 214  * `icon` - link to class icon (if available)
 215
 216 When `addressdetails=1` is requested, the localised address parts appear
 217 as subelements with the type of the address part.
 218
 219 Additional information requested with `extratags=1` and `namedetails=1` can
 220 be found in extra elements as sub-element of each place.
 221
 222
 223 ## Notes on field values
 224
 225 ### place_id is not a persistent id
 226
 227 The `place_id` is created when a Nominatim database gets installed. A
 228 single place will have a different value on another server or even when
 229 the same data gets re-imported. It's thus not useful to treat it as
 230 permanent for later use.
 231
 232 The combination `osm_type`+`osm_id` is slighly better but remember in
 233 OpenStreetMap mappers can delete, split, recreate places (and those
 234 get a new `osm_id`), there is no link between those old and new ids.
 235 Places can also change their meaning without changing their `osm_id`,
 236 e.g. when a restaurant is retagged as supermarket. For a more in-depth
 237 discussion see [Permanent ID](https://wiki.openstreetmap.org/wiki/Permanent_ID).
 238
 239 Nominatim merges some places (e.g. center node of a city with the boundary
 240 relation) so `osm_type`+`osm_id`+`class_name` would be more unique.
 241
 242 ### boundingbox
 243
 244 Comma separated list of min latitude, max latitude, min longitude, max longitude.
 245 The whole planet would be `-90,90,-180,180`.
 246
 247 Can we used to pan and center the map on the result, for example with leafletjs
 248 mapping library
 249 `map.fitBounds([[bbox[0],bbox[2]],[bbox[1],bbox[3]]], {padding: [20, 20], maxzoom: 16});`
 250
 251 Bounds crossing the antimeridian have a min latitude -180 and max latitude 180,
 252 essentially covering the planet (See [issue 184](https://github.com/openstreetmap/Nominatim/issues/184)).
 253
 254 ### addressdetails
 255
 256 Address details in the xml and json formats return a list of names together
 257 with a designation label. Per default the following labels may appear:
 258
 259  * continent
 260  * country, country_code
 261  * region, state, state_district, county
 262  * municipality, city, town, village
 263  * city_district, district, borough, suburb, subdivision
 264  * hamlet, croft, isolated_dwelling
 265  * neighbourhood, allotments, quarter
 266  * city_block, residental, farm, farmyard, industrial, commercial, retail
 267  * road
 268  * house_number, house_name
 269  * emergency, historic, military, natural, landuse, place, railway,
 270    man_made, aerialway, boundary, amenity, aeroway, club, craft, leisure,
 271    office, mountain_pass, shop, tourism, bridge, tunnel, waterway
 272
 273 They roughly correspond to the classification of the OpenStreetMap data
 274 according to either the `place` tag or the main key of the object.