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