# Auto-complete

REST API, Service version 1.0.0

> API reference: [`POST /geocoding/autocomplete/1.0`](https://benomad.com/dev/doc/bemap-api/api/search/geocoding-autocomplete.md)

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

_For more details: [Wikipedia](https://en.wikipedia.org/wiki/Geocoding)_

## Summary
1. Request
 1. Mandatory parameters
 2. Optional parameters
2. Response
 1. Details of fields
 2. Response samples
 3. Error response

## Request
The request must be sent with the HTTP method `POST` and the HTTP header `Content-Type` set to `application/json`. 

Sample:
URI: `/bgis/service/geocoding/autocomplete/1.0`

POST data:
```javascript
{
  "geoserver": "nominatim",
  "coordinate": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "place": "Paris"
}
```

All coordinates are defined by longitude and latitude, see the [coordinate system](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md) glossary for more details.

### __Parameters__

> NOTE: the `geoserver` parameter must be defined to `nominatim`, `addok`, `herehlp`. Otherwise the default `geoserver` value will be used.

- `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

### Details of fields

- `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)

### Response samples

JSON Sample:
```javascript
{
	"items": [{
			"place": "PARIS | ILE-DE-FRANCE | FRANCE",
			"score": 0.7,
			"coordinate": {
				"longitude": 2.38305,
				"latitude": 48.902475
			}
		}
	]
}
```

### Error response
If an error occurs during the process on server side, only an error object will be returned in the response. See `Error example` chapter.
* `code`: error code. 
* `message`: error message. 
* `coordinate`: coordinate of error (optional). 
   * `lon`: longitude of coordinate in decimal degrees ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). 
   * `lat`: latitude of coordinate in decimal degrees ([WGS84](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md)). 

#### Error example
```javascript
{ 
   "error": { 
      "code": "ERROR_CODE", 
      "message": "Comment of error.", 
      "coordinate": { 
         "lon": 8.193691832353528, 
         "lat": 45.42630127240513 
      } 
   } 
}
```

All coordinates are defined by longitude and latitude, see the [coordinate system](https://benomad.com/dev/doc/bemap-api/guides/reference/glossary-coordinate-system.md) glossary for more details.