💻 Purpose of the API

The Routeplanner Search API is a geocoding service that converts addresses, place names, and other location descriptions into geographic coordinates — and vice versa. It supports free-text, structured, and hybrid queries, and tolerates incomplete or slightly incorrect input.

Use it to:

• Convert an address string into latitude/longitude coordinates for mapping or routing
• Validate and complete partial address input
• Find places, POIs, or administrative areas by name
• Enrich addresses with structured components (country, state, city, postal code, street, house number)

🤔 How to use?

Base URL

https://api.company.info/routeplanner/search

Authentication

All requests require an API key passed as a request header:

X-API-Key: YOUR_API_KEY

GET /geocode

Geocode an address or place name into coordinates. Returns a ranked list of matches from most likely to least likely. Supports free-text queries, structured queries, and their combinations.

Query modes

You must provide either q, qq, or both in every request.

q — Free-text query

Pass any unstructured address string. The API will parse and match it as best it can, tolerating partial or slightly incorrect input.

/geocode?q=Kalverstraat 20 Amsterdam
/geocode?q=Beacon Boston Hospital

qq — Qualified (structured) query

Pass a structured query using named sub-parameters separated by semicolons. Use this when you have clean, separated address components.

Supported sub-parameters: country, state, county, city, district, street, houseNumber, postalCode

/geocode?qq=street=Kalverstraat;houseNumber=20;city=Amsterdam;country=Netherlands
/geocode?qq=postalCode=1012NX
/geocode?qq=city=Amsterdam;country=Netherlands

Combining q and qq

You can pass both in the same request. This is useful when you want structured control over some fields and free-text for others.

/geocode?q=20&qq=street=Kalverstraat;city=Amsterdam

Search context parameters

These parameters narrow down where the API looks for results.

at — Search center

Bias results towards a specific location. Provide as {latitude},{longitude}.

/geocode?q=coffee&at=52.3676,4.9041

in — Geographic boundary (hard filter)

Restrict results to a specific country or countries. Results outside this area will not be returned.

Format: countryCode:{ISO3166-1-alpha-3}[,{code}]*

/geocode?q=Amsterdam&in=countryCode:NLD
/geocode?q=Springfield&in=countryCode:USA,CAN

ℹ️

Country codes must be uppercase ISO 3166-1 alpha-3 (e.g. NLD, DEU, GBR, USA).

Other parameters

Example request

Geocode a Dutch address, restricted to the Netherlands, in English:

curl --request GET \
     --url 'https://api.company.info/routeplanner/search/geocode?qq=street=Kalverstraat;houseNumber=20;city=Amsterdam&in=countryCode:NLD&lang=en&limit=5' \
     --header 'X-API-Key: YOUR_API_KEY'

Example response

{
  "items": [
    {
      "title": "Kalverstraat 20, 1012 NX Amsterdam, Netherlands",
      "id": "here:af:streetsection:abc123",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "Kalverstraat 20, 1012 NX Amsterdam, Netherlands",
        "countryCode": "NLD",
        "countryName": "Netherlands",
        "state": "North Holland",
        "city": "Amsterdam",
        "street": "Kalverstraat",
        "postalCode": "1012 NX",
        "houseNumber": "20"
      },
      "position": {
        "lat": 52.3712,
        "lng": 4.8936
      },
      "access": [
        {
          "lat": 52.3711,
          "lng": 4.8935
        }
      ],
      "mapView": {
        "west": 4.8926,
        "south": 52.3702,
        "east": 4.8946,
        "north": 52.3722
      },
      "scoring": {
        "queryScore": 1.0,
        "fieldScore": {
          "streets": [1.0],
          "houseNumber": 1.0,
          "city": 1.0,
          "postalCode": 1.0
        }
      }
    }
  ]
}

Understanding the response

Result ranking

Results are returned in items as a ranked array, from most likely to least likely match. Always evaluate the first result first, but use scoring to decide programmatically how confident you should be.

