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` - value of the main tag of the object (e.g. residential, restaurant, ...)
 102  * `label` - full comma-separated address
 103  * `name` - localised name of the place
 104  * `housenumber`, `street`, `locality`, `district`, `postcode`, `city`,
 105    `county`, `state`, `country` -
 106    provided when it can be determined from the address
 107  * `admin` - list of localised names of administrative boundaries (only with `addressdetails=1`)
 108
 109 Use `polygon_geojson` to output the full geometry of the object instead
 110 of the centroid.
 111
 112 ## XML
 113
 114 The XML response returns one or more place objects in slightly different
 115 formats depending on the API call.
 116
 117 ### Reverse
 118
 119 ```
 120 <reversegeocode timestamp="Sat, 11 Aug 18 11:53:21 +0000"
 121                 attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
 122                 querystring="lat=48.400381&lon=11.745876&zoom=5&format=xml">
 123   <result place_id="179509537" osm_type="relation" osm_id="2145268" ref="BY" place_rank="15" address_rank="15"
 124           lat="48.9467562" lon="11.4038717"
 125           boundingbox="47.2701114,50.5647142,8.9763497,13.8396373">
 126        Bavaria, Germany
 127   </result>
 128   <addressparts>
 129      <state>Bavaria</state>
 130      <ISO3166-2-lvl4>DE-BY</ISO3166-2-lvl4>
 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 ([see notes](#osm-reference))
 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" address_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     <ISO3166-2-lvl4>GB-ENG</ISO3166-2-lvl4>
 185     <postcode>SW1A 2DU</postcode>
 186     <country>United Kingdom</country>
 187     <country_code>gb</country_code>
 188   </place>
 189 </searchresults>
 190 ```
 191
 192 The attributes of the outer `searchresults` or `lookupresults` element return
 193 generic information about the query:
 194
 195  * `timestamp` - UTC time when the response was sent
 196  * `attribution` - OSM licensing information
 197  * `querystring` - original query
 198  * `polygon` - true when extra geometry information was requested
 199  * `exclude_place_ids` - IDs of places that should be ignored in a follow-up request
 200  * `more_url` - search call that will yield additional results for the query
 201    just sent
 202
 203 The place information can be found in the `place` elements, of which there may
 204 be more than one. The attributes of that element contain:
 205
 206  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
 207  * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
 208  * `ref` - content of `ref` tag if it exists
 209  * `lat`, `lon` - latitude and longitude of the centroid of the object
 210  * `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox))
 211  * `place_rank` - class [search rank](../develop/Ranking#search-rank)
 212  * `address_rank` - place [address rank](../develop/Ranking#address-rank)
 213  * `display_name` - full comma-separated address
 214  * `class`, `type` - key and value of the main OSM tag
 215  * `importance` - computed importance rank
 216  * `icon` - link to class icon (if available)
 217
 218 When `addressdetails=1` is requested, the localised address parts appear
 219 as subelements with the type of the address part.
 220
 221 Additional information requested with `extratags=1` and `namedetails=1` can
 222 be found in extra elements as sub-element of `extratags` and `namedetails`
 223 respectively.
 224
 225
 226 ## Notes on field values
 227
 228 ### place_id is not a persistent id
 229
 230 The `place_id` is an internal identifier that is assigned data is imported
 231 into a Nominatim database. The same OSM object will have a different value
 232 on another server. It may even change its ID on the same server when it is
 233 removed and reimported while updating the database with fresh OSM data.
 234 It is thus not useful to treat it as permanent for later use.
 235
 236 The combination `osm_type`+`osm_id` is slighly better but remember in
 237 OpenStreetMap mappers can delete, split, recreate places (and those
 238 get a new `osm_id`), there is no link between those old and new ids.
 239 Places can also change their meaning without changing their `osm_id`,
 240 e.g. when a restaurant is retagged as supermarket. For a more in-depth
 241 discussion see [Permanent ID](https://wiki.openstreetmap.org/wiki/Permanent_ID).
 242
 243 If you need an ID that is consistent over multiple installations of Nominatim,
 244 then you should use the combination of `osm_type`+`osm_id`+`class`.
 245
 246 ### OSM reference
 247
 248 Nominatim may sometimes return special objects that do not correspond directly
 249 to an object in OpenStreetMap. These are:
 250
 251 * **Postcodes**. Nominatim returns an postcode point created from all mapped
 252   postcodes of the same name. The class and type of these object is `place=postcdode`.
 253   No `osm_type` and `osm_id` are included in the result.
 254 * **Housenumber interpolations**. Nominatim returns a single interpolated
 255   housenumber from the interpolation way. The class and type are `place=house`
 256   and `osm_type` and `osm_id` correspond to the interpolation way in OSM.
 257 * **TIGER housenumber.** Nominatim returns a single interpolated housenumber
 258   from the TIGER data. The class and type are `place=house`
 259   and `osm_type` and `osm_id` correspond to the street mentioned in the result.
 260
 261 Please note that the `osm_type` and `osm_id` returned may be changed in the
 262 future. You should not expect to only find `node`, `way` and `relation` for
 263 the type.
 264
 265 ### boundingbox
 266
 267 Comma separated list of min latitude, max latitude, min longitude, max longitude.
 268 The whole planet would be `-90,90,-180,180`.
 269
 270 Can be used to pan and center the map on the result, for example with leafletjs
 271 mapping library
 272 `map.fitBounds([[bbox[0],bbox[2]],[bbox[1],bbox[3]]], {padding: [20, 20], maxzoom: 16});`
 273
 274 Bounds crossing the antimeridian have a min latitude -180 and max latitude 180,
 275 essentially covering the entire planet
 276 (see [issue 184](https://github.com/openstreetmap/Nominatim/issues/184)).
 277
 278 ### addressdetails
 279
 280 Address details in the xml and json formats return a list of names together
 281 with a designation label. Per default the following labels may appear:
 282
 283  * continent
 284  * country, country_code
 285  * region, state, state_district, county, ISO3166-2-lvl<admin_level>
 286  * municipality, city, town, village
 287  * city_district, district, borough, suburb, subdivision
 288  * hamlet, croft, isolated_dwelling
 289  * neighbourhood, allotments, quarter
 290  * city_block, residental, farm, farmyard, industrial, commercial, retail
 291  * road
 292  * house_number, house_name
 293  * emergency, historic, military, natural, landuse, place, railway,
 294    man_made, aerialway, boundary, amenity, aeroway, club, craft, leisure,
 295    office, mountain_pass, shop, tourism, bridge, tunnel, waterway
 296  * postcode
 297
 298 They roughly correspond to the classification of the OpenStreetMap data
 299 according to either the `place` tag or the main key of the object.