Validating an Address

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

Basic Validation

Validating an address using Uniserv’s RESTful API is quick and easy. Just pass the address in JSON format and send it to the validation endpoint at https://api.uniserv.com/ using HTTP POST:

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

{
    "street": "Rastatter Str.",
    "houseNumber": "13",
    "postalCode": "75179",
    "locality": "Pforzheim",
    "country": "DE"
}

The API supports many more input variations, which are documented in the API reference. For example, you can pass street and house number in a single addressLine field instead of using separate fields. However, no matter which input variant you use, the result structure is always the same.

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

Check the address against its database of valid addresses
Correct the address in case of mistakes (wrong postal code, spelling mistakes, etc.)
Enrich the address with additional information (if requested)
Return the corrected address (if possible) with an indication of the address quality

In the best case (the address is valid without any errors), you will receive a result like this:

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

{
    "resultClass": "A",
    "results": [
        {
            "addressType": "delivery",
            "country": "DE",
            "postalCode": "75179",
            "locality": "Pforzheim",
            "localityAbbreviation": "Pforzheim",
            "subLocality": "Wilferdinger Höhe",
            "street": "Rastatter Str.",
            "streetAbbreviation": "Rastatter Str.",
            "houseNumber": "13"
        }
    ]
}

Uniserv always returns a list of addresses, with the resultClass attribute indicating the quality of the result:

A: perfect match; the address is returned as-is
B: normalized match; some small syntactic fixes (i.e. case conversion)
C: corrected match; corrections with high confidence (i.e. fixed postal code based on street and house number)
D: probable match; corrections with lower confidence, but only one matching candidate address has been identified
E: ambiguous match, returns a list of candidate addresses
F: no match; the address is invalid

Class D is often flagged for manual review and class E requires user interaction to select one of the proposed addresses.

In more complicated cases, class E results may contain a list of valid house number ranges - for example, when the input didn’t specify a house number and the street crosses multiple postal code areas:

{
    "resultClass": "E",
    "results": [
        {
            "postalCode": "3008",
            ...
            "houseNumberChoice": [
                { "from": "58", "to": "76", "step": "even" },
                { "from": "59", "to": "71", "step": "odd" }
            ]
        },
        {
            "postalCode": "3007",
            ...
            "houseNumberChoice": [
                { "from": "2", "to": "32", "step": "even" },
                { "from": "11", "to": "47", "step": "odd" }
            ]
        }
    ]
}

Without additional user input it is not possible to choose the postal code, which means postal delivery to that address may fail.

Requesting Additional Information

In addition to address validation, Uniserv can enrich the address with related information, like geo coordinates (longitude, latitude) or delivery information.

For example, we request coordinates based on the World Geodetic System (WGS, revision 84):

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

{
    "street": "Rastatter Straße",
    "houseNumber": "13",
    "postalCode": "75179",
    "locality": "Pforzheim",
    "country": "DE",

    "_options": {
        "include": ["coordinates-wgs84"]
    }
}

The response will then contain the requested information, in this case geo coordinates:

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

{
  "resultClass": "B",
  "results": [
    {
      "street": "Rastatter Str.",
      ...

      "coordinates": {
        "wgs84": {
          "precision": "house-number",
          "lat": 48.89855,
          "lon": 8.66726
        }
      }
    }
  ],

  ...
}

If you need field-by-field information on how well the input matched the returned candidates, you can request the metadata option:

    "_options": {
        "include": ["metadata"]
    }

Each candidate will then have a _meta attribute with additional information on each input field.

Alternative authentication with session token

In addition to using the API key for authentication, as shown in the previous examples, the validation endpoint can also be used with a session token, created by the start-session endpoint, as described in the Autocomplete documentation. In this case, the session token needs to be added as Bearer token in the Authorization header:

POST /location/v1/validate
Content-Type: application/json
Authorization: Bearer <your-session-token-here>

{
    "street": "Rastatter Str.",
    "houseNumber": "13",
    "postalCode": "75179",
    "locality": "Pforzheim",
    "country": "DE"
}

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.