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