Geocode V1

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