resultType

Indicates what kind of location was matched:

houseNumberType

Only present when resultType is houseNumber:

houseNumberFallback

If true, the requested house number did not exist in the map data and the nearest known house number on the same street was returned instead. Use scoring.fieldScore.houseNumber to see how close the match was.

position vs access

• position — the display pin coordinate. Use this for showing a marker on a map.
• access — the navigation access point (e.g. driveway entrance or parking lot entry). Use this as the destination when routing.

mapView

A bounding box (west, south, east, north) that encloses the result. Useful for setting the map viewport to frame the result.

distance

Distance in meters from the search center (at parameter) to this result. Only present when at is provided.

Scoring

The scoring object helps you assess match quality programmatically.

queryScore

A value between 0 and 1 representing overall match quality. A score of 1.0 means all input tokens were recognized and matched perfectly.

fieldScore

Per-field scores between 0 and 1 showing how well each part of the result matches the corresponding part of the query. Only fields that were actually matched are included.

Use these scores to decide whether to auto-accept a result or prompt the user to confirm. For example, if queryScore is below 0.7 you may want to present the result as a suggestion rather than a definitive match.

BETA: Query parsing (show=parsing)

Add show=parsing to your request to receive a breakdown of how the API interpreted your query. The parsing object in the response shows which terms in your input were matched to which address fields, including their character positions.

Useful for debugging unexpected results or building query analysis tooling.

⚠️ Possible errors

🛠️ Try it yourself!

Test the API directly in our API reference.

🔤 Glossary

Geocoding The process of converting a human-readable address or place name into geographic coordinates (latitude and longitude).

BCP 47 language code A standardized format for language tags. Examples: en (English), nl (Dutch), de (German), fr (French).

ISO 3166-1 alpha-3 A three-letter country code standard. Examples: NLD (Netherlands), DEU (Germany), GBR (United Kingdom), USA (United States).

Qualified query (qq) A structured search query where each address component is passed as a named key-value pair (e.g. city=Amsterdam;street=Kalverstraat), as opposed to a single free-text string.

Point Address (PA) A house number that exists as an exact, individually registered point in the map data. More precise than an interpolated address.

Interpolated address A house number that was estimated by the API based on the known number range of the street, rather than being individually registered. Less precise than a Point Address.

Access point The navigable entry point to a location — for example a driveway, building entrance, or parking lot entry — as distinct from the display pin position. Used as the destination when calculating routes.

MapView A bounding box defined by four coordinates (west, south, east, north) that frames the geographic extent of a result. Useful for setting a map viewport.

❓ FAQ

Do I need to provide both q and qq? No, you need at least one. You can provide only q, only qq, or both together. Combining them gives you structured control over some fields while keeping others as free text.

What happens if the house number I search for doesn't exist in the map data? The API returns the nearest known house number on the same street and sets houseNumberFallback: true. Check scoring.fieldScore.houseNumber for the numeric difference between what you requested and what was returned.

How do I restrict results to the Netherlands only? Add in=countryCode:NLD to your request. This is a hard filter — no results from outside the Netherlands will be returned.

What is the difference between position and access? position is the display pin — where you put the marker on a map. access is the navigation entry point — where a routing engine should direct a driver or walker. For most addresses these are close but not identical.

How do I interpret queryScore? A score of 1.0 means a perfect match — all input was recognized and matched. Scores below 0.7 generally indicate a weak match where you should prompt the user to confirm the result. Scores near 0 indicate the input was not meaningfully matched.

Can I get results in Dutch? Yes, add lang=nl to your request. The API will render place names, country names, and other localised strings in Dutch where available.

What is houseNumberType: interpolated and should I trust it? An interpolated address means the house number was estimated rather than individually mapped. It is less precise than a Point Address (PA). For most use cases it is accurate enough, but if precision is critical — such as for emergency services or legal address validation — you should treat interpolated results with more caution.