API REFERENCE

This section is intended for developers of applications and servers that use the PickPoint geocoding platform. Before you start working with API you need to create an account. To quickly familiarize yourself with our service please refer to the Getting Started section.

All you need to start experimenting is any utility for sending HTTP-requests, or you can even use your web browser's address bar. You can also use GEO LAB, which is available from your account dashboard

While developing PickPoint we did our best to minimize the effort needed to integrate it with your products. We deliberately decided not to use Basic Authentication, Bearer Token Authentication and others, in favor of using user keys directly in the URL requests to our service.

To start working with our service you must first copy your API Key that is available from your account subscription section:

Please note, that all PickPoint functions are accessible only with an access key.

https://api.pickpoint.io/v1/?key=YOUR-API-KEY

Open the resulting URL in the address bar of your browser. You will see a "Welcome to PickPoint API" message. This means that you have been successfully authorized and connected to our API. Otherwise, you will see an "Unauthorized" message.

To use PickPoint API functions you need to add your API key to all of your queries:

Now you can make your first request to the PickPoint API. To do that, create a URL in the following format:

?key=YOUR-API-KEY

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

ENTRYPOINT

QUERY

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

BOUNDARIES

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

ENTRYPOINT

QUERY

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

ENTRYPOINT

QUERY

Our geocoding platform supports two of the most common response formats: JSON and XML. You can change them by including the desired format (json or xml) in the format parameter of the query, for example:

GET /forward/?key=YOUR-API-KEY&q=Tokyo&format=json

Using the accept-language parameter you can specify the preferred geocoding result language. The value of this parameter must be specified in the format ab-XY, where:

• • "ab" – is a two-letter language code in the ISO 639-1 format. For example, "en" is English, "fr" is French, "ru" is Russian. To see the full list of all language codes click here.
• • "XY" – is a two-letter country code in the ISO-3166 format. For example, "ES" is Spain, "DE" is Germany, "CN" is China. To see the full list of country codes, click here.

Example:

GET /forward/?key=YOUR-API-KEY&q=Tokyo&accept-language=en

Each type of geocoding query is able to return addresses in a structured format. For this you should use the addressdetails=1 parameter. As a result, in the response body there will be a new 'addressparts' attribute (for address lookup queries the detailed address is a part of the response body) that describes every part of the found address in detail.

Example of a query with detailed address:

GET /reverse/?key=YOUR-API-KEY&lat=48.8698899&lon=2.3084521&zoom=18&addressdetails=1

If you need to see a list of names of a geo-objects in other languages, or find possible alternative names, use the namedetails=1 parameter. The response will have a new 'namedetails' attribute with a list of all possible names, like in the following example:

GET /lookup/?key=YOUR-API-KEY&osm_ids=R2360164&namedetails=1

In some cases you may need to know the boundaries of geo-objects, for example, to show them on a map or to visualize them in any other way. Currently, this option is only available for forward and reverse geocoding queries. You can get these coordinates in four different formats:

• GeoJSON - when setting the polygon_geojson parameters to 1, the result will come in the geojson attribute of the response line.
• KML - send polygon_kml=1, to receive coordinates as the value of the geokml attribute.
• SVG - data in this format should be requested using the polygon_svg=1 parameter. The result will appear in the geosvg attribute.
• Text - to receive coordinates as text, use the polygon_text=1 parameter. The result will be in the geotext attribute.

Here's an example, for receiving the boundaries of London:

GET /forward/?key=YOUR-API-KEY&q=Tokyo&format=json