Batch reverse geocode

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. 

##### This version of Batch reverse geocoding service will be removed from production support on September 30, 2018.

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:

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

Request

API reference

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

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

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.

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/v0/api/batch/reversegeocode?key=yourAPIkey

Request Body

[
  {
    "lat": 49.38631,
    "lon": 7.33913
  },
  {
    "lat": 50.37352,
    "lon": -4.13895
  }
]

Response

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

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

Monitor batch job

Batch job state can be monitored by performing GET operation on the returned URL location.

Request

GET https://geocoding.api.sygic.com/v0/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": [
        {
            "location": {
                "country": "Germany",
                "city": "Waldmohr",
                "street": "Im Krämmel",
                "house_number": "14",
                "zip": "66914",
                "admin_level_1": "Rheinland-Pfalz"
            },
            "geometry": {
                "lat": 49.38631,
                "lon": 7.33913
            },
            "distance": 0
        },
        {
            "location": {
                "country": "United Kingdom",
                "city": "Plymouth",
                "street": "Eastlake Street",
                "house_number": "18",
                "zip": "PL1 1BA",
                "admin_level_1": "England"
            },
            "geometry": {
                "lat": 50.373265,
                "lon": -4.139416
            },
            "distance": 59.084196836869793
        }
    ],
    "state": "FINISHED",
    "status": "OK",
    "copyright": "© 2018 Sygic a.s."
}