# 🌍 Reverse Geocoding API

The **Reverse Geocoding** service converts **GPS coordinates** (latitude, longitude) into a **human-readable address** or **place name**.
It can identify **street addresses**, **places**, and **administrative subdivisions** such as neighborhoods, counties, states, or countries.

Reverse geocoding is essential for **location-based services**, making raw GPS data more understandable to end users.

## 🔗 Endpoint

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

## 📦 Sample Request Body


```
{
  "geoserver": "osm",
  "transportMode": "CAR",
  "maximumResults": 5,
  "coordinateSat": {
    "lon": 2.3412,
    "lat": 48.85693
  },
  "radius": "1000",
  "language": "on"
}
```

## 🔧 Parameters

| **Field** | **Optional** | **Description** |
|  --- | --- | --- |
| `coordinateSat` | **No** | GPS coordinates of the request. Type: `CoordinateSat](#coordinatesat)`. |
| `radius` | **No** | Maximum search radius around the given GPS point, in **meters**. Type: `long` |
| `geoserver` | Yes | Name of the geoserver to use. Type: `string` |
| `language` | Yes | Defines the **language** used to perform the address lookup. If the specified language is not available, the **default language** will be used.  The value must be an **ISO 639-1** 2-letter code.  Special value: `"IC"` → case-insensitive search based on **ISO-3166 Alpha-2** or **Alpha-3** country codes.  Type: `string`. |
| `maximumResults` | Yes | Maximum number of items used to perform the search and returned by the server. Type: `int`. |
| `options` | Yes | Comma-separated list of one or more **reverse geocoding options**. See details below. |
| `swidx` | Yes | Switch index used internally by the server. Type: `int`. |
| `transportMode` | Yes | Transport mode used for the request. Type: `string`. See [Available transport modes](#available-transport-modes). |


### 📌 Available `options` values

| **Option** | **Description** |
|  --- | --- |
| `OPPOSITE_POSTAL_ADDRESS` | Return the **opposite postal address** only if it differs from the main postal address. |
| `OPPOSITE_POSTAL_ADDRESS_ALWAYS` | Always return the opposite postal address, even if it's the same as the main postal address. |
| `POLYLINE` | Return the list of **coordinates** forming the road segment. |
| `ROAD_FEATURE` | Return detailed **network information** for the road segment. |
| `SEGMENTID` | Return the **segment ID** (similar to a **link ID**). |
| `SKIP_EMPTY_STREETNAME` | Skip results **without a street name** if other elements have one. |
| `START_AT_RADIUS` | Force the search to **start directly** at the specified **radius**. |
| `TRAFFIC` | Include **real-time traffic information**. |
| `TRAFFIC_HISTORICAL` *(Beta)* | Include **historical traffic information**. Uses timestamps defined in coordinates. |
| `TRAFFIC_PREDICTIVE` | Include **predictive traffic information**. Uses timestamps defined in coordinates. |
| `URBAN_AREA` | Indicate whether the resulting matched point is inside an **urban area**. |


### 🚗 Available transport modes

| **Value** | **Description** |
|  --- | --- |
| `BICYCLE` | Bicycle routing. |
| `CAR` | Passenger car (default). |
| `EMERGENCY` | Emergency vehicle. |
| `MOTORCYCLE` | Motorcycle routing. |
| `PEDESTRIAN` | Pedestrian routing. |
| `PUBLIC_BUS` | Public bus routing. |
| `TAXI` | Taxi routing. |
| `TRUCK` | Standard truck routing. |


### 🗺️ CoordinateSat

Defines the GPS coordinates used in the request.

| **Field** | **Optional** | **Description** |
|  --- | --- | --- |
| `lat` | **No** | Latitude in **decimal degrees** (WGS84). Type: `double`. |
| `lon` | **No** | Longitude in **decimal degrees** (WGS84). Type: `double`. |
| `heading` | Yes | Heading angle in **degrees**. Type: `double`. |
| `sat` | Yes | Number of **GPS satellites** available. Type: `integer`. |
| `speed` | Yes | Speed in **km/h**. Type: `float`. |
| `time` | Yes | GPS **timestamp** in **milliseconds** (EPOCH). Type: `long` |


## 📤 Sample Response


```
{
  "extent": {
    "minLon": 2.34117,
    "minLat": 48.85686,
    "maxLon": 2.3413,
    "maxLat": 48.85696
  },
  "elements": [
    {
      "coordinate": {
        "lon": 2.34121,
        "lat": 48.85694
      },
      "distanceFromRequest": 1.33,
      "postalAddress": {
        "countryCode": "FRA",
        "country": "France",
        "state": "Île-de-France",
        "county": "Paris",
        "city": "Paris",
        "district": "Paris 1er Arrondissement",
        "postalCode": "75001",
        "roadNumber": "",
        "street": "Quai des Orfèvres"
      },
      "postalAddressClassType": "ROAD_FOURTH",
      "postalAddressClassId": 4048,
      "postalAddressExactStreeNumber": false,
      "angle": 149,
      "administrativeSpeedLimit": 30,
      "relevanceScore": 0.05327986839399546,
      "countryRelevanceScore": 0,
      "cityRelevanceScore": 0,
      "postalCodeRelevanceScore": 0,
      "streetRelevanceScore": 0,
      "streetNumberRelevanceScore": 0,
      "geoElementTypes": [
        "ROAD",
        "FOURTH_ROAD",
        "DISTRICT",
        "CITY",
        "COUNTY",
        "STATE",
        "COUNTRY"
      ],
      "segmentId": 0
    },
    {
      "coordinate": {
        "lon": 2.34117,
        "lat": 48.85694
      },
      "distanceFromRequest": 2.46,
      "postalAddress": {
        "countryCode": "FRA",
        "country": "France",
        "state": "Île-de-France",
        "county": "Paris",
        "city": "Paris",
        "district": "Paris 1er Arrondissement",
        "postalCode": "75000",
        "roadNumber": "",
        "street": "Place du Pont Neuf"
      },
      "postalAddressClassType": "ROAD_FOURTH",
      "postalAddressClassId": 4048,
      "postalAddressExactStreeNumber": false,
      "angle": -147,
      "administrativeSpeedLimit": 30,
      "relevanceScore": 0.05319761464116799,
      "countryRelevanceScore": 0,
      "cityRelevanceScore": 0,
      "postalCodeRelevanceScore": 0,
      "streetRelevanceScore": 0,
      "streetNumberRelevanceScore": 0,
      "geoElementTypes": [
        "ROAD",
        "FOURTH_ROAD",
        "DISTRICT",
        "CITY",
        "COUNTY",
        "STATE",
        "COUNTRY"
      ],
      "segmentId": 0
    },
    {
      "coordinate": {
        "lon": 2.34119,
        "lat": 48.85696
      },
      "distanceFromRequest": 3.42,
      "postalAddress": {
        "countryCode": "FRA",
        "country": "France",
        "state": "Île-de-France",
        "county": "Paris",
        "city": "Paris",
        "district": "Paris 1er Arrondissement",
        "postalCode": "75000",
        "roadNumber": "",
        "street": "Place du Pont Neuf"
      },
      "postalAddressClassType": "ROAD_FOURTH",
      "postalAddressClassId": 4048,
      "postalAddressExactStreeNumber": false,
      "angle": -148,
      "administrativeSpeedLimit": 30,
      "relevanceScore": 0.05309479745013365,
      "countryRelevanceScore": 0,
      "cityRelevanceScore": 0,
      "postalCodeRelevanceScore": 0,
      "streetRelevanceScore": 0,
      "streetNumberRelevanceScore": 0,
      "geoElementTypes": [
        "ROAD",
        "FOURTH_ROAD",
        "DISTRICT",
        "CITY",
        "COUNTY",
        "STATE",
        "COUNTRY"
      ],
      "segmentId": 0
    },
    {
      "coordinate": {
        "lon": 2.3413,
        "lat": 48.85688
      },
      "distanceFromRequest": 9.2,
      "postalAddress": {
        "countryCode": "FRA",
        "country": "France",
        "state": "Île-de-France",
        "county": "Paris",
        "city": "Paris",
        "district": "Paris 1er Arrondissement",
        "postalCode": "75001",
        "roadNumber": "",
        "street": "Place du Pont Neuf",
        "streetNumber": "15",
        "oppositeStreetNumber": "15"
      },
      "postalAddressClassType": "ROAD_FOURTH",
      "postalAddressClassId": 4048,
      "postalAddressExactStreeNumber": false,
      "angle": 35,
      "administrativeSpeedLimit": 30,
      "relevanceScore": 0.05190211803413529,
      "countryRelevanceScore": 0,
      "cityRelevanceScore": 0,
      "postalCodeRelevanceScore": 0,
      "streetRelevanceScore": 0,
      "streetNumberRelevanceScore": 0,
      "geoElementTypes": [
        "ROAD",
        "FOURTH_ROAD",
        "DISTRICT",
        "CITY",
        "COUNTY",
        "STATE",
        "COUNTRY"
      ],
      "segmentId": 0
    },
    {
      "coordinate": {
        "lon": 2.34128,
        "lat": 48.85686
      },
      "distanceFromRequest": 9.75,
      "postalAddress": {
        "countryCode": "FRA",
        "country": "France",
        "state": "Île-de-France",
        "county": "Paris",
        "city": "Paris",
        "district": "Paris 1er Arrondissement",
        "postalCode": "75001",
        "roadNumber": "",
        "street": "Quai des Orfèvres"
      },
      "postalAddressClassType": "ROAD_FOURTH",
      "postalAddressClassId": 4048,
      "postalAddressExactStreeNumber": false,
      "angle": 134,
      "administrativeSpeedLimit": 30,
      "relevanceScore": 0.05171704709027348,
      "countryRelevanceScore": 0,
      "cityRelevanceScore": 0,
      "postalCodeRelevanceScore": 0,
      "streetRelevanceScore": 0,
      "streetNumberRelevanceScore": 0,
      "geoElementTypes": [
        "ROAD",
        "FOURTH_ROAD",
        "DISTRICT",
        "CITY",
        "COUNTY",
        "STATE",
        "COUNTRY"
      ],
      "segmentId": 0
    }
  ],
  "maximunResult": 5
}
```

## 📘 Notes

- Coordinates must be expressed in **WGS84 decimal degrees**.
- If no result is found within the provided `radius`, the response will be empty.
- If the `language` parameter is missing, the system will use the default server language.