services / location / cloud / 1.0 / development-guides

Structuring an Address

To try these examples, sign up for a free test account on Uniserv CONNECT and get your API key!

Basic Usage

The Structure API takes an unstructured, single‐line address and splits it into its component. Send a JSON POST to the /structure endpoint:

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

{
  "singleLine": "Uniserv GmbH Roland Pfeiffer Geschäftsführung Rastatter Str. 13 75179 Pforzheim"
}

The service will:

  1. Validate your API key.

  2. Detect the country code.

  3. Segment the input into address elements.

  4. Return the parsed fields in JSON.

Example Response

In a successful call, you receive HTTP 200 and a JSON body with each element:

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

{
  "country": "DE",
  "postalCode": "75179",
  "locality": "Pforzheim",
  "subLocality": null,
  "street": "Rastatter Str.",
  "houseNumber": "13",
  "recipient": "Roland Pfeiffer",
  "organization": "Uniserv GmbH",
  "organizationAddition": "Geschäftsführung",
  "unidentifiedElements": []
}

The unidentifiedElements array lists any words that couldn’t be assigned to a known field.

Field Reference

See the Data Model for full details: Structure Data Model.

Field Type Description

singleLine

string

Input: the full address in one line.

country

string

Detected country code.

postalCode

string

Postal code, if recognized.

locality

string

City or town name, if recognized.

subLocality

string

District or neighborhood, if recognized.

street

string

Street name, if recognized.

houseNumber

string

House number, if recognized.

recipient

string

Person’s name, if identified.

organization

string

Organization name, if identified.

organizationAddition

string

Extra org info (e.g. department), if present.

unidentifiedElements

array[string]

Tokens that couldn’t be assigned.

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: abcd1234

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

For a full list of error types and remedies, see list of errors.