Forward Geocoding is a function for converting geographic addresses to coordinates in a Latitude - Longitude format. For example, providing an address like "221b Baker St, London NW1 6XE" you would receive its coordinates - "51.524259, -0.1584738", and have it shown on a map.
Using the forward geocoding will result in a list of geographical objects from the OSM database, sorted by relevance. This means options that are considered to more precisely match the expected results, will be at the top of the list.
If you want to narrow your query by the type of the element sought, for example search only cities or countries, you should use the following parameters:
- country - search by country
- state - search by states
- county - search by districts / provinces
- city - search by names of cities
- street - search by names of streets. Should be specified in the following format <house_number> <street_name>
- postalcode - limit the results to a specified postal code
Please note that these parameters are not applicable with the q
Let's consider a search for cities with the name St. Petersburg:
The main geocoding function parameter is the search query that is sent with the key q. Normally, the geographical address of the object is the search query, for example:
221b Baker St, London NW1 6XE
Note, that the query line should be converted to the URL-encoded format.
The q parameter is also sufficient for making a simple query:
The forward geocoding functions are executed using the following queries:
For various reasons you may want to limit your search results. Below you will see several useful parameters which you can use for this.
parameter is used to limit the search area by a country or a list of countries. The parameter value here should be a two-letter country code (or country codes) in the ISO 3166 alpha-2 format. Here's an example:
- Poland - pl
- New Zealand - nz
- China - cn
You may know that London as a geographical name refers not only to the capital of the UK, but also to several cities in the US. In order to exclude the results outside the UK, you should formulate your query as:
The full list of country codes in the ISO 3166 alpha-2 format can be found here
There are a large number of different geo-objects with the same name. But, if you limit your search area geometrically, by way of forming a rectangular area on a coordinate grid, you will probably get better results. This is where the viewbox
parameter comes into play. For example, you want to find coordinates for objects with the word "park" in their names. More specifically, your search is for such objects only in London. Using the results of the previous query, specify:
Please note, that apart from viewbox the query includes the bounded parameter. The use of this parameter guarantees that only the results from the specified area (viewbox) will be shown.
In order to exclude the results you know are irrelevant, use the exclude_place_ids parameter with OSM (place_id) identifiers for unwanted geographical objects. For example, you want to find all objects named "London", excluding the UK capital. Using the place_id that we received as a result for one of our previous queries, we have:
To limit the number of resulting options, use the limit parameter: