Batch Geocode V0 [Deprecated]

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 geocoding allows you to retrieve GPS coordinates and complete address info for searched addresses. Batch Geocoding is a two step process:

  1. POST request that consist of json with addresses to be geocoded
  2. GET request that will retrieve results from the server once processed

Request

API Reference

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

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

Methods

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

Parameters

For the full list of supported parameters see Geocode API documentation.

Create batch job

Request

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

Request Body

[
    {
        "location": "Paul-Robeson-Straße+21,+10439+Berlin,+Germany"
    },
    {
        "country": "Germany",
        "city": "Berlin",
        "street": "Neumagener Straße",
        "house_number": "2",
        "zip": "13088",
        "admin_level_1": "Berlin"
    }
]

Response

Status: 202 Accepted
Location: https://geocoding.api.sygic.com/v0/api/batch/geocode/{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/geocode/{id}?key=yourAPIkey

Response

Status: 200
Retry-After: 1

{
  "state": "WAITING|RUNNING|FINISHED|FAILED",
  "status": "OK|NO_RESULTS",
  "error": {
    "code": "...",
    "message": "..."
  },
  "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 distance matrix 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 GPS coordinates and complete address info for searched locations.

{
    "results": [
        {
            "location": {
                "country": "Germany",
                "city": "Berlin",
                "street": "Paul-Robeson-Straße",
                "house_number": "10",
                "zip": "10439",
                "admin_level_1": "Berlin"
            },
            "geometry": {
                "lat": 52.55255,
                "lon": 13.4101
            },
            "confidence": 0.53662663125887211
        },
        {
            "location": {
                "country": "Germany",
                "city": "Berlin",
                "street": "Neumagener Straße",
                "house_number": "2",
                "zip": "13088",
                "admin_level_1": "Berlin"
            },
            "geometry": {
                "lat": 52.55732,
                "lon": 13.47227
            },
            "confidence": 0.90238095238095239
        }
    ],
    "state": "FINISHED",
    "status": "OK",
    "copyright": "© 2018 Sygic a.s."
}