# Auto-complete

`POST https://bemap.benomad.com/bgis/service/geocoding/autocomplete/1.0`

Part of [Geocoding](https://benomad.com/dev/doc/bemap-api/search/geocoding.md).

> **Suggest addresses as the user types.** Address suggestions while the user is still typing, for a search box.

From a textual address perform a geographical research to suggest some textual postal address (free text).

Provisioned per account: without it, BeMap answers `400 Access Denied`.

## Request body

JSON, `Content-Type: application/json`. Schema `AutocompleteGeocodingRequest`.

- `place` (string, required): Textual postal address or POI name. Mandatory.
- `coordinate` (Coordinate, required): To define the center of research area. Most providers use the parameter as optional, but some others require it to work. You can try a request without it, if the server returns an error message about this required parameter, add it and retry the same request.
  - `lon` (number (double), required): Longitude in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). Also accepted as `longitude`.
  - `lat` (number (double), required): Latitude in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). Also accepted as `latitude`.
- `geoserver` (string): Geoserver name.
- `swidx` (integer (int32), deprecated): Switch index.
- `language` (string): Define the language that will be used to perform the address lookup. Objects for which defined language code is not available, default language will be used. Values language Code - An US-ASCII string that defines an ISO 639-1 (2-letter) language code. The specials 'IC' (no sensitive case) language code allows you to search for a country  depending on its ISO-3166 Alpha-3 or Alpha-2 country code.
- `boundingbox` (BoundingBox): Define a bounding box to limit the auto-complete search area.
  - `minLon` (number (double)): Minimum longitude, in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)).
  - `minLat` (number (double)): Minimum latitude, in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)).
  - `maxLon` (number (double)): Maximum longitude, in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)).
  - `maxLat` (number (double)): Maximum latitude, in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)).
- `radius` (integer (int64)): Define the radius of research in meters.
- `countryCode` (string): Optional filtering research on country code.
- `addressDetails` (boolean): Set to true to receive the proposed postal addresses in separate fields (country, city, street, etc). false by default.
- `enLocId` (boolean): Used by HERE HLP geo-server; if set to true the Location ID will be returned.
- `enEntrances` (boolean): Enable the generation list of geo-coordinate of the access to the result (for instance the entrance).
- `enHighlights` (boolean): Enable the generation of text slices matching the query. These slices can be used to highlight the related matching fields.
- `enCategories` (boolean): Enable the generation list of category ids. The primary category has its flag primary set to true.
- `enFoodTypes` (boolean): Enable the generation list of food-type ids if available The primary category has its flag primary set to true.
- `enChains` (boolean): Enable place chains metadata to allow customers to choose a chain icon.
- `enReferences` (boolean): Enable the data source ids, when the place result has a contribution from specific suppliers.

## Response

`200`, schema `AutocompleteGeocodingResponse`.

