Geocoding 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

Geocoding allows you to retrieve GPS coordinates and complete address info for searched address.

Request

API Reference

Geocoding service is located under following API reference:

https://geocoding.api.sygic.com/

Parameters

Geocoding service offers geographic location output based on structured address input

GET /v1/api/geocode?admin_level_2=[country_name]&admin_level_8=[city_name]&street=[street_name]&house_number=[house_number]&key=[API_KEY]

Parameter Is mandatory Example Description
key yes /geocode?key=ABCDEFGH Api key for accessing the service
admin_level_2 / country yes /geocode?admin_level_2=Germany Country name, ISO2 or ISO3 code
admin_level_3 no /geocode?admin_level_3=Bayern Country subdivision (e.g. state name in USA or Germany)
admin_level_8 / municipality yes /geocode?admin_level_8=Munchen Municipality name (city name)
key no /geocode?admin_level_9=Ludwigsvorstadt Municipality subdivision name
postal_code no /geocode?postal_code=80335 Postal code
street yes /geocode?street=Bayerstraße Name of the street
house_number yes /geocode?house_number=32 House (street) number

Response

Geocoding response is in the JSON format.

Top-level element consists of an array of results, status and copyright notice.

Geocoding response

Value Description
results Array of GeocodingResultItems
status Descriptive response status

OK - in case of HTTP status code 200

ACCESS_DENIED - status code 401, missing or invalid ApiKey

INVALID_REQUEST - status code 400, invalid combination of required parameters or missing parameter

OVER_QUERY_LIMIT - status code 429, throttling limit exceeded
copyright Sygic copyright notice

GeocodingResultItem

Value Description
components Array of GeocodingComponents
formatted_result Formatted address
location Geographic location of result
location_type Kind of geographic location in relation to results

exact - exact match of result location

interpolated - location match based on interpolation from an address range

closest_point - result contains match of closest address point service could find based on specified location (e.g. if service can't find a house number '14' but it found an address with house number '12')
type Type of result item

address - address point result type

road - street result type (in case address point was not found)
country_iso ISO3 code of the country

GeocodingComponent

Value Description
type location component type. Multiple items with the same type are allowed

admin_level_2 - country name

admin_level_3 - country subdivision

admin_level_4 - country secondary subdivision

admin_level_8 - municipality name (city)

admin_level_9 - municipality subdivision

postal_code - postal code of the area

street - street name

house_number - house number
value String value

Response example

{
    "results": [
        {
            "components": [
                {
                    "type": "admin_level_2",
                    "value": "Deutschland"
                },
                {
                    "type": "admin_level_3",
                    "value": "Bayern"
                },
                {
                    "type": "admin_level_4",
                    "value": "München (Stadt)"
                },
                {
                    "type": "admin_level_8",
                    "value": "München"
                },
                {
                    "type": "admin_level_9",
                    "value": "Ludwigsvorstadt"
                },
                {
                    "type": "postal_code",
                    "value": "80335"
                },
                {
                    "type": "street",
                    "value": "Bayerstraße"
                },
                {
                    "type": "house_number",
                    "value": "32"
                }
            ],
            "formatted_result": "Bayerstraße 32, 80335 München, Deutschland",
            "location": {
                "lat": 48.13918,
                "lon": 11.5516
            },
            "location_type": "exact",
            "type": "address",
            "country_iso": "deu"
        }
    ],
    "status": "OK",
    "copyright": "© 2019 Sygic a.s."
}

Service status codes

200 - service returned a result (see response format section)
202 - batch job submission succeeded
204 - service did not find the specified location
400 - mandatory input parameter is missing
401 - invalid API key
404 - batch job was not found
429 - throttling limit exceeded
500 - service error
504 - service request timed out