/retrieve Endpoint

The /retrieve endpoint allows you to retrieve a previously normalized and geocoded address using its unique identifier. This is useful when you need to access the full address details, including geocoding information, after normalization.

Note

This endpoint does not trigger any normalization or geocoding behavior. It only retrieves the address data from the database using the provided ID.

HTTP Method and URL

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

Request Parameters

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

• normalized_address_id (required): The unique identifier (UUID) of the normalized address you want to retrieve. This ID is returned in the response from the /normalize or /geocode endpoints.

Example JSON request body:

{
  "normalized_address_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

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 /retrieve endpoint using cURL:

curl -X POST 'https://api.address-hub.com/retrieve' -H 'AH-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{ "normalized_address_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }'

Response

The response will include the complete normalized address with all geocoding information, matching the same structure as the /geocode endpoint response.

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": "9",
    "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,
    "latitude": 52.5336828,
    "longitude": 13.366826,
    "geocoder_source": "OpenData",
    "accuracy_level": "PRECISE",
    "geocode_date": "2025-01-25 12:19:06",
    "confidence_score": 1,
    "building_id": 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": {
        "internal": {
            "relevance": 1,
            "accuracy": "PRECISE"
        }
    },
    "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 /retrieve endpoint will return one of the following HTTP status codes:

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

Use Cases

The /retrieve endpoint is particularly useful in scenarios such as:

• Caching and Storage: Store only the id in your database and retrieve full address details when needed.
• Address History: Access previously processed addresses without re-normalizing or re-geocoding.
• Reference Lookups: Quickly retrieve complete address information using a stored identifier.