--- updatedAt: 2026-04-15T11:55:55.000Z agentTools: projectIndex: https://docs.company.info/llms.txt --- # Geo Search
# Purpose 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 | Parameter | Type | Default | Max | Description | | -------------- | ------- | ------- | --- | --------------------------------------------------------------------------------- | | `limit` | integer | 20 | 100 | Maximum number of results to return | | `lang` | string | — | — | Response language as BCP 47 language code (e.g. `nl`, `en`, `de`) | | `show` | string | — | — | Enable additional response fields. Currently supports `parsing` (BETA) | | `X-Request-ID` | header | — | — | Optional request identifier for logging and error correlation. UUIDv4 recommended | *** ### Example request Geocode a Dutch address, restricted to the Netherlands, in English: ```curl 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 ```json { "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: | Value | What it means | | -------------------- | ---------------------------------------- | | `houseNumber` | An exact address with a house number | | `street` | A street without a specific house number | | `locality` | A city, postal code, or district | | `administrativeArea` | A county, state, or country | | `place` | A point of interest or named place | | `intersection` | A street crossing (BETA) | | `postalCodePoint` | A postal code centroid (BETA) | | `addressBlock` | A block or sub-block | #### `houseNumberType` Only present when `resultType` is `houseNumber`: | Value | What it means | | -------------- | ----------------------------------------------------------------------------------- | | `PA` | Point Address — the house number exists precisely in the map data | | `interpolated` | The house number was estimated by interpolating between known numbers on the street | #### `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. | Field | What it measures | | ------------------------------ | ------------------------------------------------------------------------ | | `city` | How well the city name matched | | `streets` | How well the street name(s) matched (array, one score per street) | | `houseNumber` | How close the house number is (numeric difference from requested number) | | `postalCode` | How well the postal code matched | | `country` / `state` / `county` | How well the administrative area matched | 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 | HTTP Status | When it occurs | What to do | | ------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `400 Bad Request` | Neither `q` nor `qq` was provided, or a parameter has an invalid format | Check that at least one of `q` or `qq` is present and that parameter values are correctly formatted | | `405 Method Not Allowed` | A request was made using an HTTP method other than GET | Use `GET` for all requests to this endpoint | | `503 Service Unavailable` | Temporary server-side issue | Retry after a short delay with exponential backoff; contact support if it persists | *** # Try it yourself! Test the API directly in our [API reference](https://docs.company.info/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.