Batch reverse geocoding v1

Move to section

Please note Sygic does no longer issue new Sygic Maps API keys. This documentation is for existing customers only. If you wish to include maps & navigation into your project, please refer to Sygic Maps SDK.

Overview

Batch reverse geocoding allows you to get address information for multiple GPS positions at the same time with limitation to 1000 locations per request.
Batch reverse geocoding is a two step process:

POST request that consist of json with array GPS coordiantes sets to be reverse geocoded
GET request that will retrieve results from the server once processed

Live Example

This example demonstrates the use of the Reverse geocoding service. Click on icons to see the code on Github or play with it in JSFiddle:

Request

Methods

Method	Description
POST	Initiate batch reverse geocoding. Contains JSON data to be reversely geocoded.
GET	Monitor status and retrieve results from the server once processed.

API Reference

https://geocoding.api.sygic.com/v1/api/batch/reversegeocode?key=yourAPIkey

Request authentication is done via parameter key, which must be included in the request URL.

Parameters

Batch reverse geocoding API takes an array of coordinate objects as input.

Parameter	Data type	Description
lat	double / string	Latitude
lon	double / string	Longitude

Create batch job

Request

POST https://geocoding.api.sygic.com/v1/api/batch/reversegeocode?key=yourAPIkey

Request Body

[
        {
            "lat": "51.50105925961465",
            "lon": "-0.12856364250183108"
        },
        {
            "lat": "51.50124960223127",
            "lon": "-0.12593507766723636"
        }
]

Response

Status: 202 Accepted
Location: https://geocoding.api.sygic.com/v1/api/batch/reversegeocode/{id}?key=yourAPIkey

{
    "status": "OK",
    "copyright": "© 2018 Sygic a.s."
}

Monitor batch job

To request a result of batch request, you need an ID of your result from the previously provided POST request. The link containing the ID can be found in the Location header of the POST response.

Request

GET https://geocoding.api.sygic.com/v1/api/batch/reversegeocode/{id}?key=yourAPIkey

Response

Status: 200
Retry-After: 1

{
  "state": "WAITING|RUNNING|FINISHED|FAILED",
  "status": "OK|NO_RESULTS",
  "error": {
    "code": "...",
    "message": "..."
  },
  "results": [..],
  "copyright": "© 2018 Sygic a.s."
}

Client is expected to perform regular polling on the result URL until the job is finished. Client should wait between each try, as advised by Retry-After header value (in seconds).

State	Status	Description
WAITING	NO_RESULTS	Request has been accepted and batch job is waiting to be processed.
RUNNING	NO_RESULTS	Batch job is running.
FINISHED	OK	Batch job has succeeded and result is ready.
FAILED	NO_RESULTS	Batch job has failed to produce result, error object contains further details.

Get batch result

Successfully finished batch job contains reversely geocoded locations from given coordinates.

{
    "results": [
        [
            {
                "components": [
                    {
                        "type": "house_number",
                        "value": "14"
                    },
                    {
                        "type": "route",
                        "value": "Im Krämmel"
                    },
                    {
                        "type": "admin_level_1",
                        "value": "Rheinland-Pfalz"
                    },
                    {
                        "type": "admin_level_7",
                        "value": "Kusel"
                    },
                    {
                        "type": "admin_level_8",
                        "value": "Waldmohr"
                    },
                    {
                        "type": "buildup_area",
                        "value": "Waldmohr"
                    },
                    {
                        "type": "postal_code",
                        "value": "66914"
                    },
                    {
                        "type": "country",
                        "value": "Germany"
                    }
                ],
                "formatted_result": "Waldmohr, Waldmohr, 66914, Germany",
                "location": {
                    "lat": 49.386313,
                    "lon": 7.339133
                },
                "location_type": "exact",
                "type": "address",
                "country_iso": "deu",
                "distance": 0.35
            },
            {
                "components": [
                    {
                        "type": "admin_level_1",
                        "value": "Rheinland-Pfalz"
                    },
                    {
                        "type": "admin_level_7",
                        "value": "Kusel"
                    },
                    {
                        "type": "admin_level_8",
                        "value": "Waldmohr"
                    },
                    {
                        "type": "buildup_area",
                        "value": "Waldmohr"
                    },
                    {
                        "type": "country",
                        "value": "Germany"
                    },
                    {
                        "type": "postal_code",
                        "value": "66914"
                    }
                ],
                "formatted_result": "Waldmohr, Waldmohr, 66914, Germany",
                "location": {
                    "lat": 49.386494,
                    "lon": 7.338406
                },
                "location_type": "centroid",
                "type": "locality",
                "country_iso": "deu"
            }
        ],
        [
            {
                "components": [
                    {
                        "type": "house_number",
                        "value": "18"
                    },
                    {
                        "type": "route",
                        "value": "Eastlake Street"
                    },
                    {
                        "type": "admin_level_1",
                        "value": "England"
                    },
                    {
                        "type": "admin_level_7",
                        "value": "Devon"
                    },
                    {
                        "type": "admin_level_8",
                        "value": "Plymouth"
                    },
                    {
                        "type": "buildup_area",
                        "value": "Plymouth"
                    },
                    {
                        "type": "postal_code",
                        "value": "PL1 1BA"
                    },
                    {
                        "type": "country",
                        "value": "United Kingdom"
                    }
                ],
                "formatted_result": "Eastlake Street 18, PL1 1BA Plymouth, United Kingdom",
                "location": {
                    "lat": 50.373274,
                    "lon": -4.139419
                },
                "location_type": "interpolated",
                "type": "address",
                "country_iso": "gbr",
                "distance": 43.1
            },
            {
                "components": [
                    {
                        "type": "admin_level_1",
                        "value": "England"
                    },
                    {
                        "type": "admin_level_7",
                        "value": "Devon"
                    },
                    {
                        "type": "admin_level_8",
                        "value": "Plymouth"
                    },
                    {
                        "type": "buildup_area",
                        "value": "Plymouth"
                    },
                    {
                        "type": "country",
                        "value": "United Kingdom"
                    },
                    {
                        "type": "postal_code",
                        "value": "PL4 8"
                    }
                ],
                "formatted_result": "Plymouth, United Kingdom",
                "location": {
                    "lat": 50.398806,
                    "lon": -4.141642
                },
                "location_type": "centroid",
                "type": "locality",
                "country_iso": "gbr"
            }
        ]
    ],
    "state": "FINISHED",
    "status": "OK",
    "copyright": "© 2018 Sygic a.s."
}

Previous article: Reverse Geocode v0 [Deprecated]
Next article: Batch reverse geocode