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.
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.language
Language code (ISO 639-1, 2 letters) used for suggestions.
Special value:"IC"→ case-insensitive country code search.
👉 Must always be provided.
boundingBox
Restrict the autocomplete search to a rectangular area in WGS84 coordinates.
Type: 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
Iftrue, 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 toherehlp: returns Location ID iftrue.enReferences
Returns supplier-specific source IDs when available.
{
"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
}✅ 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
}✅ 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
}✅ 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
}✅ 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 latitudeminLon→ minimum longitudemaxLat→ maximum latitudemaxLon→ 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
}✅ 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
}✅ 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
}✅ 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
}✅ 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.
{
"enChains": true
}📦 Example
{
"geoserver": "nominatim",
"place": "Boulevard Sai",
"coordinate": {
"lat": 48.8566,
"lon": 2.3522
},
"language": "fr",
"enChains": true,
"maximumResults": 3
}Response
✅ 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
}✅ 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
}✅ 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
}✅ 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
}✅ 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
}✅ 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
}✅ 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
}