bdd: convert API tests to smaller test db

[nominatim.git] / docs / api / Output.md

diff --git a/docs/api/Output.md b/docs/api/Output.md
index 5a33942034d4d49c41145cf02e9f8dbd0f62f571..a37cbe0b820f565198a6cc8d7ede0fe81118aca0 100644 (file)
--- a/docs/api/Output.md
+++ b/docs/api/Output.md
@@ -1,13 +1,11 @@
 # Place Output
 
 # Place Output
 

-The [\reverse](Reverse.md), [\search](Search.md) and [\lookup](Lookup.md)
+The [/reverse](Reverse.md), [/search](Search.md) and [/lookup](Lookup.md)

 API calls produce very similar output which is explained in this section.
 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.
+There is one section for each format. The format correspond to what was
+selected via the `format` parameter.

 
 

-## Formats
-
-### JSON
+## JSON

 
 The JSON format returns an array of places (for search and lookup) or
 a single place (for reverse) of the following format:
 
 The JSON format returns an array of places (for search and lookup) or
 a single place (for reverse) of the following format:


@@ -41,88 +39,87 @@ a single place (for reverse) of the following format:
       "wikipedia": "en:London",
       "population": "8416535"
     }
       "wikipedia": "en:London",
       "population": "8416535"
     }

-  },
+  }

 ```
 
 The possible fields are:
 
 ```
 
 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
+ * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
+ * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
+ * `boundingbox` - area of corner coordinates ([see notes](#boundingbox))

  * `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)
  * `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`)
+ * `address` - dictionary of address details (only with `addressdetails=1`,
+   [see notes](#addressdetails))

  * `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)
 
  * `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
+## 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
 
 
 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
+## GeoJSON

 
 

-This format follows the [RFC7946](http://geojson.org). Every feature includes
+This format follows the [RFC7946](https://geojson.org). Every feature includes

 a bounding box (`bbox`).
 
 a bounding box (`bbox`).
 

-The feature list has the following fields:
+The properties object has the following fields:

 
 

- * `place_id` - reference to the Nominatim internal database ID
- * `osm_type`, `osm_id` - reference to the OSM object
+ * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
+ * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))

  * `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)
  * `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
+ * `address` - dictionary of address details (only with `addressdetails=1`,
+   [see notes](#addressdetails))
+ * `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.
 
    (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
+## GeocodeJSON

 
 The GeocodeJSON format follows the
 [GeocodeJSON spec 0.1.0](https://github.com/geocoders/geocodejson-spec).
 The following feature attributes are implemented:
 
 
 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)
+ * `osm_type`, `osm_id` - reference to the OSM object (unofficial extension, [see notes](#osm-reference))

  * `type` - value of the main tag of the object (e.g. residential, restaurant, ...)
  * `label` - full comma-separated address
  * `name` - localised name of the place
  * `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` -
+ * `housenumber`, `street`, `locality`, `district`, `postcode`, `city`,
+   `county`, `state`, `country` -

    provided when it can be determined from the address
    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.
 
  * `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
+## XML

 
 The XML response returns one or more place objects in slightly different
 formats depending on the API call.
 
 
 The XML response returns one or more place objects in slightly different
 formats depending on the API call.
 

-#### Reverse
+### Reverse

 
 ```
 <reversegeocode timestamp="Sat, 11 Aug 18 11:53:21 +0000"
 
 ```
 <reversegeocode timestamp="Sat, 11 Aug 18 11:53:21 +0000"

-                attribution="Data © OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright"
+                attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"

                 querystring="lat=48.400381&lon=11.745876&zoom=5&format=xml">
                 querystring="lat=48.400381&lon=11.745876&zoom=5&format=xml">

-  <result place_id="179509537" osm_type="relation" osm_id="2145268" ref="BY"
+  <result place_id="179509537" osm_type="relation" osm_id="2145268" ref="BY" place_rank="15" address_rank="15"

           lat="48.9467562" lon="11.4038717"
           boundingbox="47.2701114,50.5647142,8.9763497,13.8396373">
        Bavaria, Germany
           lat="48.9467562" lon="11.4038717"
           boundingbox="47.2701114,50.5647142,8.9763497,13.8396373">
        Bavaria, Germany


@@ -148,28 +145,28 @@ attribution to OSM and the original querystring.
 
 The place information can be found in the `result` element. The attributes of that element contain:
 
 
 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
+ * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
+ * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))

  * `ref` - content of `ref` tag if it exists
  * `lat`, `lon` - latitude and longitude of the centroid of the 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
+ * `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox))

 
 

-The full address address of the result can be found in the content of the
+The full 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.
 
 `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
+### Search and Lookup

 
 ```
 <searchresults timestamp="Sat, 11 Aug 18 11:55:35 +0000"
 
 ```
 <searchresults timestamp="Sat, 11 Aug 18 11:55:35 +0000"

-               attribution="Data © OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright"
+               attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://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">
                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"
+  <place place_id="100149" osm_type="node" osm_id="107775" place_rank="15" address_rank="15"

          boundingbox="51.3473219,51.6673219,-0.2876474,0.0323526" lat="51.5073219" lon="-0.1276474"
          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" 
+         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>
          class="place" type="city" importance="0.9654895765402"
          icon="https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png">
     <extratags>


@@ -203,12 +200,13 @@ generic information about the query:
 The place information can be found in the `place` elements, of which there may
 be more than one. The attributes of that element contain:
 
 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
+ * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
+ * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))

  * `ref` - content of `ref` tag if it exists
  * `lat`, `lon` - latitude and longitude of the centroid of the 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
+ * `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox))
+ * `place_rank` - class [search rank](../develop/Ranking#search-rank)
+ * `address_rank` - place [address rank](../develop/Ranking#address-rank)

  * `display_name` - full comma-separated address
  * `class`, `type` - key and value of the main OSM tag
  * `importance` - computed importance rank
  * `display_name` - full comma-separated address
  * `class`, `type` - key and value of the main OSM tag
  * `importance` - computed importance rank


@@ -218,5 +216,80 @@ 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
 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.
-
+be found in extra elements as sub-element of `extratags` and `namedetails`
+respectively.
+
+
+## Notes on field values
+
+### place_id is not a persistent id
+
+The `place_id` is an internal identifier that is assigned data is imported
+into a Nominatim database. The same OSM object will have a different value
+on another server. It may even change its ID on the same server when it is
+removed and reimported while updating the database with fresh OSM data.
+It is thus not useful to treat it as permanent for later use.
+
+The combination `osm_type`+`osm_id` is slighly better but remember in
+OpenStreetMap mappers can delete, split, recreate places (and those
+get a new `osm_id`), there is no link between those old and new ids.
+Places can also change their meaning without changing their `osm_id`,
+e.g. when a restaurant is retagged as supermarket. For a more in-depth
+discussion see [Permanent ID](https://wiki.openstreetmap.org/wiki/Permanent_ID).
+
+If you need an ID that is consistent over multiple installations of Nominatim,
+then you should use the combination of `osm_type`+`osm_id`+`class`.
+
+### OSM reference
+
+Nominatim may sometimes return special objects that do not correspond directly
+to an object in OpenStreetMap. These are:
+
+* **Postcodes**. Nominatim returns an postcode point created from all mapped
+  postcodes of the same name. The class and type of these object is `place=postcdode`.
+  No `osm_type` and `osm_id` are included in the result.
+* **Housenumber interpolations**. Nominatim returns a single interpolated
+  housenumber from the interpolation way. The class and type are `place=house`
+  and `osm_type` and `osm_id` correspond to the interpolation way in OSM.
+* **TIGER housenumber.** Nominatim returns a single interpolated housenumber
+  from the TIGER data. The class and type are `place=house`
+  and `osm_type` and `osm_id` correspond to the street mentioned in the result.
+
+Please note that the `osm_type` and `osm_id` returned may be changed in the
+future. You should not expect to only find `node`, `way` and `relation` for
+the type.
+
+### boundingbox
+
+Comma separated list of min latitude, max latitude, min longitude, max longitude.
+The whole planet would be `-90,90,-180,180`.
+
+Can be used to pan and center the map on the result, for example with leafletjs
+mapping library
+`map.fitBounds([[bbox[0],bbox[2]],[bbox[1],bbox[3]]], {padding: [20, 20], maxzoom: 16});`
+
+Bounds crossing the antimeridian have a min latitude -180 and max latitude 180,
+essentially covering the entire planet
+(see [issue 184](https://github.com/openstreetmap/Nominatim/issues/184)).
+
+### addressdetails
+
+Address details in the xml and json formats return a list of names together
+with a designation label. Per default the following labels may appear:
+
+ * continent
+ * country, country_code
+ * region, state, state_district, county
+ * municipality, city, town, village
+ * city_district, district, borough, suburb, subdivision
+ * hamlet, croft, isolated_dwelling
+ * neighbourhood, allotments, quarter
+ * city_block, residental, farm, farmyard, industrial, commercial, retail
+ * road
+ * house_number, house_name
+ * emergency, historic, military, natural, landuse, place, railway,
+   man_made, aerialway, boundary, amenity, aeroway, club, craft, leisure,
+   office, mountain_pass, shop, tourism, bridge, tunnel, waterway
+
+They roughly correspond to the classification of the OpenStreetMap data
+according to either the `place` tag or the main key of the object.