/normalize Endpoint

The /normalize endpoint is designed to take an input address, correct any inaccuracies or inconsistencies, and return the normalized address data. Unlike the /geocode endpoint, this endpoint does not perform geocoding. Fields related to geocoding will not be included in the response.

HTTP Method and URL

POST https://api.address-hub.com/normalize

Request Parameters

To use the /normalize endpoint, you need to send a POST request with a JSON payload that includes the following parameters:

• address (required): The physical address you want to normalize. This should be as complete as possible to ensure accurate normalization.
• country (required): The ISO 3166-1 alpha-2 country code for the address. This helps the API apply the correct set of normalization rules.

Example JSON request body:

{
  "address": "otto weidt platz 9 10557 berlin",
  "country": "DE"
}

Headers

Include these HTTP headers in your request:

• AH-API-KEY: YOUR_API_KEY
• Content-Type: application/json

Request Example

Here’s an example of how to make a request to the /normalize endpoint using cURL:

curl -X POST 'https://api.address-hub.com/normalize' -H 'AH-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{ "address": "otto weidt platz 8 10557 berlin", "country": "DE" }'

Response

The response includes the normalized address data. Geocoding-related fields such as latitude, longitude, geocoder_source, accuracy_level, geocode_date, and geocoding_relevance will be set to null.

Example JSON response:

{
    "created_at": "2025-01-25T12:18:09.000000Z",
    "updated_at": "2025-01-25T12:19:06.000000Z",
    "id": "139c88ab-a92e-4c18-b04f-0877a813e3ae",
    "hash": "f04da698f0b621dc32337550e1f8fa0ea51f52220be17f37aabbba18f83cf736",
    "normalizer_version": "2.6.5",
    "street": "Otto-Weidt-Platz",
    "number": "8",
    "zip_code": "10557",
    "locality": null,
    "city": "berlin",
    "country": "DE",
    "formatted_address": "Otto-Weidt-Platz 9, 10557, Berlin, Deutschland",
    "floor": "",
    "staircase": null,
    "door": null,
    "venue": null,
    "po_box": null,
    "co": null,
    "predirectional": null,
    "street_suffix": null,
    "extra": null,
    "state": null,
    "rest": null,
    "road_type": "",
    "street_name": "Otto-Weidt-Platz",
    "sub_locality": null,
    "sub_locality_type": null,
    "geocoding_relevance": null,
    "attributions": "https://address-hub.com/attributions",
    "metadata": [],
    "normalization_relevance": {
        "score": 1,
        "components_confidence": {
            "street": 1,
            "zip_code": 1
        },
        "should_use_normalization": true
    }
}

Status Codes

The /normalize endpoint will return one of the following HTTP status codes:

• 200 OK: The request was successful, and the response body contains the normalized data.
• 400 Bad Request: The request was invalid. This usually occurs if the address parameter is missing or malformed.
• 401 Unauthorized: The API key was missing or invalid.
• 429 Too Many Requests: The request was denied due to rate limiting.
• 500 Internal Server Error: An unexpected error occurred on the server.

Handling Errors

In case of an error, the API will return a JSON object with a message key, providing more details about the issue.

Example error response:

{
  "message": "Invalid API key"
}

Notes

• If you are looking for geocoding functionality along with normalization, please refer to the Geocode Endpoint Documentation.
• The /normalize endpoint is ideal for scenarios where you only need address validation and standardization without geolocation data.

Best Practices

When using the /normalize endpoint, consider the following best practices:

• Provide complete and accurate addresses to ensure the best normalization results.
• Handle HTTP status codes appropriately in your application to gracefully manage errors and successful responses.
• Respect the rate limits to maintain service availability and avoid disruptions.