# 📖 Geocoding API – Parameters Overview

The Geocoding API accepts several parameters that control how the address lookup is performed and how results are returned.
They fall into two categories: **mandatory** (at least one must be present) and **optional**.

## ✅ Mandatory

- **`address`**
Defines the postal address to geocode. It can contain fields such as `country`, `city`, `street`, `postalCode`, etc.
👉 At least `country` or `countryCode`, or alternatively a `boundingBox`, must be provided.
- **`boundingBox`**
Defines a rectangular area (in WGS84 coordinates) that restricts the search. Useful when the same address exists in multiple regions.


## ⚙️ Optional

- **`assetSearchType`**
Defines the type of object to search for. Possible values: `CITY_CENTER`, `OBJECT`, `POI`, `ROAD`.
- **`geoserver`**
Name of the geoserver to use. Example: `here`, `osm`.
- **`language`**
Language code (ISO 639-1, 2 letters) for the address lookup.
Special value: `"IC"` → case-insensitive search by country code (ISO-3166 Alpha-2 or Alpha-3).
- **`maximumResults`**
Maximum number of results returned by the server. Type: `int`.
- **`searchType`**
Controls how the input string is matched. Possible values:
  - `CONTAINS` → pattern must be contained in the results.
  - `FUZZY` → fuzzy matching (typos tolerated).
  - `KEY_SEARCH` → search by unique identifiers.
  - `STRICT` → exact match only.
  - `STRICT_BEGINNING` → result must start with the pattern.
  - `WORD_BEGINNING` → one word must begin with the pattern.


## 📦 Example (overview)


```
{
  "geoserver": "osm",
  "address": {
    "country": "France",
    "city": "Paris",
    "street": "villa des pyrénées"
  },
  "boundingBox": {
    "minLat": 48.80,
    "minLon": 2.25,
    "maxLat": 48.90,
    "maxLon": 2.45
  },
  "assetSearchType": "POI",
  "searchType": "FUZZY",
  "maximumResults": 3,
  "language": "fr"
}
```

➡️ This request searches for “Villa des Pyrénées, Paris” within the specified bounding box, returning up to 3 results in French, using fuzzy matching.

## 📐 BoundingBox

✅ **Use case**
Limit the geocoding search to a **specific area** (e.g. a city or trip corridor), to avoid irrelevant results from other regions.

💡 **What it does**
The service only returns addresses **inside the defined rectangle** (WGS84 coordinates).

🔧 **How to enable**
Add the `boundingBox` field in the request body with 4 coordinates: `maxLat`, `maxLon`, `minLat`, `minLon`.

📦 **Example**


```
{
  "geoserver": "osm",
  "address": {
    "city": "Paris",
    "street": "rue de la paix"
  },
  "boundingBox": {
    "maxLat": 48.95,
    "maxLon": 2.50,
    "minLat": 48.80,
    "minLon": 2.25
  },
  "language": "fr",
  "maximumResult": 3
}
```

📤 **Response**


```
{
  "extent": {
    "minLon": 2.33029,
    "minLat": 48.86834,
    "maxLon": 2.33227,
    "maxLat": 48.87025
  },
  "elements": [
    {
      "boundingBox": {
        "minLon": 2.33029,
        "minLat": 48.86834,
        "maxLon": 2.33227,
        "maxLat": 48.87025
      },
      "coordinate": {
        "lon": 2.33045,
        "lat": 48.8685
      },
      "distanceFromRequest": 0,
      "postalAddress": {
        "countryCode": "FRA",
        "country": "France",
        "state": "Île-de-France",
        "county": "Paris",
        "city": "Paris",
        "district": "Paris 2e Arrondissement",
        "postalCode": "75002",
        "street": "Rue de la Paix"
      },
      "postalAddressClassType": "ROAD_TERTIARY",
      "postalAddressClassId": 4304,
      "postalAddressExactStreeNumber": false,
      "angle": -147,
      "administrativeSpeedLimit": 0,
      "relevanceScore": 1,
      "countryRelevanceScore": 1,
      "cityRelevanceScore": 0.75,
      "postalCodeRelevanceScore": 1,
      "streetRelevanceScore": 1,
      "streetNumberRelevanceScore": 0,
      "segmentId": 0
    }
  ],
  "maximunResult": 1
}
```

## 🏠 Address

✅ **Use case**
Provide a **postal address** (country, city, street, etc.) that you want to convert into geographical coordinates.

💡 **What it does**
The service parses the given address fields and returns one or more **matching locations** with longitude/latitude coordinates.

🔧 **How to enable**
Include the `address` object in the request body.
You can specify any combination of fields: `country`, `countryCode`, `city`, `district`, `postalCode`, `street`, `streetNumber`, etc.

