--- /dev/null
+# Frequently Asked Questions
+
+## API Results
+
+#### 1. The address of my search results contains far-away places that don't belong there.
+
+Nominatim computes the address from two sources in the OpenStreetMap data:
+from administrative boundaries and from place nodes. Boundaries are the more
+useful source. They precisely describe an area. So it is very clear for
+Nominatim if a point belongs to an area of not. Place nodes are more complicated.
+These are only points without any precise extend. So Nominatim has to take a
+guess and assume that an address belongs to the closest place nose it can find.
+In an ideal world, Nominatim would not need the place nodes but there are
+many places on earth where there are not precise boundaries available for
+all parts that make up an address. This is in particular true for the more
+local address parts, like villages and suburbs. Therefore it is not possible
+to completely dismiss place nodes. And sometimes they sneak in where they
+don't belong.
+
+As a OpenStreetMap mapper, you can improve the situation in two ways: if you
+see a place node for which already an administrative area exists, then you
+should _link_ the two by adding the node with a 'label' role to the boundary
+relation. If there is no administrative area, you can add the approximate
+extend of the place and tag it place=<something> as well.
+
+#### 2. When doing reverse search, the address details have parts that don't contain the point I was looking up.
+
+There is a common misconception how the reverse API call works in Nominatim.
+Reverse does not give you the address of the point you asked for. Reverse
+returns the closest object to the point you asked for and then returns the
+address of that object. Now, if you are close to a border, then the closest
+object may be across that border. When Nominatim then returns the address,
+contains the county/state/country across the border.
+
+#### 3. I get different counties/states/countries when I change the zoom parameter in the reverse query. How is that possible?
+
+This is basically the same problem as in the previous answer.
+The zoom level influences at which [search rank](https://wiki.openstreetmap.org/wiki/Nominatim/Development_overview#Country_to_street_level) Nominatim starts looking
+for the closest object. So the closest house number maybe on one side of the
+border while the closest street is on the other. As the address details contain
+the address of the closest object found, you might sometimes get one result,
+sometimes the other for the closest point.
+
-## Address lookup
+# Address lookup
-Lookup the address of one or multiple OSM objects like node, way or relation.
+The lookup API allows to query the address and other details of one or
+multiple OSM objects like node, way or relation.
+
+## Parameters
+
+The lookup API has the following format:
-### Parameters
```
- https://nominatim.openstreetmap.org/lookup?<query>
+ https://nominatim.openstreetmap.org/lookup?osm_ids=[N|W|R]<value>,…,…,&<params>
```
-* `format=[xml|json|geojson]`
+`osm_ids` is mandatory and must contain a comma-separated list of OSM ids each
+prefixed with its type, one of node(N), way(W) or relation(R). Up to 50 ids
+can be queried at the same time.
+
+Additional optional parameters are explained below.
+
+### Output format
+
+* `format=[html|xml|json|jsonv2|geojson|geocodejson]`
- * Output format
- * Defaults to `xml`
+See [Place Output Formats](Output.md) for details on each format. (Default: xml)
* `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.
+
+### Output details
+
+* `addressdetails=[0|1]`
+
+Include a breakdown of the address into elements. (Default: 0)
+
+
+* `extratags=[0|1]`
+
+Include additional information in the result if available,
+e.g. wikipedia link, opening hours. (Default: 0)
+
+
+* `namedetails=[0|1]`
+
+Include a list of alternative names in the results. These may include
+language variants, references, operator and brand. (Default: 0)
+
+
+### Language of results
* `accept-language=<browser language string>`
- * Preferred language order for showing search results, overrides the value specified in the "Accept-Language" HTTP header.
- * Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes.
+Preferred language order for showing search results, overrides the value
+specified in the "Accept-Language" HTTP header.
+Either use a standard RFC2616 accept-language string or a simple
+comma-separated list of language codes.
-* `osm_ids=[N|W|R]<value>,…,[N|W|R]<value`
- * A list of up to 50 specific osm node, way or relations ids to return the addresses for
-* `addressdetails=[0|1]`
- * defaults to 0
- * Include a breakdown of the address into elements
+### Other
* `email=<valid email address>`
- * If you are making large numbers of request please include a valid email address or alternatively include your email address as part of the User-Agent string.
- * This information will be kept confidential and only used to contact you in the event of a problem, see [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.
+If you are making large numbers of request please include an appropriate email
+address to identify your requests. See Nominatim's [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.
+
+* `debug=[0|1]`
-* `extratags=1`
- * Include additional information in the result if available, e.g. wikipedia link, opening hours.
+Output assorted developer debug information. Data on internals of Nominatim's
+"Search Loop" logic, and SQL queries. The output is (rough) HTML format.
+This overrides the specified machine readable format. (Default: 0)
-* `namedetails=1`
- * Include a list of alternative names in the results.
- * These may include language variants, references, operator and brand.
-### Example
+## Examples
##### XML
--- /dev/null
+# Place Output
+
+The [\reverse](Reverse.md), [\search](Search.md) and [\lookup](Lookup.md)
+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.
+
+## Formats
+
+### JSON
+
+The JSON format returns an array of places (for search and lookup) or
+a single place (for reverse) of the following format:
+
+```
+ {
+ "place_id": "100149",
+ "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
+ "osm_type": "node",
+ "osm_id": "107775",
+ "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",
+ "class": "place",
+ "type": "city",
+ "importance": 0.9654895765402,
+ "icon": "https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png",
+ "address": {
+ "city": "London",
+ "state_district": "Greater London",
+ "state": "England",
+ "postcode": "SW1A 2DU",
+ "country": "United Kingdom",
+ "country_code": "gb"
+ },
+ "extratags": {
+ "capital": "yes",
+ "website": "http://www.london.gov.uk",
+ "wikidata": "Q84",
+ "wikipedia": "en:London",
+ "population": "8416535"
+ }
+ },
+```
+
+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
+ * `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`)
+ * `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
+
+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
+
+This format follows the [RFC7946](http://geojson.org). Every feature includes
+a bounding box (`bbox`).
+
+The feature list has the following fields:
+
+ * `place_id` - reference to the Nominatim internal database ID
+ * `osm_type`, `osm_id` - reference to the OSM object
+ * `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
+ (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
+
+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)
+ * `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` -
+ 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.
+
+### XML
+
+The XML response returns one or more place objects in slightly different
+formats depending on the API call.
+
+#### Reverse
+
+```
+<reversegeocode timestamp="Sat, 11 Aug 18 11:53:21 +0000"
+ attribution="Data © OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright"
+ querystring="lat=48.400381&lon=11.745876&zoom=5&format=xml">
+ <result place_id="179509537" osm_type="relation" osm_id="2145268" ref="BY"
+ lat="48.9467562" lon="11.4038717"
+ boundingbox="47.2701114,50.5647142,8.9763497,13.8396373">
+ Bavaria, Germany
+ </result>
+ <addressparts>
+ <state>Bavaria</state>
+ <country>Germany</country>
+ <country_code>de</country_code>
+ </addressparts>
+ <extratags>
+ <tag key="place" value="state"/>
+ <tag key="wikidata" value="Q980"/>
+ <tag key="wikipedia" value="de:Bayern"/>
+ <tag key="population" value="12520000"/>
+ <tag key="name:prefix" value="Freistaat"/>
+ </extratags>
+</reversegeocode>
+```
+
+The attributes of the outer `reversegeocode` element return generic information
+about the query, including the time when the response was sent (in UTC),
+attribution to OSM and the original querystring.
+
+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
+ * `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
+
+The full address 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.
+
+#### Search and Lookup
+
+```
+<searchresults timestamp="Sat, 11 Aug 18 11:55:35 +0000"
+ attribution="Data © OpenStreetMap contributors, ODbL 1.0. http://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">
+ <place place_id="100149" osm_type="node" osm_id="107775" place_rank="15"
+ 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"
+ class="place" type="city" importance="0.9654895765402"
+ icon="https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png">
+ <extratags>
+ <tag key="capital" value="yes"/>
+ <tag key="website" value="http://www.london.gov.uk"/>
+ <tag key="wikidata" value="Q84"/>
+ <tag key="wikipedia" value="en:London"/>
+ <tag key="population" value="8416535"/>
+ </extratags>
+ <city>London</city>
+ <state_district>Greater London</state_district>
+ <state>England</state>
+ <postcode>SW1A 2DU</postcode>
+ <country>United Kingdom</country>
+ <country_code>gb</country_code>
+ </place>
+</searchresults>
+```
+
+The attributes of the outer `searchresults` or `lookupresults` element return
+generic information about the query:
+
+ * `timestamp` - UTC time when the response was sent
+ * `attribution` - OSM licensing information
+ * `querystring` - original query
+ * `polygon` - true when extra geometry information was requested
+ * `exclude_place_ids` - IDs of places that should be ignored in a follow-up request
+ * `more_url` - search call that will yield additional results for the query
+ just sent
+
+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
+ * `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
+ * `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)
+
+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
+be found in extra elements as sub-element of each place.
+
--- /dev/null
+### Nominatim API
+
+Nominatim indexes named (or numbered) features with the OSM data set and a subset of other unnamed features (pubs, hotels, churches, etc).
+
+Its API has the following endpoints for querying the data:
+
+ * __[/search](Search.md)__ - search OSM objects by name or type
+ * __[/reverse](Reverse.md)__ - search OSM object by their location
+ * __[/lookup](Lookup.md)__ - look up address details for OSM objects by thier ID
+ * __/status__ - query the status of the server
+ * __/deletable__ - list objects that have been deleted in OSM but are held
+ back in Nominatim in case the deletion was accidental
+ * __/polygons__ - list of broken polygons detected by Nominatim
+ * __/details__ - show internal details for an object (for debugging only)
-## Reverse Geocoding
+# Reverse Geocoding
-Reverse geocoding generates an address from a latitude and longitude. The optional `zoom` parameter specifies the level of detail required in terms of something suitable for a Leaflet.js/OpenLayers/etc. zoom level.
+Reverse geocoding generates an address from a latitude and longitude or from
+an OSM object.
+
+## Parameters
+
+The main format of the reverse API is
-### Parameters
```
https://nominatim.openstreetmap.org/reverse?<query>
```
+There are two ways how the requested location can be specified:
+
+* `lat=<value>` `lon=<value>`
+
+ A geographic location to generate an address for. The coordiantes must be
+ in WGS84 format.
+
+* `osm_type=[N|W|R]` `osm_id=<value>`
+
+ 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 paramters cannot
+be used at the same time. Both accept the additional optional parameters listed
+below.
+
+### Output format
+
* `format=[xml|json|jsonv2|geojson|geocodejson]`
- * Output format
- * defaults to `xml`
- * `jsonv2` adds the next fields to response:
- * `place_rank`
- * `category`
- * `type`
- * `importance`
- * `addresstype`
+See [Place Output Formats](Output.md) for details on each format. (Default: html)
* `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.
-* `accept-language=<browser language string>`
+### Output details
- * Preferred language order for showing search results, overrides the value specified in the "Accept-Language" HTTP header.
- * Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes.
+* `addressdetails=[0|1]`
-* `osm_type=[N|W|R]` `osm_id=<value>`
- * A specific osm node / way / relation to return an address for
- * **Please use this in preference to lat/lon where possible**
+Include a breakdown of the address into elements. (Default: 1)
-* `lat=<value>` `lon=<value>`
- * The location to generate an address for
+
+* `extratags=[0|1]`
+
+Include additional information in the result if available,
+e.g. wikipedia link, opening hours. (Default: 0)
+
+
+* `namedetails=[0|1]`
+
+Include a list of alternative names in the results. These may include
+language variants, references, operator and brand. (Default: 0)
+
+
+### Language of results
+
+* `accept-language=<browser language string>`
+
+Preferred language order for showing search results, overrides the value
+specified in the "Accept-Language" HTTP header.
+Either use a standard RFC2616 accept-language string or a simple
+comma-separated list of language codes.
+
+### Result limitation
* `zoom=[0-18]`
- * Level of detail required where `0` is country and `18` is house/building
-* `addressdetails=[0|1]`
- * defaults to 0
- * Include a breakdown of the address into elements
+Level of detail required for the address. This is a number that corresponds
+roughly to the zoom level used in map frameworks like Leaflet.js, Openlayers etc.
+In terms of address details the zoom levels are as follows:
-* `email=<valid email address>`
+ zoom | address detail
+ -----|---------------
+ 3 | country
+ 5 | state
+ 8 | county
+ 10 | city
+ 14 | suburb
+ 16 | street
+ 18 | building
- * If you are making large numbers of request please include a valid email address or alternatively include your email address as part of the User-Agent string.
- * This information will be kept confidential and only used to contact you in the event of a problem, see [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.
-* `polygon_geojson=1`
- * Output geometry of results in geojson format.
+### Polygon output
+* `polygon_geojson=1`
* `polygon_kml=1`
- * Output geometry of results in kml format.
-
* `polygon_svg=1`
- * Output geometry of results in svg format.
-
* `polygon_text=1`
- * Output geometry of results as a WKT.
+
+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`
- * defaults to 0.0
- * Simplify the output geometry before returning. The parameter is the
- tolerance in degrees with which the geometry may differ from the original
- geometry. Topology is preserved in the result.
-* `extratags=1`
- * Include additional information in the result if available, e.g. wikipedia link, opening hours.
+Simplify the output geometry before returning. 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
+
+* `email=<valid email address>`
+
+If you are making large numbers of request please include an appropriate email
+address to identify your requests. See Nominatim's [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.
+
+
+* `debug=[0|1]`
+
+Output assorted developer debug information. Data on internals of Nominatim's
+"Search Loop" logic, and SQL queries. The output is (rough) HTML format.
+This overrides the specified machine readable format. (Default: 0)
-* `namedetails=1`
- * Include a list of alternative names in the results.
- * These may include language variants, references, operator and brand.
-### Example
+## Examples
* [https://nominatim.openstreetmap.org/reverse?format=xml&lat=52.5487429714954&lon=-1.81602098644987&zoom=18&addressdetails=1](https://nominatim.openstreetmap.org/reverse?format=xml&lat=52.5487429714954&lon=-1.81602098644987&zoom=18&addressdetails=1)
}
```
-### Hierarchy
-
-* Admin level => XML entity
- * 2 => `<country>`
- * 4 => `<state>`
- * 5 => `<state_district>`
- * 6
- * 7 => `<county>`
- * 8 => `<village>`
- * 9 => `<city_district>`
- * 10 => `<suburb>`
+# Search queries
-## Search
-Nominatim indexes named (or numbered) features with the OSM data set and a subset of other unnamed features (pubs, hotels, churches, etc)
+The search API allows to look up a location from a textual description.
+Nominatim supports structured as well as free-form search queries.
-Search terms are processed first left to right and then right to left if that fails.
+The search query may also contain
+[special phrases](https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases)
+which are tranlated into specific OpenStreetMap(OSM) tags (e.g. Pub => amenity=pub).
+Note that this only limits the items to be found. It is not suited to return complete
+lists of OSM objects of a specific type.
+Use [Overpass API](https://overpass-api.de/) for that.
-Both searches will work: [pilkington avenue, birmingham](//nominatim.openstreetmap.org/search?q=pilkington+avenue,birmingham), [birmingham, pilkington avenue](//nominatim.openstreetmap.org/search?q=birmingham,+pilkington+avenue)
+## Parameters
-(Commas are optional, but improve performance by reducing the complexity of the search.)
+The search API has the following two formats:
-Where house numbers have been defined for an area they should be used: [135 pilkington avenue, birmingham](//nominatim.openstreetmap.org/search?q=135+pilkington+avenue,+birmingham)
-
-### Special Keywords
-Various keywords are translated into searches for specific osm tags (e.g. Pub => amenity=pub). A current list of [special phrases](https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases) processed is available.
+```
+ https://nominatim.openstreetmap.org/search/<query>?<params>
+```
-### Parameters
+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/<query>?<params>
```
-* `format=[html|xml|json|jsonv2|geojson|geocodejson]`
+In this form, the query may be given through two different sets of parameters:
+
+* `q=<query>`
- * Output format
- * defaults to `html`
+ Free-form query string to search for.
+ Free-form queries are processed first left to right and then right to
+ left if that fails. So you may search for
+ [pilkington avenue, birmingham](//nominatim.openstreetmap.org/search?q=pilkington+avenue,birmingham) as well as for
+ [birmingham, pilkington avenue](//nominatim.openstreetmap.org/search?q=birmingham,+pilkington+avenue).
+ Commas are optional, but improve performance by reducing the complexity
+ of the search.
+
+
+* `street=<housenumber> <streetname>`
+ `city=<city>`
+ `county=<county>`
+ `state=<state>`
+ `country=<country>`
+ `postalcode=<postalcode>`
+
+ Alternative query string format for structured requests.
+ Structured requests are faster but are less robust against alternative
+ OSM tagging schemas. **Do not combine with** `q=<query>` **parameter**.
+
+All three query forms accept the additional paramters listed below.
+
+### Output format
+
+* `format=[html|xml|json|jsonv2|geojson|geocodejson]`
+See [Place Output Formats](Output.md) for details on each format. (Default: html)
* `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.
-* `accept-language=<browser language string>`
+### Output details
- * Preferred language order for showing search results, overrides the value specified in the "Accept-Language" HTTP header.
- * Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes.
+* `addressdetails=[0|1]`
-* `q=<query>`
+Include a breakdown of the address into elements. (Default: 0)
- * Query string to search for.
- * Alternatively can be entered as:
- * `street=<housenumber> <streetname>`
- * `city=<city>`
- * `county=<county>`
- * `state=<state>`
- * `country=<country>`
- * `postalcode=<postalcode>`
-
- **(experimental)** Alternative query string format for structured requests.
-Structured requests are faster and require fewer server resources. **Do not combine with `q=<query>` parameter**.
+* `extratags=[0|1]`
-* `countrycodes=<countrycode>[,<countrycode>][,<countrycode>]...`
+Include additional information in the result if available,
+e.g. wikipedia link, opening hours. (Default: 0)
- * Limit search results to a specific country (or a list of countries).
- * `<countrycode>` should be the ISO 3166-1alpha2 code, e.g. `gb` for the United Kingdom, `de` for Germany, etc.
-* `viewbox=<x1>,<y1>,<x2>,<y2>`
- * The preferred area to find search results. Any two corner points of the box are accepted in any order as long as they span a real box.
+* `namedetails=[0|1]`
-* `bounded=[0|1]`
- * defaults to 0
- * Restrict the results to only items contained with the viewbox (see above).
- * Restricting the results to the bounding box also enables searching by amenity only.
- * For example a search query of just `"[pub]"` would normally be rejected but with `bounded=1` will result in a list of items matching within the bounding box.
+Include a list of alternative names in the results. These may include
+language variants, references, operator and brand. (Default: 0)
-* `polygon=[0|1]`
- * defaults to 0
- * Output polygon outlines for items found **(deprecated, use one of the polygon_* parameters instead)**
-* `addressdetails=[0|1]`
- * defaults to 0
- * Include a breakdown of the address into elements
+### Language of results
-* `email=<valid email address>`
+* `accept-language=<browser language string>`
+
+Preferred language order for showing search results, overrides the value
+specified in the "Accept-Language" HTTP header.
+Either use a standard RFC2616 accept-language string or a simple
+comma-separated list of language codes.
+
+### Result limitation
+
+* `countrycodes=<countrycode>[,<countrycode>][,<countrycode>]...`
+
+Limit search results to one or more countries. `<countrycode>` must be the
+ISO 3166-1alpha2 code, e.g. `gb` for the United Kingdom, `de` for Germany.
- * If you are making large numbers of request please include a valid email address or alternatively include your email address as part of the User-Agent string.
- * This information will be kept confidential and only used to contact you in the event of a problem, see [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.
* `exclude_place_ids=<place_id,[place_id],[place_id]`
- * If you do not want certain openstreetmap objects to appear in the search 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 query only returned a few results, then including those here would cause the search to return other, less accurate, matches (if possible)
+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.
+This can be used to broaden search results. For example, if a previous
+query only returned a few results, then including those here would cause
+the search to return other, less accurate, matches (if possible).
+
* `limit=<integer>`
- * defaults to 10
- * Limit the number of returned results.
-* `dedupe=[0|1]`
- * defaults to 1
- * 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 different OSM ways due to different characteristics.
- * Nominatim will attempt to detect such duplicates and only return one match; this is controlled by the dedupe parameter which defaults to 1. Since the limit is, for reasons of efficiency, enforced before and not after de-duplicating, it is possible that de-duplicating leaves you with less results than requested.
+Limit the number of returned results. (Default: 10)
-* `debug=[0|1]`
- * defaults to 0
- * Output assorted developer debug information. Data on internals of nominatim "Search Loop" logic, and SQL queries. The output is (rough) HTML format. This overrides the specified machine readable format.
-* `polygon_geojson=1`
- * Output geometry of results in geojson format.
+* `viewbox=<x1>,<y1>,<x2>,<y2>`
-* `polygon_kml=1`
- * Output geometry of results in kml format.
+The preferred area to find search results. Any two corner points of the box
+are accepted in any order as long as they span a real box.
-* `polygon_svg=1`
- * Output geometry of results in svg format.
+* `bounded=[0|1]`
+
+When a viewbox is given, restrict the result to items contained with that
+viewbox (see above). When `viewbox` and `bounded` are given, an amenity
+only search is allowed. In this case, give the special keyword for the
+amenity in squaer brackets, e.g. `[pub]`. (Default: 0)
+
+
+### Polygon output
+
+* `polygon_geojson=1`
+* `polygon_kml=1`
+* `polygon_svg=1`
* `polygon_text=1`
- * Output geometry of results as a WKT.
+
+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`
- * defaults to 0.0
- * Simplify the output geometry before returning. The parameter is the
- tolerance in degrees with which the geometry may differ from the original
- geometry. Topology is preserved in the result.
-* `extratags=1`
- * Include additional information in the result if available, e.g. wikipedia link, opening hours.
+Simplify the output geometry before returning. 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
+
+* `email=<valid email address>`
+
+If you are making large numbers of request please include an appropriate email
+address to identify your requests. See Nominatim's [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.
+
+* `dedupe=[0|1]`
+
+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
+different OSM ways due to different characteristics. Nominatim will
+attempt to detect such duplicates and only return one match unless
+this parameter is set to 0. (Default: 1)
-* `namedetails=1`
- * Include a list of alternative names in the results.
- * These may include language variants, references, operator and brand.
-### Examples
+
+* `debug=[0|1]`
+
+Output assorted developer debug information. Data on internals of Nominatim's
+"Search Loop" logic, and SQL queries. The output is (rough) HTML format.
+This overrides the specified machine readable format. (Default: 0)
+
+
+
+## Examples
##### XML with polygon points
}
]
}
-```
\ No newline at end of file
+```
Nominatim (from the Latin, 'by name') is a tool to search OSM data by name and address and to generate synthetic addresses of OSM points (reverse geocoding).
+
+This guide comes in three parts:
+
+ * __[API reference](api/Overview.md)__ for users of Nominatim
+ * __[Administration Guide](admin/Installation.md)__ for those who want
+ to install their own Nominatim server
+ * __[Developer's Guide](develop/overview.md)__ for developers of the software
pages:
- 'Introduction' : 'index.md'
- 'API Reference':
+ - 'Overview': 'api/Overview.md'
- 'Search': 'api/Search.md'
- 'Reverse': 'api/Reverse.md'
- 'Address Lookup': 'api/Lookup.md'
+ - 'Place Output Formats': 'api/Output.md'
+ - 'FAQ': 'api/Faq.md'
- 'Administration Guide':
- 'Basic Installation': 'admin/Installation.md'
- 'Importing and Updating' : 'admin/Import-and-Update.md'
// for POI or street level
if ($iMaxRank >= 26) {
$sSQL = 'select place_id,parent_place_id,rank_address,country_code,';
- $sSQL .= 'CASE WHEN ST_GeometryType(geometry) in (\'ST_Polygon\',\'ST_MultiPolygon\') THEN ST_distance('.$sPointSQL.', centroid)';
- $sSQL .= ' ELSE ST_distance('.$sPointSQL.', geometry) ';
- $sSQL .= ' END as distance';
+ $sSQL .= ' ST_distance('.$sPointSQL.', geometry) as distance';
$sSQL .= ' FROM ';
$sSQL .= ' placex';
$sSQL .= ' WHERE ST_DWithin('.$sPointSQL.', geometry, '.$fSearchDiam.')';
$aViewBox[3]
);
- $fHeight = $aViewBox[0] - $aViewBox[2];
- $fWidth = $aViewBox[1] - $aViewBox[3];
+ $fHeight = abs($aViewBox[0] - $aViewBox[2]);
+ $fWidth = abs($aViewBox[1] - $aViewBox[3]);
$this->sqlViewboxLarge = sprintf(
'ST_SetSRID(ST_MakeBox2D(ST_Point(%F,%F),ST_Point(%F,%F)),4326)',
} else {
$oToken = new Token\Word(
$iId,
- $aWord['word'][0] != ' ',
+ $aWord['word_token'][0] != ' ',
(int) $aWord['count']
);
}
projects / nominatim.git / commitdiff