# 📖 Autocomplete Geocoding API – Parameters Overview

The Autocomplete Geocoding API accepts several parameters that control how partial address lookups are performed and how suggestions are returned.
They fall into two categories: **mandatory** (must be present) and **optional**.

## ✅ Mandatory

- **`place`**
The free-text input (postal address, city, POI, etc.) to autocomplete.
👉 This field is **always required**.
- **`coordinate`**
Defines the center of the search area (latitude & longitude, WGS84).
⚠️ Most providers require this field for accurate suggestions.
Type: [Coordinate](#coordinate).
- **`language`**
Language code (ISO 639-1, 2 letters) used for suggestions.
Special value: `"IC"` → case-insensitive country code search.
👉 Must always be provided.


## ⚙️ Optional

- **`boundingBox`**
Restrict the autocomplete search to a rectangular area in WGS84 coordinates.
Type: [BoundingBox](#boundingbox).
- **`countryCode`**
Restrict results to a specific country (ISO 3166 Alpha-2 or Alpha-3 code).
- **`geoserver`**
Name of the geoserver to use.
Supported values: `nominatim`, `addok`, `herehlp`.
If not defined, the default geoserver will be used.
- **`radius`**
Defines the search radius in meters around the given coordinate. Type: `long`.
- **`addressDetails`**
If `true`, returns suggestions split into fields (`country`, `city`, `street`, etc.).
Default: `false`.
- **`enCategories`**
Enables category IDs in the response (primary flagged).
- **`enChains`**
Enables chain metadata (e.g., franchise information).
- **`enEntrances`**
Returns geo-coordinates of entrances (when available).
- **`enFoodTypes`**
Returns food-type IDs (primary flagged).
- **`enHighlights`**
Returns text slices matching the query, useful for highlighting.
- **`enLocId`**
Specific to `herehlp`: returns Location ID if `true`.
- **`enReferences`**
Returns supplier-specific source IDs when available.


## 📦 Example (overview)


```
{
  "geoserver": "nominatim",
  "place": "Paris",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "boundingBox": {
    "minLat": 48.80,
    "minLon": 2.25,
    "maxLat": 48.95,
    "maxLon": 2.45
  },
  "countryCode": "FR",
  "language": "fr",
  "radius": 10000,
  "addressDetails": true,
  "enHighlights": true,
  "maximumResults": 5
}
```

## 🏷️ place

✅ **Use case**

Provide a **free-text input** (postal address, city, POI, etc.) to trigger autocomplete suggestions.
This is the starting point of the query — the text the user is typing.

💡 **What it does**

The service analyzes the string and returns a **list of possible completions**: street names, cities, POIs, depending on the context and provider.

🔧 **How to enable**

Add the `place` field in the request body with a text string.
👉 This field is **mandatory**.


```
{
  "place": "Boulevard Sai"
}
```

📦 **Example**


```
{
  "geoserver": "nominatim",
  "place": "Boulevard Sai",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "language": "fr",
  "maximumResults": 3
}
```

## 📍 coordinate

✅ **Use case**

Define the **center of the search area** to improve the relevance of autocomplete suggestions.
Useful when the same place name exists in different regions.

💡 **What it does**

The service prioritizes suggestions that are **closer to the given coordinate** (latitude, longitude, WGS84).
Some providers require this parameter to work.

🔧 **How to enable**


```
{
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  }
}
```

📦 **Example**


```
{
  "geoserver": "nominatim",
  "place": "Boulevard Sai",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "language": "fr",
  "maximumResults": 3
}
```

## 🌐 language

✅ **Use case**

Control the **language of suggestions** returned by the service.
Useful for multilingual regions or international applications.

💡 **What it does**

If the requested language is supported, suggestions are returned in that language.
If not, the **default language** of the geoserver is used.
Special value `"IC"` → enables case-insensitive search by country codes (ISO-3166 Alpha-2 or Alpha-3).

🔧 **How to enable**


```
{
  "language": "fr"
}
```

📦 **Example**


```
{
  "geoserver": "nominatim",
  "place": "Boulevard Sai",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "language": "fr",
  "maximumResults": 3
}
```

## 📐 boundingBox

✅ **Use case**

Limit the autocomplete search to a **specific rectangular area**.
This avoids irrelevant suggestions coming from other regions when a place name is ambiguous.

💡 **What it does**

The service only considers results **inside the defined rectangle** (WGS84 coordinates).
Useful for narrowing down searches to a city, region, or trip corridor.

🔧 **How to enable**

Add the `boundingBox` field in the request body.
It requires **four coordinates** in decimal degrees (WGS84):

- `minLat` → minimum latitude
- `minLon` → minimum longitude
- `maxLat` → maximum latitude
- `maxLon` → maximum longitude



```
{
  "boundingBox": {
    "minLat": 48.80,
    "minLon": 2.25,
    "maxLat": 48.95,
    "maxLon": 2.45
  }
}
```

📦 **Example**


```
{
  "geoserver": "nominatim",
  "place": "Boulevard Sai",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "language": "fr",
  "boundingBox": {
    "minLat": 48.80,
    "minLon": 2.25,
    "maxLat": 48.95,
    "maxLon": 2.45
  },
  "maximumResults": 3
}
```

## 🌎 countryCode

✅ **Use case**

Restrict the autocomplete results to a **specific country**.
Useful when the same city or street name exists in multiple countries.

💡 **What it does**

The service will only return suggestions that match the given **ISO country code**.
Supported formats:

- **Alpha-2** (2 letters, e.g. `"FR"`, `"DE"`, `"US"`)
- **Alpha-3** (3 letters, e.g. `"FRA"`, `"DEU"`, `"USA"`)


🔧 **How to enable**

Add the `countryCode` field in the request body with the ISO code of the desired country.


```
{
  "countryCode": "FR"
}
```

📦 **Example**


```
{
  "geoserver": "nominatim",
  "place": "Boulevard Sai",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "language": "fr",
  "countryCode": "FR",
  "maximumResults": 3
}
```

## 🏷️ addressDetails

✅ **Use case**

Get the **postal address split into separate fields** (country, city, street, postal code, etc.) instead of a single formatted string.
Useful if your application needs to store or display structured address components.

💡 **What it does**

When enabled, the response includes a **detailed object** with fields like `country`, `city`, `street`, `postalCode`, etc.
By default, the service only returns a formatted address string.

🔧 **How to enable**

Add the `addressDetails` field in the request body and set it to `true`.
Default value: `false`.


```
{
  "addressDetails": true
}
```

📦 **Example**


```
{
  "geoserver": "nominatim",
  "place": "Boulevard Sai",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "language": "fr",
  "addressDetails": true,
  "maximumResults": 3
}
```

## 🗂️ enCategories

✅ **Use case**

Retrieve the **categories** (e.g. restaurant, hotel, park) associated with each autocomplete result.
Useful for filtering or displaying an icon/type alongside place suggestions.

💡 **What it does**

When enabled, the response contains a list of **category IDs**.
One category is marked as **primary** (`"primary": true`) to indicate the most relevant classification.

🔧 **How to enable**

Add the `enCategories` field in the request body and set it to `true`.
Default value: `false`.


```
{
  "enCategories": true
}
```

📦 **Example**


```
{
  "geoserver": "nominatim",
  "place": "Boulevard Sai",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "language": "fr",
  "enCategories": true,
  "maximumResults": 3
}
```

## 🏬 enChains

✅ **Use case**

Identify whether a place belongs to a **commercial chain** (e.g. McDonald’s, Carrefour, Starbucks).
Useful for apps that want to display a **chain-specific icon** or group results by brand.

💡 **What it does**

When enabled, the response includes **metadata about chains**.
This allows clients to recognize and visually highlight places that are part of a well-known chain.

🔧 **How to enable**

Add the `enChains` field in the request body and set it to `true`.
Default value: `false`.


```json
{
  "enChains": true
}
```

📦 **Example**


```
{
  "geoserver": "nominatim",
  "place": "Boulevard Sai",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "language": "fr",
  "enChains": true,
  "maximumResults": 3
}
```

**Response**


```

```

## 🚪 enEntrances

✅ **Use case**

Get the **precise entrances** of a place (e.g. the door of a shopping mall, a parking entry, or a building entrance).
Useful for navigation apps that need to guide users to the **correct access point** instead of just the building’s center.

💡 **What it does**

When enabled, the response contains a list of **geo-coordinates** representing entrances associated with the place.
This helps refine arrival instructions for pedestrians or drivers.

🔧 **How to enable**

Add the `enEntrances` field in the request body and set it to `true`.
Default value: `false`.


```
{
  "enEntrances": true
}
```

📦 **Example**


```
{
  "geoserver": "nominatim",
  "place": "Boulevard Sai",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "language": "fr",
  "enEntrances": true,
  "maximumResults": 3
}
```

## 🍴 enFoodTypes

✅ **Use case**

Retrieve the **type of cuisine** for restaurants or food-related places (e.g. Italian, Japanese, Fast food).
Useful for apps that want to **filter or display food categories** directly in search suggestions.

💡 **What it does**

When enabled, the response includes a list of **food-type IDs**.
One food type is marked as **primary** (`"primary": true`) to indicate the most relevant cuisine category.

🔧 **How to enable**

Add the `enFoodTypes` field in the request body and set it to `true`.
Default value: `false`.


```
{
  "enFoodTypes": true
}
```

📦 **Example**


```
{
  "geoserver": "nominatim",
  "place": "Boulevard Sai",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "language": "fr",
  "enFoodTypes": true,
  "maximumResults": 3
}
```

## ✨ enHighlights

✅ **Use case**
Highlight the **matching parts of the suggestion text** that correspond to the user’s query.
Useful for autocomplete UIs where you want to **bold or emphasize** the part of the result that matches the search.

💡 **What it does**
When enabled, the response includes **text slices** that explicitly show which characters matched the query.
This can be used to visually highlight relevant parts in your application.

🔧 **How to enable**
Add the `enHighlights` field in the request body and set it to `true`.
Default value: `false`.


```
{
  "enHighlights": true
}
```

📦 **Example**


```
{
  "geoserver": "nominatim",
  "place": "Boulevard Sai",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "language": "fr",
  "enHighlights": true,
  "maximumResults": 3
}
```

## 🆔 enLocId

✅ **Use case**

Retrieve the **unique Location ID** provided by the HERE HLP geoserver.
Useful if your application needs to **store, reuse, or request updates** for the exact same place later.

💡 **What it does**

When enabled, the response includes a **location identifier** (LocId) generated by HERE HLP.
This ID is persistent and can be used as a stable reference to the place.

🔧 **How to enable**

Add the `enLocId` field in the request body and set it to `true`.
Default value: `false`.
⚠️ Only applies when using the `herehlp` geoserver.


```
{
  "enLocId": true
}
```

📦 **Example**


```
{
  "geoserver": "herehlp",
  "place": "Boulevard Sai",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "language": "fr",
  "enLocId": true,
  "maximumResults": 3
}
```

## 🔗 enReferences

✅ **Use case**
Retrieve the **data source references** that contributed to a place result.
Useful if your application needs to display or log the **origin of the information** (e.g. OpenStreetMap, HERE, other providers).

💡 **What it does**
When enabled, the response includes a list of **reference IDs** from external data sources.
This metadata allows you to trace where the place information comes from.

🔧 **How to enable**
Add the `enReferences` field in the request body and set it to `true`.
Default value: `false`.


```
{
  "enReferences": true
}
```

📦 **Example**


```
{
  "geoserver": "nominatim",
  "place": "Boulevard Sai",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "language": "fr",
  "enReferences": true,
  "maximumResults": 3
}
```

## 🌍 geoserver

✅ **Use case**
Choose which **geocoding provider** to use for the autocomplete request.
Different providers may return different results in terms of coverage, accuracy, or available metadata.

💡 **What it does**
The service delegates the autocomplete query to the selected **geoserver backend**.
If not specified, a **default provider** is used.
Supported values:

- `"nominatim"`
- `"addok"`
- `"herehlp"`


🔧 **How to enable**
Add the `geoserver` field in the request body with one of the supported provider names.


```
{
  "geoserver": "nominatim"
}
```

📦 **Example**


```
{
  "geoserver": "nominatim",
  "place": "Boulevard Sai",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "language": "fr",
  "maximumResults": 3
}
```

## 📏 radius

✅ **Use case**

Restrict autocomplete suggestions to a **circular area around a point**, defined by its radius in meters.
Useful when searching for places **near a specific location** (e.g. POIs around the user’s position).

💡 **What it does**

The service limits the search results to those located **within the given distance** from the specified coordinate.
This helps focus results on nearby areas only.

🔧 **How to enable**

Add the `radius` field in the request body with a value in **meters** (type: `long`).
It must be used together with a `coordinate`.


```
{
  "radius": 1000
}
```

📦 **Example**


```
{
  "geoserver": "nominatim",
  "place": "Boulevard Sai",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "language": "fr",
  "radius": 1000,
  "maximumResults": 3
}
```