osm-search/Nominatim
1
1
Fork 0
mirror of https://github.com/osm-search/Nominatim.git synced 2024-12-24 13:31:37 +03:00
Code Issues Packages Projects Releases Wiki Activity

update API documentation

Browse Source 
* remove traces of HTML output
* add details on artificial objects (see also #1671)
* add geometry output documentation for lookup
* deprecate query by ID via reverse endpoint
* remove /search/<query> query format, no longer supported
* explain better what reverse geocoding does
* lots of smaller fixes to wording
This commit is contained in:
Sarah Hoffmann 2020-12-05 16:21:42 +01:00
parent ea844db847
commit eaee87e73d
5 changed files with 146 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
docs/api/Details.md
View File

@ -1,19 +1,22 @@
# Place details # Place details
Lookup details about a single place by id. The default output is HTML for debugging search logic and results. Show all details about a single place saved in the database.
**The details page (including JSON output) exists for debugging only and must not be downloaded automatically**, see [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/). !!! warning
The details page exists for debugging only. You may not use it in scripts
or to automatically query details about a result.
See [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/).
## Parameters ## Parameters
The details API supports the following two request formats: The details API supports the following two request formats:
``` ``` xml
https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=<value>&class=<value> https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=<value>&class=<value>
``` ```
`osmtype` and `osmid` are required parameter. The type is one of node (N), way (W) `osmtype` and `osmid` are required parameters. The type is one of node (N), way (W)
or relation (R). The id must be a number. The `class` parameter is optional and or relation (R). The id must be a number. The `class` parameter is optional and
allows to distinguish between entries, when the corresponding OSM object has more allows to distinguish between entries, when the corresponding OSM object has more
than one main tag. For example, when a place is tagged with `tourism=hotel` and than one main tag. For example, when a place is tagged with `tourism=hotel` and
@ -23,36 +26,34 @@ to get exactly the one you want. If there are multiple places in the database
but the `class` parameter is left out, then one of the places will be chosen but the `class` parameter is left out, then one of the places will be chosen
at random and displayed. at random and displayed.
``` ``` xml
https://nominatim.openstreetmap.org/details?place_id=<value> https://nominatim.openstreetmap.org/details?place_id=<value>
``` ```
Placeids are assigned sequentially during Nominatim data import. The id for a place is different between Nominatim installation (servers) and changes when data gets reimported. Therefore it can't be used as permanent id and shouldn't be used in bug reports. Place IDs are assigned sequentially during Nominatim data import. The ID
for a place is different between Nominatim installation (servers) and
changes when data gets reimported. Therefore it cannot be used as
a permanent id and shouldn't be used in bug reports.
Additional optional parameters are explained below. Additional optional parameters are explained below.
### Output format ### Output format
* `format=[html|json]`
See [Place Output Formats](Output.md) for details on each format. (Default: html)
* `json_callback=<string>` * `json_callback=<string>`
Wrap JSON output in a callback function (JSONP) i.e. `<string>(<json>)`. Wrap JSON output in a callback function (JSONP) i.e. `<string>(<json>)`.
Only has an effect for JSON output formats.
* `pretty=[0|1]` * `pretty=[0|1]`
For JSON output will add indentation to make it more human-readable. (Default: 0) Add indentation to make it more human-readable. (Default: 0)
### Output details ### Output details
* `addressdetails=[0|1]` * `addressdetails=[0|1]`
Include a breakdown of the address into elements. (Default for JSON: 0, for HTML: 1) Include a breakdown of the address into elements. (Default: 0)
* `keywords=[0|1]` * `keywords=[0|1]`
@ -60,11 +61,16 @@ Include a list of name keywords and address keywords (word ids). (Default: 0)
* `linkedplaces=[0|1]` * `linkedplaces=[0|1]`
Include details of places higher in the address hierarchy. E.g. for a street this is usually the city, state, postal code, country. (Default: 1) Include a details of places that are linked with this one. Places get linked
together when they are different forms of the same physical object. Nominatim
links two kinds of objects together: place nodes get linked with the
corresponding administrative boundaries. Waterway relations get linked together with their
members.
(Default: 1)
* `hierarchy=[0|1]` * `hierarchy=[0|1]`
Include details of places lower in the address hierarchy. E.g. for a city this usually a list of streets, suburbs, rivers. (Default for JSON: 0, for HTML: 1) Include details of places lower in the address hierarchy. . (Default: 0)
* `group_hierarchy=[0|1]` * `group_hierarchy=[0|1]`
@ -72,7 +78,7 @@ For JSON output will group the places by type. (Default: 0)
* `polygon_geojson=[0|1]` * `polygon_geojson=[0|1]`
Include geometry of result. (Default for JSON: 0, for HTML: 1) Include geometry of result. (Default: 0)
### Language of results ### Language of results
@ -86,10 +92,6 @@ comma-separated list of language codes.
## Examples ## Examples
##### HTML
[https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407](https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407)
##### JSON ##### JSON
[https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407&format=json](https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407&format=json) [https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407&format=json](https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407&format=json)

15
docs/api/Lookup.md
View File

@ -56,6 +56,21 @@ specified in the "Accept-Language" HTTP header.
Either use a standard RFC2616 accept-language string or a simple Either use a standard RFC2616 accept-language string or a simple
comma-separated list of language codes. comma-separated list of language codes.
### Polygon output
* `polygon_geojson=1`
* `polygon_kml=1`
* `polygon_svg=1`
* `polygon_text=1`
Output geometry of results as a GeoJSON, KML, SVG or WKT. Only one of these
options can be used at a time. (Default: 0)
* `polygon_threshold=0.0`
Return a simplified version of the output geometry. The parameter is the
tolerance in degrees with which the geometry may differ from the original
geometry. Topology is preserved in the result. (Default: 0.0)
### Other ### Other

81
docs/api/Output.md
View File

@ -2,12 +2,10 @@
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` There is one section for each format. The format correspond to what was
parameter. selected via the `format` parameter.
## Formats ## JSON
### JSON
The JSON format returns an array of places (for search and lookup) or The JSON format returns an array of places (for search and lookup) or
a single place (for reverse) of the following format: a single place (for reverse) of the following format:
@ -41,13 +39,13 @@ a single place (for reverse) of the following format:
"wikipedia": "en:London", "wikipedia": "en:London",
"population": "8416535" "population": "8416535"
} }
}, }
``` ```
The possible fields are: The possible fields are:
* `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id)) * `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 * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
* `boundingbox` - area of corner coordinates ([see notes](#boundingbox)) * `boundingbox` - area of corner coordinates ([see notes](#boundingbox))
* `lat`, `lon` - latitude and longitude of the centroid of the object * `lat`, `lon` - latitude and longitude of the centroid of the object
* `display_name` - full comma-separated address * `display_name` - full comma-separated address
@ -62,22 +60,22 @@ The possible fields are:
* `geojson`, `svg`, `geotext`, `geokml` - full geometry * `geojson`, `svg`, `geotext`, `geokml` - full geometry
(only with the appropriate `polygon_*` parameter) (only with the appropriate `polygon_*` parameter)
### JSONv2 ## JSONv2
This is the same as the JSON format with two changes: This is the same as the JSON format with two changes:
* `class` renamed to `category` * `class` renamed to `category`
* additional field `place_rank` with the search rank of the object * additional field `place_rank` with the search rank of the object
### GeoJSON ## GeoJSON
This format follows the [RFC7946](https://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 ([see notes](#place_id-is-not-a-persistent-id)) * `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 * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
* `category`, `type` - key and value of the main OSM tag * `category`, `type` - key and value of the main OSM tag
* `display_name` - full comma-separated address * `display_name` - full comma-separated address
* `place_rank` - class search rank * `place_rank` - class search rank
@ -92,13 +90,13 @@ The feature list has the following fields:
Use `polygon_geojson` to output the full geometry of the object instead Use `polygon_geojson` to output the full geometry of the object instead
of the centroid. of the centroid.
### GeocodeJSON ## GeocodeJSON
The GeocodeJSON format follows the The GeocodeJSON format follows the
[GeocodeJSON spec 0.1.0](https://github.com/geocoders/geocodejson-spec). [GeocodeJSON spec 0.1.0](https://github.com/geocoders/geocodejson-spec).
The following feature attributes are implemented: 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, ...) * `type` - value of the main tag of the object (e.g. residential, restaurant, ...)
* `label` - full comma-separated address * `label` - full comma-separated address
* `name` - localised name of the place * `name` - localised name of the place
@ -110,18 +108,18 @@ The following feature attributes are implemented:
Use `polygon_geojson` to output the full geometry of the object instead Use `polygon_geojson` to output the full geometry of the object instead
of the centroid. of the centroid.
### XML ## XML
The XML response returns one or more place objects in slightly different The XML response returns one or more place objects in slightly different
formats depending on the API call. 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. https://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" lat="48.9467562" lon="11.4038717"
boundingbox="47.2701114,50.5647142,8.9763497,13.8396373"> boundingbox="47.2701114,50.5647142,8.9763497,13.8396373">
Bavaria, Germany Bavaria, Germany
@ -148,7 +146,7 @@ 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 ([see notes](#place_id-is-not-a-persistent-id)) * `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 * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
* `ref` - content of `ref` tag if it exists * `ref` - content of `ref` tag if it exists
* `lat`, `lon` - latitude and longitude of the centroid of the object * `lat`, `lon` - latitude and longitude of the centroid of the object
* `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox)) * `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox))
@ -159,14 +157,14 @@ The full address of the result can be found in the content of the
Additional information requested with `addressdetails=1`, `extratags=1` and Additional information requested with `addressdetails=1`, `extratags=1` and
`namedetails=1` can be found in extra elements. `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. https://www.openstreetmap.org/copyright" attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
querystring="london" polygon="false" exclude_place_ids="100149" 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"> 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" class="place" type="city" importance="0.9654895765402"
@ -203,11 +201,12 @@ The place information can be found in the `place` elements, of which there may
be more than one. The attributes of that element contain: be more than one. The attributes of that element contain:
* `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id)) * `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 * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
* `ref` - content of `ref` tag if it exists * `ref` - content of `ref` tag if it exists
* `lat`, `lon` - latitude and longitude of the centroid of the object * `lat`, `lon` - latitude and longitude of the centroid of the object
* `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox)) * `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox))
* `place_rank` - class search rank * `place_rank` - class [search rank](../develop/Ranking#search-rank)
* `address_rank` - place [address rank](../develop/Ranking#address-rank)
* `display_name` - full comma-separated address * `display_name` - full comma-separated address
* `class`, `type` - key and value of the main OSM tag * `class`, `type` - key and value of the main OSM tag
* `importance` - computed importance rank * `importance` - computed importance rank
@ -217,17 +216,19 @@ When `addressdetails=1` is requested, the localised address parts appear
as subelements with the type of the address part. as subelements with the type of the address part.
Additional information requested with `extratags=1` and `namedetails=1` can 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 ## Notes on field values
### place_id is not a persistent id ### place_id is not a persistent id
The `place_id` is created when a Nominatim database gets installed. A The `place_id` is an internal identifier that is assigned data is imported
single place will have a different value on another server or even when into a Nominatim database. The same OSM object will have a different value
the same data gets re-imported. It's thus not useful to treat it as on another server. It may even change its ID on the same server when it is
permanent for later use. 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 The combination `osm_type`+`osm_id` is slighly better but remember in
OpenStreetMap mappers can delete, split, recreate places (and those OpenStreetMap mappers can delete, split, recreate places (and those
@ -236,20 +237,40 @@ 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 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). discussion see [Permanent ID](https://wiki.openstreetmap.org/wiki/Permanent_ID).
Nominatim merges some places (e.g. center node of a city with the boundary If you need an ID that is consistent over multiple installations of Nominatim,
relation) so `osm_type`+`osm_id`+`class_name` would be more unique. 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 ### boundingbox
Comma separated list of min latitude, max latitude, min longitude, max longitude. Comma separated list of min latitude, max latitude, min longitude, max longitude.
The whole planet would be `-90,90,-180,180`. The whole planet would be `-90,90,-180,180`.
Can we used to pan and center the map on the result, for example with leafletjs Can be used to pan and center the map on the result, for example with leafletjs
mapping library mapping library
`map.fitBounds([[bbox[0],bbox[2]],[bbox[1],bbox[3]]], {padding: [20, 20], maxzoom: 16});` `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, Bounds crossing the antimeridian have a min latitude -180 and max latitude 180,
essentially covering the planet (See [issue 184](https://github.com/openstreetmap/Nominatim/issues/184)). essentially covering the entire planet
(see [issue 184](https://github.com/openstreetmap/Nominatim/issues/184)).
### addressdetails ### addressdetails

51
docs/api/Reverse.md
View File

@ -1,36 +1,48 @@
# Reverse Geocoding # Reverse Geocoding
Reverse geocoding generates an address from a latitude and longitude or from Reverse geocoding generates an address from a latitude and longitude.
an OSM object.
## How it works
The reveser geocoding API does not exactly compute the address for the
coordinate it receives. It works by finding the closest suitable OSM object
and returning its address information. This may occasionally lead to
unexpected results.
First of all, Nominatim only includes OSM objects in
its index that are suitable for searching. Small, unnamed paths for example
are missing from the database and can therefore not be used for reverse
geocoding either.
The other issue to be aware of is that the closest OSM object may not always
have a similar enough address to the coordinate you were requesting. For
example, in dense city areas it may belong to a completely different street.
## Parameters ## Parameters
The main format of the reverse API is The main format of the reverse API is
``` ```
https://nominatim.openstreetmap.org/reverse?<query> https://nominatim.openstreetmap.org/reverse?lat=<value>&lon=<value>&<params>
``` ```
There are two ways how the requested location can be specified: where `lat` and `lon` are latitude and longitutde of a coordinare in WGS84
projection. The API returns exactly one result or an error when the coordinate
is in an area with no OSM data coverage.
* `lat=<value>` `lon=<value>` Additional paramters are accepted as listed below.
A geographic location to generate an address for. The coordiantes must be !!! warning "Deprecation warning"
in WGS84 format. The reverse API used to allow address lookup for a single OSM object by
its OSM id. This use is now deprecated. Use the [Address Lookup API](../Lookup)
* `osm_type=[N|W|R]` `osm_id=<value>` instead.
A specific OSM node(N), way(W) or relation(R) to return an address for.
In both cases exactly one object is returned. The two input parameters cannot
be used at the same time. Both accept the additional optional parameters listed
below.
### Output format ### Output format
* `format=[xml|json|jsonv2|geojson|geocodejson]` * `format=[xml|json|jsonv2|geojson|geocodejson]`
See [Place Output Formats](Output.md) for details on each format. (Default: html) See [Place Output Formats](Output.md) for details on each format. (Default: xml)
* `json_callback=<string>` * `json_callback=<string>`
@ -69,8 +81,9 @@ comma-separated list of language codes.
* `zoom=[0-18]` * `zoom=[0-18]`
Level of detail required for the address. Default: 18. This is a number that corresponds Level of detail required for the address. Default: 18. This is a number that
roughly to the zoom level used in map frameworks like Leaflet.js, Openlayers etc. corresponds roughly to the zoom level used in XYZ tile sources in frameworks
like Leaflet.js, Openlayers etc.
In terms of address details the zoom levels are as follows: In terms of address details the zoom levels are as follows:
zoom | address detail zoom | address detail
@ -97,7 +110,7 @@ options can be used at a time. (Default: 0)
* `polygon_threshold=0.0` * `polygon_threshold=0.0`
Simplify the output geometry before returning. The parameter is the Return a simplified version of the output geometry. The parameter is the
tolerance in degrees with which the geometry may differ from the original tolerance in degrees with which the geometry may differ from the original
geometry. Topology is preserved in the result. (Default: 0.0) geometry. Topology is preserved in the result. (Default: 0.0)

52
docs/api/Search.md
View File

@ -1,30 +1,27 @@
# Search queries # Search queries
The search API allows you to look up a location from a textual description. The search API allows you to look up a location from a textual description
Nominatim supports structured as well as free-form search queries. or address. Nominatim supports structured and free-form search queries.
The search query may also contain The search query may also contain
[special phrases](https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases) [special phrases](https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases)
which are translated into specific OpenStreetMap (OSM) tags (e.g. Pub => `amenity=pub`). which are translated into specific OpenStreetMap (OSM) tags (e.g. Pub => `amenity=pub`).
Note that this only limits the items to be found, it's not suited to return complete This can be used to narrow down the kind of objects to be returned.
lists of OSM objects of a specific type. For those use [Overpass API](https://overpass-api.de/).
!!! warning
Special phrases are not suitable to query all objects of a certain type in an
area. Nominatim will always just return a collection of the best matches. To
download OSM data by object type, use the [Overpass API](https://overpass-api.de/).
## Parameters ## Parameters
The search API has the following two formats: The search API has the following format:
```
https://nominatim.openstreetmap.org/search/<query>?<params>
```
This format only accepts a free-form query string where the
parts of the query are separated by slashes.
``` ```
https://nominatim.openstreetmap.org/search?<params> https://nominatim.openstreetmap.org/search?<params>
``` ```
In this form, the query may be given through two different sets of parameters: The search term may be specified with two different sets of parameters:
* `q=<query>` * `q=<query>`
@ -46,13 +43,13 @@ In this form, the query may be given through two different sets of parameters:
Structured requests are faster but are less robust against alternative Structured requests are faster but are less robust against alternative
OSM tagging schemas. **Do not combine with** `q=<query>` **parameter**. OSM tagging schemas. **Do not combine with** `q=<query>` **parameter**.
All three query forms accept the additional parameters listed below. Both query forms accept the additional parameters listed below.
### Output format ### Output format
* `format=[html|xml|json|jsonv2|geojson|geocodejson]` * `format=[xml|json|jsonv2|geojson|geocodejson]`
See [Place Output Formats](Output.md) for details on each format. (Default: html) See [Place Output Formats](Output.md) for details on each format. (Default: jsonv2)
* `json_callback=<string>` * `json_callback=<string>`
@ -96,16 +93,16 @@ Limit search results to one or more countries. `<countrycode>` must be the
e.g. `gb` for the United Kingdom, `de` for Germany. e.g. `gb` for the United Kingdom, `de` for Germany.
Each place in Nominatim is assigned to one country code based Each place in Nominatim is assigned to one country code based
on `admin_level=2` tags, in rare cases to none (for example in on OSM country boundaries. In rare cases a place may not be in any country
international waters outside any country). at all, for example, in international waters.
* `exclude_place_ids=<place_id,[place_id],[place_id]` * `exclude_place_ids=<place_id,[place_id],[place_id]`
If you do not want certain OSM objects to appear in the search If you do not want certain OSM objects to appear in the search
result, give a comma separated list of the `place_id`s you want to skip. result, give a comma separated list of the `place_id`s you want to skip.
This can be used to broaden search results. For example, if a previous This can be used to retrieve additional search results. For example, if a
query only returned a few results, then including those here would cause previous query only returned a few results, then including those here would
the search to return other, less accurate, matches (if possible). cause the search to return other, less accurate, matches (if possible).
* `limit=<integer>` * `limit=<integer>`
@ -122,10 +119,11 @@ are accepted as long as they span a real box. `x` is longitude,
* `bounded=[0|1]` * `bounded=[0|1]`
When a viewbox is given, restrict the result to items contained with that When a viewbox is given, restrict the result to items contained within that
viewbox (see above). When `viewbox` and `bounded=1` are given, an amenity viewbox (see above). When `viewbox` and `bounded=1` are given, an amenity
only search is allowed. In this case, give the special keyword for the only search is allowed. Give the special keyword for the amenity in square
amenity in square brackets, e.g. `[pub]`. (Default: 0) brackets, e.g. `[pub]` and a selection of objects of this type is returned.
There is no guarantee that the result is complete. (Default: 0)
### Polygon output ### Polygon output
@ -140,7 +138,7 @@ options can be used at a time. (Default: 0)
* `polygon_threshold=0.0` * `polygon_threshold=0.0`
Simplify the output geometry before returning. The parameter is the Return a simplified version of the output geometry. The parameter is the
tolerance in degrees with which the geometry may differ from the original tolerance in degrees with which the geometry may differ from the original
geometry. Topology is preserved in the result. (Default: 0.0) geometry. Topology is preserved in the result. (Default: 0.0)
@ -154,13 +152,11 @@ address to identify your requests. See Nominatim's [Usage Policy](https://operat
* `dedupe=[0|1]` * `dedupe=[0|1]`
Sometimes you have several objects in OSM identifying the same place or Sometimes you have several objects in OSM identifying the same place or
object in reality. The simplest case is a street being split in many object in reality. The simplest case is a street being split into many
different OSM ways due to different characteristics. Nominatim will different OSM ways due to different characteristics. Nominatim will
attempt to detect such duplicates and only return one match unless attempt to detect such duplicates and only return one match unless
this parameter is set to 0. (Default: 1) this parameter is set to 0. (Default: 1)
* `debug=[0|1]` * `debug=[0|1]`
Output assorted developer debug information. Data on internals of Nominatim's Output assorted developer debug information. Data on internals of Nominatim's