- `items` (AutocompleteElem[]): List of proposal items.
  - `elemType` (string, required): Type of element result. Auto-complete is able to return items of several types: categoryQuery, chainQuery, place, locality, etc.
  - `place` (string, required): Proposed place.
  - `coordinate` (CoordinateFullName, required): Coordinate of proposed place.
    - `longitude` (number (double), required): Longitude in degrees decimal (WGS84) (double).
    - `latitude` (number (double), required): Latitude in degrees decimal (WGS84) (double).
    - `altitude` (number (double)): Altitude in meters.
  - `addressLabel` (string): The full address in one text string of the entity result item.
  - `address` (Address): Complete postal address of proposed place.
    - `countryCode` (string): ISO code of country.
    - `country` (string): Country name.
    - `state` (string): State name.
    - `county` (string): County name.
    - `city` (string): City name.
    - `district` (string): District name of city.
    - `postalCode` (string): Postal code.
    - `roadNumber` (string): Road number.
    - `street` (string): Street name.
    - `streetNumber` (string): House number.
    - `oppositeStreetNumber` (string, deprecated): Opposite street number.
  - `countryCode` (string): Country Code.
  - `entrances` (Coordinate[]): List of coordinate of the access to the result (for instance the entrance).
    - `lon` (number (double), required): Longitude in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). Also accepted as `longitude`.
    - `lat` (number (double), required): Latitude in degrees decimal ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). Also accepted as `latitude`.
  - `distance` (integer (int32)): The distance in a straight line in meters from the position specified in the query `coordinate` parameter.
  - `locationId` (string): Location Id.
  - `language` (string): Language.
  - `score` (number (double)): Score.
  - `placeHighlight` (AutocompleteElemHighlight[]): The text slices matching the query. These slices can be used to highlight the related matching place field.
    - `start` (integer (int32))
    - `end` (integer (int32))
  - `addressLabelHighlight` (AutocompleteElemHighlight[]): The text slices matching the query. These slices can be used to highlight the related matching address label field.
    - `start` (integer (int32))
    - `end` (integer (int32))
  - `categories` (AutocompleteElemReference[]): A list of category ids. The primary category has its flag primary set to true.
    - `supplierId` (string)
    - `id` (string)
    - `name` (string)
    - `primary` (boolean)
  - `foodTypes` (AutocompleteElemReference[]): A list of food-type ids if available The primary category has its flag primary set to true.
    - `supplierId` (string)
    - `id` (string)
    - `name` (string)
    - `primary` (boolean)
  - `chains` (AutocompleteElemReference[]): Place chains metadata to allow customers to choose a chain icon.
    - `supplierId` (string)
    - `id` (string)
    - `name` (string)
    - `primary` (boolean)
  - `references` (AutocompleteElemReference[]): Data source ids, when the place result has a contribution from specific suppliers:
    - `supplierId` (string)
    - `id` (string)
    - `name` (string)
    - `primary` (boolean)

## Errors

- `400`: Bad Request
- `302`: no credentials were sent. Do not follow the redirect.
- `401`: the account or the API key is wrong.

How to read each one: [Errors](https://benomad.com/dev/doc/bemap-api/getting-started/errors.md).

## Example

```bash
curl -X POST 'https://bemap.benomad.com/bgis/service/geocoding/autocomplete/1.0' \
  -u 'YOUR_ACCOUNT:YOUR_API_KEY' \
  --fail-with-body \
  -H 'Content-Type: application/json' \
  -d '{
  "place": "Tour Eif",
  "coordinate": {
    "lat": 48.8584,
    "lon": 2.2945
  },
  "geoserver": "herehlp",
  "language": "fr"
}'
```

Response captured from production, long arrays and strings shortened:

```json
{
  "items": [
    {
      "elemType": "place",
      "place": "La Tour Eiffel",
      "addressLabel": "La Tour Eiffel, 5 Avenue Anatole France, 75007 Paris, France",
      "coordinate": {
        "longitude": 2.2945,
        "latitude": 48.85824
      },
      "distance": 18
    },
    {
      "elemType": "place",
      "place": "RER-Champs de Mars-Tour Eiffel",
      "addressLabel": "RER-Champs de Mars-Tour Eiffel, Quai Jacques Chirac, 75015 Paris, France",
      "coordinate": {
        "longitude": 2.29066,
        "latitude": 48.85745
      },
      "distance": 300
    }
  ]
}
```

## Tutorials

- [Autocomplete Geocoding API: Parameters Overview](https://benomad.com/dev/doc/bemap-api/guides/tutorials/autocompletegeocoding-parameters.md)
- [Tutorial for the first trip in electrical vehicle · 1.0](https://benomad.com/dev/doc/bemap-api/guides/tutorials/evtrip-first-trip-v1-0.md)
- [Tutorial for the first trip in electrical vehicle · 2.0](https://benomad.com/dev/doc/bemap-api/guides/tutorials/evtrip-first-trip-v2-0.md)

## Reference pages

- [Auto-complete](https://benomad.com/dev/doc/bemap-api/guides/services/autocompletegeocoding.md)