Batch Geocode V1

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 processing of Geocoding service offers submission of multiple structured address inputs at once.

Request

POST

/v1/api/batch/geocode?key=[API_KEY]

body of POST message should contain an array of json-formatted structured address input (see. Input format of Geocode V1)

[
{
 "admin_level_2": "Germany",
 "admin_level_8": "Munchen",
 "street": "Bayerstraße",
 "house_number": "32"
},
{
 "admin_level_2": "BE",
 "admin_level_8": "THISNES",
 "street": "ROUTE DE WAVRE",
 "house_number": "100B",
 "postal_code": "4280"
},
{
 "admin_level_2": "United States",
 "admin_level_3": "Maryland",
 "admin_level_8": "Baltimore",
 "street": "Bonaparte Ave",
 "house_number": "898"
}
]

response of successful batch submission is reported by HTTP status code 202 (Accepted)
response header contains a Location value in a form of:
/v1/api/batch/geocode/[job_ID]?key=[API_KEY]

Batch Geocoding submission response headers
Location URI for polling the execution status and results retrieval

Status & result retrieval

Status of a job execution can be checked by polling the Location URI retrieved in the response of batch submission POST request:

GET /v1/api/batch/geocode/[job_ID]?key=[API_KEY]

Batch geocoding status response body

Value Description
results Array of arrays of GeocodingResultItems. In case no location was found for a structured address input, inner array is empty.
results Array of arrays of GeocodingResultItems. In case no location was found for a structured address input, inner array is empty.
state WAITING - job is waiting to be executed

RUNNING - job is currently executing

FINISHED - job execution finished successfully (results property is populated)

FAILED - job execution failed (error property contains an error message with a failure description)
error Error message
status OK
copyright Sygic copyright notice

Batch Geocoding status response headers

Value Description
Retry-After Hint for repeating the request after n seconds

Note: Batch execution result is being kept available for retrieval for a short time after the execution ends. Trying to get the result after a longer period of time might not be possible (response with a result code 404). You should poll the batch service with a reasonable delay between the requests. For this purpose a Retry-After header hint is exposed in the response of unfinished jobs.

{
    "results": [
        [
            {
                "components": [
                    {
                        "type": "admin_level_2",
                        "value": "Germany"
                    },
                    {
                        "type": "admin_level_8",
                        "value": "München"
                    },
                    {
                        "type": "postal_code",
                        "value": "80331"
                    },
                    {
                        "type": "street",
                        "value": "Bayerstraße"
                    },
                    {
                        "type": "house_number",
                        "value": "32"
                    }
                ],
                "formatted_result": "Bayerstraße 32, 80331 München",
                "location": {
                    "lat": 48.139041900634766,
                    "lon": 11.551609992980957
                },
                "location_type": "exact",
                "type": "address",
                "country_iso": "deu"
            }
        ],
        ...
        [
            {
                "components": [
                    {
                        "type": "admin_level_2",
                        "value": "Belgique"
                    },
                    {
                        "type": "admin_level_3",
                        "value": "Wallonie"
                    },
                    {
                        "type": "admin_level_4",
                        "value": "Liège"
                    },
                    {
                        "type": "admin_level_8",
                        "value": "Hannut"
                    },
                    {
                        "type": "admin_level_9",
                        "value": "Thisnes"
                    },
                    {
                        "type": "postal_code",
                        "value": "4280"
                    },
                    {
                        "type": "street",
                        "value": "Route de Wavre"
                    },
                    {
                        "type": "house_number",
                        "value": "152"
                    }
                ],
                "formatted_result": "Route de Wavre 152, 4280 Hannut, Belgique",
                "location": {
                    "lat": 50.67183,
                    "lon": 5.03779
                },
                "location_type": "closest_point",
                "type": "address",
                "country_iso": "bel"
            }
        ],
    ],
    "state": "FINISHED",
    "status": "OK",
    "copyright": "© 2019 Sygic a.s."
}