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

Additional Response Fields

The /geocode response can include additional fields that provide more context about how the result was obtained and how the selection among multiple geocoders was made. These fields are additive and do not change the meaning of existing fields.

Cache Info

• cache_info (object): Provides cache metadata for the response.
  • layer (string): Which cache tier was consulted or returned the response. Possible values:
    • request_cache: The full request was cached and returned from the request cache.
    • fresh_geocode: No cache for this address was found, neither in the request cache nor in the database (address was geocoded fresh).
    • database_cache: The address was found in the database, meaning it was previously geocoded and is still cached under the terms and conditions of the geocoder used.
  • hit (boolean): Whether a cache hit occurred at that layer.

Geocode Attempts

• geocode_attempts (integer): Number of geocoding provider calls attempted during this request (includes internal and/or external providers that were actually called). Use this to reason about latency and cost.

Extended Address Components

When available, the following optional components may appear:

• block (string|null): Block identifier where applicable (e.g., manzana, block).
• lot (string|null): Lot/parcel identifier when present in the address system.
• settlement (string|null): Named settlement distinct from city/locality (e.g., colonia, barrio, village).
• settlement_type (string|null): Classification of the settlement (e.g., colonia, barrio, comuna, village).

Timestamps

• geocode_date now returns an ISO‑8601 UTC timestamp (e.g., 2025-08-20T14:48:19.000000Z). Historical records may show older formats; clients should parse as a timestamp.

Geocoding Decision Trace (Extended)

The geocoding_relevance object can include a full decision trace that explains how providers were evaluated and why a winner was selected. This includes:

• Top-level

  • stop_reason (string): Why the provider loop stopped. One of:
    • threshold — best score reached/exceeded the acceptance threshold.
    • early_exit — an early‑exit heuristic triggered.
    • end_of_list — all providers were evaluated and no earlier stop condition fired.
  • _summary (object): Compact snapshot for quick inspection:
    • stop_reason — see above.
    • selected — provider key of the final winner (e.g., internal, google, here, mapbox).
    • best_score — final best combined score.
    • threshold — acceptance threshold in effect.

• Per‑provider entries (keyed by provider, e.g., internal, google, here, mapbox):

  • relevance (0–1): Textual/address component match quality.
  • spatial_relevance (0–1): Polygon/proximity fit.
  • accuracy (enum): One of PRECISE, INTERPOLATED, GEOMETRIC_CENTER, APPROXIMATE, GENERAL.
  • accuracy_score (0–1): Accuracy normalized to a score.
  • combined_score (0–1+): Weighted score used to rank providers.
  • best_so_far (0–1+): Best combined score at the time this provider was evaluated.
  • delta (float): Improvement over best_so_far at evaluation time (combined_score - best_so_far).
  • decision (enum): One of:
    • candidate — became best‑so‑far (improved by ≥ minDelta).
    • selected — final winner.
    • rejected — not selected (e.g., no meaningful improvement vs. best).
    • skipped — excluded (e.g., overconfident or invalid result).
    • not_attempted — provider was not called due to an earlier stop.
  • reason (string): Short code explaining why. Examples:
    • highest_combined_score — final selection.
    • no_meaningful_improvement — delta below the acceptance margin.
    • overconfident — flagged by internal plausibility checks.
    • superseded_by — replaced by the final selected provider.
    • stopped_by — not attempted because the loop stopped (threshold or early_exit).
  • superseded_by (string, optional): Provider key that beat this candidate.
  • stopped_by (string, optional): Mirrors top‑level stop_reason when decision is not_attempted.

Tip: Combine stop_reason with per‑provider decision to see when paid providers (e.g., Google, HERE) were avoided.

Trimmed example including new fields:

{
  "cache_info": {
    "layer": "fresh_geocode",
    "hit": false
  },
  "geocode_attempts": 1,
  "geocoding_relevance": {
    "internal": {
      "relevance": 1,
      "spatial_relevance": 0,
      "accuracy": "PRECISE",
      "accuracy_score": 1,
      "decision": "selected",
      "reason": "highest_combined_score",
      "combined_score": 0.57,
      "best_so_far": 0.57,
      "delta": 0
    },
    "here": {
      "relevance": 0.8333333333333335,
      "spatial_relevance": 0,
      "accuracy": "PRECISE",
      "accuracy_score": 1,
      "decision": "rejected",
      "reason": "no_meaningful_improvement",
      "combined_score": 0.5283333333333333,
      "best_so_far": 0.57,
      "delta": -0.04166666666666674
    },
    "google": {
      "relevance": 0.8333333333333335,
      "spatial_relevance": 0,
      "accuracy": "PRECISE",
      "accuracy_score": 1,
      "decision": "rejected",
      "reason": "no_meaningful_improvement",
      "combined_score": 0.5283333333333333,
      "best_so_far": 0.57,
      "delta": -0.04166666666666674
    },
    "stop_reason": "end_of_list",
    "_summary": {
      "stop_reason": "end_of_list",
      "selected": "internal",
      "best_score": 0.57,
      "threshold": "0.77"
    }
  },
  "block": null,
  "lot": null,
  "settlement": null,
  "settlement_type": null
}

These additions are backward‑compatible and optional; clients can safely ignore unknown fields. If you rely on the decision trace, treat field presence as feature‑gated (rollouts may be incremental).

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

Extended fields recap

When present, geocoding_relevance includes the decision trace detailed above (per‑provider relevance, spatial_relevance, accuracy_score, combined_score, decision, reason, best_so_far, delta) plus the top‑level stop_reason and _summary. These fields explain how a provider was chosen and are useful for auditing quality vs. cost decisions.

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.