Reverse Geocoding

In order to try these examples, head over to Uniserv CONNECT and create an API Key (test accounts are free!).

Introduction

Reverse Geocoding offers the option to find addresses by coordinates.

Reverse Geocoding

Request one result

POST /location/v1/reverse-geocode
Content-Type: application/json
Authorization: Bearer <your-api-key-here>

{
    "wgs84": {
        "lat": 48.89788,
        "lon": 8.66731
    },
    "tolerance":  10
}

Request multiple results

POST /location/v1/reverse-geocode
Content-Type: application/json
Authorization: Bearer <your-api-key-here>

{
    "wgs84": {
        "lat": 47.660546,
        "lon": 8.876075
    },
    "tolerance":  30
}

Explanation for the API you can find here: API reference

When Uniserv receives the request, it will do the following:

Check the coordinates against its database of valid addresses
If a tolerance is added check for candidates in the tolerance range
Return the candidates

In the best case, you will receive a result like this:

Response one result

HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "distance": 13,
            "country": "DE",
            "region": "Baden-Württemberg",
            "postalCode": "75179",
            "locality": "Pforzheim",
            "localityAbbreviation": "Pforzheim",
            "subLocality": "Wilferdinger Höhe",
            "subLocalityAbbreviation": "Wilferdinger Höhe",
            "street": "Rastatter Str.",
            "streetAbbreviation": "Rastatter Str.",
            "houseNumber": "13",
            "coordinates": {
                "wgs84": {
                    "precision": "house-number",
                    "lat": 48.89788,
                    "lon": 8.66712
                }
            }
        }
    ]
}

Response multiple results

{
    "results": [
        {
            "distance": 26,
            "country": "DE",
            "region": "Baden-Württemberg",
            "postalCode": "78337",
            "locality": "Öhningen",
            "localityAbbreviation": "Öhningen",
            "localityAddition": "Bodensee",
            "subLocality": "Öhningen",
            "subLocalityAbbreviation": "Öhningen",
            "street": "Steiner Str.",
            "streetAbbreviation": "Steiner Str.",
            "houseNumber": "30",
            "coordinates": {
                "wgs84": {
                    "precision": "house-number",
                    "lat": 47.66045,
                    "lon": 8.87640
                }
            }
        },
        {
            "distance": 27,
            "country": "CH",
            "region": "Schaffhausen",
            "postalCode": "8260",
            "locality": "Stein am Rhein",
            "localityAbbreviation": "Stein am Rhein",
            "street": "Oehningerstrasse",
            "streetAbbreviation": "Oehningerstrasse",
            "houseNumber": "79",
            "coordinates": {
                "wgs84": {
                    "precision": "house-number",
                    "lat": 47.66068,
                    "lon": 8.87576
                }
            }
        },
        {
            "distance": 27,
            "country": "CH",
            "region": "Schaffhausen",
            "postalCode": "8260",
            "locality": "Stein am Rhein",
            "localityAbbreviation": "Stein am Rhein",
            "street": "Oehningerstrasse",
            "streetAbbreviation": "Oehningerstrasse",
            "houseNumber": "77",
            "coordinates": {
                "wgs84": {
                    "precision": "house-number",
                    "lat": 47.66053,
                    "lon": 8.87571
                }
            }
        }
    ]
}

Troubleshooting

The API returns errors with HTTP status codes and a payload in problem+json format (see RFC 7807):

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
X-Uniserv-Request-Id: ea9a76bd3e80875f

{
    "status": 401,
    "type": "https://docs.uniserv.com/location/problems#no-auth-data",
    "title": "No authorization header present"
}

The type attribute is a URI that points to a description of the error and possible solutions. For more information please refer to the list of errors.