/geocode Endpoint

The /geocode endpoint is designed to take an input address, normalize it to correct any inaccuracies or inconsistencies, and then return precise geolocation data.

HTTP Method and URL

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

Request Parameters

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

• address (required): The physical address that you want to geocode. This should be as complete as possible to ensure accuracy.
• country (required): The ISO 3166-1 alpha-2 country code for the address. This helps the API to better understand the address and apply the right set of normalization rules to improve geocoding results.

Example JSON request body:

{
  "address": "otto weidt platz 8 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 /geocode endpoint using cURL:

curl -X POST 'https://api.address-hub.com/geocode' -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 will include the normalized address and its geocoded latitude and longitude coordinates.

Example JSON response:

{
    "created_at": "2024-07-13T13:20:35.000000Z",
    "updated_at": "2024-07-13T13:20:35.000000Z",
    "id": "c9ec25fc-39a1-4ac7-afe5-755b42b75aa5",
    "hash": "a515277362c858831efacf7ef8d07fa4748bf108e26e470699226c3f71dd0bbd",
    "normalizer_version": "2.5.3",
    "street": "Otto-Weidt-Platz",
    "number": "8",
    "zip_code": "10557",
    "locality": null,
    "city": "berlin",
    "country": "DE",
    "formatted_address": "Otto-Weidt-Platz 8, 10557, berlin, Deutschland",
    "floor": "",
    "staircase": null,
    "door": null,
    "venue": null,
    "po_box": null,
    "co": null,
    "latitude": 52.5328468,
    "longitude": 13.3673032,
    "geocoder_source": "Google",
    "accuracy_level": "PRECISE",
    "geocode_date": "2024-07-13 13:20:35",
    "confidence_score": 0.8333333333333335,
    "building_id": null,
    "predirectional": null,
    "street_suffix": null,
    "extra": null,
    "state": "",
    "rest": null,
    "road_type": "",
    "street_name": "Otto-Weidt-Platz",
    "sub_locality": null,
    "sub_locality_type": null
}

Accuracy Level

The accuracy_level field indicates the level of confidence in the geocoded result. The possible values are:

• PRECISE: The geocoded result is highly accurate.
• INTERPOLATED: The result is an estimate (typically along a street) calculated between two exact points (such as crossroads)
• GEOMETRIC_CENTER: Means that the provided result represents the geometric midpoint of a feature, such as a polyline (e.g., a street) or a polygon (e.g., a region).
• APPROXIMATE: The provided result is an estimate
• GENERAL: The provided result is a general location, such as a city or town.

Confidence Score

The confidence_score represents the final calculated value of how closely a geocoded address matches the normalized address. It is derived by evaluating the relevance of key address components such as street, number, zip code, locality, city, and country, each weighted according to its importance.

The score ranges from 0 to 1, with higher values indicating a higher degree of confidence in the match. This score helps in determining the accuracy and reliability of the geocoded address, ensuring you receive precise and relevant location information.

Status Codes

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

• 200 OK: The request was successful, and the response body contains the geocoded 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 an message key, providing more details about the issue.

Example error response:

{
  "message": "Invalid API key"
}

Best Practices

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

• Ensure the address is as complete and accurate as possible to improve geocoding 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.