📦 **Example**


```
{
  "geoserver": "osm",
  "address": {
    "country": "France",
    "city": "Paris",
    "street": "Rue de Rivoli",
    "streetNumber": "99"
  },
  "language": "fr",
  "maximumResult": 1
}
```

**Response**


```
{
  "extent": {
    "minLon": 2.32341,
    "minLat": 48.85852,
    "maxLon": 2.3482,
    "maxLat": 48.86637
  },
  "elements": [
    {
      "boundingBox": {
        "minLon": 2.32341,
        "minLat": 48.85852,
        "maxLon": 2.3482,
        "maxLat": 48.86637
      },
      "coordinate": {
        "lon": 2.33491,
        "lat": 48.86284
      },
      "exactCoordinate": {
        "lon": 2.33482,
        "lat": 48.86273
      },
      "distanceFromRequest": 0,
      "postalAddress": {
        "countryCode": "FRA",
        "country": "France",
        "state": "Île-de-France",
        "county": "Paris",
        "city": "Paris",
        "district": "Paris 1er Arrondissement",
        "postalCode": "75001",
        "street": "Rue de Rivoli",
        "streetNumber": "99"
      },
      "postalAddressClassType": "ROAD_TERTIARY",
      "postalAddressClassId": 4304,
      "postalAddressExactStreeNumber": true,
      "angle": 117,
      "administrativeSpeedLimit": 0,
      "relevanceScore": 1,
      "countryRelevanceScore": 1,
      "cityRelevanceScore": 0.75,
      "postalCodeRelevanceScore": 1,
      "streetRelevanceScore": 1,
      "streetNumberRelevanceScore": 1,
      "segmentId": 0
    }
  ],
  "maximunResult": 1
}
```

## 🌐 Language

✅ **Use case**
Control the **language** used for address lookup and returned results (street names, city names, etc.).

💡 **What it does**
If the requested language is available, the response will return the address in that language.
If not, the **default language** of the geoserver will be used.
Special value `"IC"` allows case-insensitive search by ISO country codes.

🔧 **How to enable**
Add the `language` field in the request body with an **ISO 639-1** 2-letter code (e.g. `fr`, `en`, `de`).

📦 **Example**


```
{
  "geoserver": "osm",
  "address": {
    "country": "Germany",
    "city": "Munich",
    "street": "Marienplatz"
  },
  "language": "de",
  "maximumResult": 1
}
```

**Response**


```
{
  "extent": {
    "minLon": -73.26347,
    "minLat": 59.77727,
    "maxLon": -11.31233,
    "maxLat": 83.62743
  },
  "elements": [
    {
      "boundingBox": {
        "minLon": -73.26347,
        "minLat": 59.77727,
        "maxLon": -11.31233,
        "maxLat": 83.62743
      },
      "coordinate": {
        "lon": -42.2879,
        "lat": 71.70235
      },
      "distanceFromRequest": 0,
      "postalAddress": {
        "countryCode": "GRL",
        "country": "Greenland"
      },
      "postalAddressClassType": "COUNTRY",
      "postalAddressClassId": 1111,
      "postalAddressExactStreeNumber": false,
      "angle": 0,
      "administrativeSpeedLimit": 0,
      "relevanceScore": 0.6,
      "countryRelevanceScore": 0.6,
      "cityRelevanceScore": 1,
      "postalCodeRelevanceScore": 1,
      "streetRelevanceScore": 1,
      "streetNumberRelevanceScore": 0,
      "segmentId": 0
    }
  ],
  "maximunResult": 1
}
```

## 🔍 searchType

✅ **Use case**
Control the **matching strategy** used when searching for addresses. Useful to handle typos, partial inputs, or strict searches.

💡 **What it does**
Determines how the service compares the input text with stored addresses:

- `CONTAINS` → match if the input is contained in the address.
- `FUZZY` → allows typos or misspellings (fuzzy search).
- `KEY_SEARCH` → search by key identifiers (IDs).
- `STRICT` → exact match only.
- `STRICT_BEGINNING` → match must start with the input string.
- `WORD_BEGINNING` → match if one word begins with the input (separators: space, `-`, `/`).


🔧 **How to enable**
Add the `searchType` field in the request body with one of the supported values.

📦 **Example**


```
{
  "geoserver": "osm",
  "address": {
    "country": "France",
    "city": "Paris",
    "street": "villa des pyrenes"
  },
  "searchType": "FUZZY",
  "maximumResult": 2,
  "language": "fr"
}
```

**Response**


