Batch Reverse Geocode v1

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

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."
    }