/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 9 10557 berlin", "country": "DE" }'

Response

The response will include the normalized address and its geocoded latitude and longitude coordinates.

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
    }
}

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.

Geocoding Relevance

The geocoding_relevance object in the response provides additional information about the relevance and accuracy of the geocoded result. This object includes the following fields:

• geocoder_source: Contains the name of the geocoder.
  • relevance: A numerical value indicating the relevance of the geocoded result. Higher values indicate higher relevance.
  • accuracy: A string indicating the accuracy level of the geocoded result. Possible values include PRECISE, INTERPOLATED, GEOMETRIC_CENTER, APPROXIMATE, and GENERAL.

Example:

{
  "geocoding_relevance": {
    "google": {
      "relevance": 0.9,
      "accuracy": "INTERPOLATED"
    },
    "here": {
      "relevance": 0.85,
      "accuracy": "GEOMETRIC_CENTER"
    }
  }
}

This information helps in understanding the quality and reliability of the geocoded address, ensuring that you receive the most relevant and accurate location data.

Geocoder Sources

The geocoder_source key in the geocoding_relevance object indicates the geocoder used to find the best geocoding result. The possible values include:

• internal: AddressHub's internal geocoder based on open data.
• google: Google Maps Geocoding API.
• here: HERE Geocoding API.
• mapbox: Mapbox Geocoding API.

AddressHub employs smart algorithms to select the most appropriate geocoder for each request, ensuring optimal accuracy and relevance. Not all geocoders are used for every request; the selection depends on the specific address and context.

This field helps in understanding which geocoder contributed to the geocoded result, providing transparency and insight into the geocoding process.

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.