```
{
  "extent": {
    "minLon": 2.40518,
    "minLat": 48.8533,
    "maxLon": 2.40587,
    "maxLat": 48.85351
  },
  "elements": [
    {
      "boundingBox": {
        "minLon": 2.40518,
        "minLat": 48.8533,
        "maxLon": 2.40587,
        "maxLat": 48.85351
      },
      "coordinate": {
        "lon": 2.40552,
        "lat": 48.85342
      },
      "distanceFromRequest": 0,
      "postalAddress": {
        "countryCode": "FRA",
        "country": "France",
        "state": "Île-de-France",
        "county": "Paris",
        "city": "Paris",
        "district": "Paris 20e Arrondissement",
        "postalCode": "75020",
        "street": "Villa des Pyrénées"
      },
      "postalAddressClassType": "ROAD_FOURTH",
      "postalAddressClassId": 4048,
      "postalAddressExactStreeNumber": false,
      "angle": 62,
      "administrativeSpeedLimit": 0,
      "relevanceScore": 0.96,
      "countryRelevanceScore": 1,
      "cityRelevanceScore": 0.75,
      "postalCodeRelevanceScore": 1,
      "streetRelevanceScore": 0.96,
      "streetNumberRelevanceScore": 0,
      "segmentId": 0
    },
    {
      "coordinate": {
        "lon": 2.33936,
        "lat": 48.85113
      },
      "exactCoordinate": {
        "lon": 2.33939,
        "lat": 48.85114
      },
      "distanceFromRequest": 2.46,
      "postalAddress": {
        "countryCode": "FRA",
        "country": "France",
        "state": "Île-de-France",
        "county": "Paris",
        "city": "Paris",
        "district": "Paris 6e Arrondissement",
        "postalCode": "75006",
        "roadNumber": "",
        "street": "Villa des Princes, Rue Monsieur le Prince",
        "streetNumber": "19",
        "oppositeStreetNumber": "10"
      },
      "postalAddressClassType": "HOTEL_MOTEL",
      "postalAddressClassId": 7314,
      "postalAddressExactStreeNumber": false,
      "angle": -27,
      "administrativeSpeedLimit": 30,
      "relevanceScore": 0.87,
      "countryRelevanceScore": 1,
      "cityRelevanceScore": 0.75,
      "postalCodeRelevanceScore": 1,
      "streetRelevanceScore": 0.87,
      "streetNumberRelevanceScore": 0,
      "geoElementTypes": [
        "ROAD",
        "FOURTH_ROAD",
        "DISTRICT",
        "CITY",
        "COUNTY",
        "STATE",
        "COUNTRY"
      ],
      "segmentId": 0
    }
  ],
  "maximunResult": 2
}
```

## 🔢 maximumResults

✅ **Use case**
Limit the **number of results** returned by the geocoding request.

💡 **What it does**
The service will return **at most N addresses** matching the search.
This helps avoid long responses and keeps only the most relevant results.

🔧 **How to enable**
Add the `maximumResults` field in the request body with an integer value.

📦 **Example**


```
{
  "geoserver": "osm",
  "address": {
    "country": "France",
    "city": "Paris",
    "street": "Rue de Rivoli"
  },
  "maximumResults": 3,
  "language": "fr"
}
```

**Response**


```
{
  "extent": {
    "minLon": 2.32341,
    "minLat": 48.85504,
    "maxLon": 2.36171,
    "maxLat": 48.86637
  },
  "elements": [
    {
      "boundingBox": {
        "minLon": 2.32341,
        "minLat": 48.85852,
        "maxLon": 2.3482,
        "maxLat": 48.86637
      },
      "coordinate": {
        "lon": 2.3482,
        "lat": 48.85852
      },
      "distanceFromRequest": 0,
      "postalAddress": {
        "countryCode": "FRA",
        "country": "France",
        "state": "Île-de-France",
        "county": "Paris",
        "city": "Paris",
        "district": "Paris 1er Arrondissement",
        "postalCode": "75001",
        "street": "Rue de Rivoli"
      },
      "postalAddressClassType": "ROAD_TERTIARY",
      "postalAddressClassId": 4304,
      "postalAddressExactStreeNumber": false,
      "angle": 117,
      "administrativeSpeedLimit": 0,
      "relevanceScore": 1,
      "countryRelevanceScore": 1,
      "cityRelevanceScore": 0.75,
      "postalCodeRelevanceScore": 1,
      "streetRelevanceScore": 1,
      "streetNumberRelevanceScore": 0,
      "segmentId": 0
    },
    {
      "boundingBox": {
        "minLon": 2.3482,
        "minLat": 48.85504,
        "maxLon": 2.36171,
        "maxLat": 48.85852
      },
      "coordinate": {
        "lon": 2.35931,
        "lat": 48.85562
      },
      "distanceFromRequest": 0,
      "postalAddress": {
        "countryCode": "FRA",
        "country": "France",
        "state": "Île-de-France",
        "county": "Paris",
        "city": "Paris",
        "district": "Paris 4e Arrondissement",
        "postalCode": "75004",
        "street": "Rue de Rivoli"
      },
      "postalAddressClassType": "ROAD_FOURTH",
      "postalAddressClassId": 4048,
      "postalAddressExactStreeNumber": false,
      "angle": 110,
      "administrativeSpeedLimit": 0,
      "relevanceScore": 1,
      "countryRelevanceScore": 1,
      "cityRelevanceScore": 0.75,
      "postalCodeRelevanceScore": 1,
      "streetRelevanceScore": 1,
      "streetNumberRelevanceScore": 0,
      "segmentId": 0
    }
  ],
  "maximunResult": 2
}
```

## 🏷️ assetSearchType

✅ **Use case**
Refine the geocoding search to target a **specific type of asset** (e.g. city center, road, POI).

💡 **What it does**
The service adjusts the results depending on the selected asset type:

- `CITY_CENTER` → returns the central point of a city.
- `OBJECT` → returns generic objects (buildings, addresses).
- `POI` → returns points of interest (restaurants, landmarks, etc.).
- `ROAD` → returns road segments or streets.


🔧 **How to enable**
Add the `assetSearchType` field in the request body with one of the available values.

📦 **Example**


```
{
  "geoserver": "osm",
  "address": {
    "country": "France",
    "city": "Nice"
  },
  "assetSearchType": "CITY_CENTER",
  "maximumResults": 1,
  "language": "fr"
}
```

**Response**


```
{
  "extent": {
    "minLon": 7.18193,
    "minLat": 43.64566,
    "maxLon": 7.32309,
    "maxLat": 43.76084
  },
  "elements": [
    {
      "boundingBox": {
        "minLon": 7.18193,
        "minLat": 43.64566,
        "maxLon": 7.32309,
        "maxLat": 43.76084
      },
      "coordinate": {
        "lon": 7.27768,
        "lat": 43.70032
      },
      "distanceFromRequest": 0,
      "postalAddress": {
        "countryCode": "FRA",
        "country": "France",
        "state": "Provence-Alpes-Côte d'Azur",
        "county": "Alpes-Maritimes",
        "city": "Nice"
      },
      "postalAddressClassType": "ORDRE_8_AREA",
      "postalAddressClassId": 1119,
      "postalAddressExactStreeNumber": false,
      "angle": 0,
      "administrativeSpeedLimit": 0,
      "relevanceScore": 1,
      "countryRelevanceScore": 1,
      "cityRelevanceScore": 1,
      "postalCodeRelevanceScore": 1,
      "streetRelevanceScore": 1,
      "streetNumberRelevanceScore": 0,
      "segmentId": 0
    }
  ],
  "maximunResult": 1
}
```

## 🌍 geoserver

✅ **Use case**
Select the **geographical database** (geoserver) to be used for the geocoding request.

💡 **What it does**
The service queries the chosen geoserver (e.g. `here`, `osm`) to return coordinates for the provided address.
Different geoservers may give **different results** depending on their coverage and data quality.

🔧 **How to enable**
Add the `geoserver` field in the request body with the desired geoserver name as a string.

📦 **Example**


```
{
  "geoserver": "osm",
  "address": {
    "country": "Italy",
    "city": "Rome",
    "street": "Via del Corso"
  },
  "geoserver": "osm",
  "maximumResults": 1,
  "language": "en"
}
```

**Response**


```
{
  "extent": {
    "minLon": 12.47651,
    "minLat": 41.89668,
    "maxLon": 12.48222,
    "maxLat": 41.91031
  },
  "elements": [
    {
      "boundingBox": {
        "minLon": 12.47651,
        "minLat": 41.89668,
        "maxLon": 12.48222,
        "maxLat": 41.91031
      },
      "coordinate": {
        "lon": 12.47675,
        "lat": 41.90975
      },
      "distanceFromRequest": 0,
      "postalAddress": {
        "countryCode": "ITA",
        "country": "Italy",
        "state": "Lazio",
        "county": "Roma",
        "city": "Rome",
        "district": "Municipio Roma I",
        "street": "Via del Corso"
      },
      "postalAddressClassType": "ROAD_FOURTH_PEDESTRIAN",
      "postalAddressClassId": 4000,
      "postalAddressExactStreeNumber": false,
      "angle": 0,
      "administrativeSpeedLimit": 0,
      "relevanceScore": 1,
      "countryRelevanceScore": 1,
      "cityRelevanceScore": 0.4,
      "postalCodeRelevanceScore": 1,
      "streetRelevanceScore": 1,
      "streetNumberRelevanceScore": 0,
      "segmentId": 0
    }
  ],
  "maximunResult": 1
}
```