# ✨ Autocomplete Geocoding API

The **Autocomplete Geocoding** service suggests **postal addresses** or **places** based on a partial textual input (free text).
It helps users type faster by offering relevant **auto-complete suggestions**.

ℹ️ For more details, see [Wikipedia](https://en.wikipedia.org/wiki/Address).

## 🔗 Endpoint

**POST** `/bgis/service/geocoding/autocomplete/1.0`
**Content-Type:** `application/json`

## 📦 Sample Request Body


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

📍 All coordinates are defined in **WGS84** (longitude, latitude). See the coordinate system glossary
for more details.

## 🔧 Parameters

⚠️ The `geoserver` parameter must be one of: `nominatim`, `addok`, `herehlp`.
If not provided, the default geoserver will be used.

| **Field** | **Optional** | **Description** |
|  --- | --- | --- |
| `place` | **No** | Textual postal address or POI name to autocomplete. Type: `string`. |
| `coordinate` | Yes | Center of the search area. Some providers require this parameter. Type: [Coordinate](#coordinate). |
| `language` | Yes | Defines the language of the lookup (ISO 639-1 code). `"IC"` allows case-insensitive search by ISO country codes. Type: `string`. |
| `addressDetails` | Yes | If `true`, returns proposed addresses split into fields (country, city, street, etc.). Default: `false`. Type: `boolean`. |
| `boundingBox` | Yes | Restrict the autocomplete search to a defined rectangle. Type: [BoundingBox](#boundingbox). |
| `countryCode` | Yes | Restrict results to a specific country code. Type: `string`. |
| `enCategories` | Yes | Return a list of category IDs (with primary flagged). Type: `boolean`. |
| `enChains` | Yes | Return metadata about place chains (e.g., franchises). Type: `boolean`. |
| `enEntrances` | Yes | Return geo-coordinates of entrances when available. Type: `boolean`. |
| `enFoodTypes` | Yes | Return available food-type IDs (with primary flagged). Type: `boolean`. |
| `enHighlights` | Yes | Return text slices matching the query, useful for highlighting results. Type: `boolean`. |
| `enLocId` | Yes | Specific to `herehlp`: return Location ID if `true`. Type: `boolean`. |
| `enReferences` | Yes | Return supplier-specific data source IDs when available. Type: `boolean`. |
| `geoserver` | Yes | Geoserver name. Supported values:  - `nominatim` → OpenStreetMap-based search  - `addok` → French **Base Adresse Nationale (BAN)**  - `herehlp` → HERE Hybrid Location Platform.  Type: `string`. |
| `radius` | Yes | Search radius in meters. Type: `long`. |


## 📐 BoundingBox

| **Field** | **Optional** | **Description** |
|  --- | --- | --- |
| `maxLat` | No | Maximum latitude (WGS84, decimal degrees). Type: `double`. |
| `maxLon` | No | Maximum longitude (WGS84, decimal degrees). Type: `double`. |
| `minLat` | No | Minimum latitude (WGS84, decimal degrees). Type: `double`. |
| `minLon` | No | Minimum longitude (WGS84, decimal degrees). Type: `double`. |


## 📍 Coordinate

| **Field** | **Optional** | **Description** |
|  --- | --- | --- |
| `lat` | No | Latitude (WGS84, decimal degrees). Type: `double`. |
| `lon` | No | Longitude (WGS84, decimal degrees). Type: `double`. |


## 📤 Sample Response


```
{
  "results": [
    {
      "address": {
        "country": "France",
        "city": "Paris",
        "street": "Boulevard de Sébastopol"
      },
      "highlight": "Boulevard de Sébastopol, Paris",
      "location": {
        "lon": 2.3522,
        "lat": 48.859
      }
    },
    {
      "address": {
        "country": "France",
        "city": "Paris",
        "street": "Boulevard Saint-Germain"
      },
      "highlight": "Boulevard Saint-Germain, Paris",
      "location": {
        "lon": 2.3505,
        "lat": 48.853
      }
    }
  ]
}
```