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 parameter.
Let's consider a search for cities with the name St. Petersburg:

GET https://api.pickpoint.io/v1/forward

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:

GET /forward/?key=YOUR-API-KEY&q=21b%20Baker%20St,%20London%20NW1%206XE

GET /forward/?key=YOUR-API-KEY&city=Saint-Petersburg

For various reasons you may want to limit your search results. Below you will see several useful parameters which you can use for this.

The countrycodes 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:

GET /forward/?key=YOUR-API-KEY&q=London&countrycodes=gb

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:

GET /forward/?key=YOUR-API-KEY&q=park&viewbox=0.0,52.0,1.0,53.0&bounded=1

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:

GET /forward/?key=YOUR-API-KEY&q=London&exclude_place_ids=158415464

To limit the number of resulting options, use the limit parameter:

GET /forward/?key=YOUR-API-KEY&q=London&limit=1

Reverse Geocoding is a function that converts coordinates in Latitude – Longitude format into geographical addresses. For example, by providing input coordinates "51.524259, -0.1584738" you will get the geographical address for this point.

The results of the reverse geocoding function can be scaled by way of changing the zoom parameter from 0 (widest parameter – countries) to 18 (narrowest parameter – buildings). Example:

https://api.pickpoint.io/v1/reverse

In order to execute a simple reverse geocoding function you need to use two parameters: lat – latitude, and lon - longitude. These parameters should be specified in degrees. Example:

Reverse geocoding functions are available at the following address:

GET /reverse/?key=YOUR-API-KEY&lat=48.85881005&lon=2.32003101155031

GET /reverse/?key=YOUR-API-KEY&lat=52.183430&lon=-106.2707519&zoom=0

Address Lookup is a function for converting OSM identifiers to geographical addresses with corresponding coordinates. For example, the OSM database has a way with identifier 3996986 which is saved for you as a result of a geocoding function. Using lookup you can get a geographical address: "Baker Street, Marylebone, Westminster, London, Greater London, England, NW1 6XE".

https://api.pickpoint.io/v1/lookup

This function's input is the osm_ids parameter. It should list the objects (from one to 50), separated by commas. For every object you must specify which OSM type it belongs to, and next to it should be the object identifier. There are three main OSM object types:

• R - relation
• W - way
• N - node

Here are examples for each object type:

This is the entry point for the address lookup function:

GET /lookup/?key=YOUR-API-KEY&osm_ids=W481027013,N1809771508,R568660