# Roads extractor

REST API, Service version 1.0.0

> API reference: [`POST /roadsextractor/1.0`](https://benomad.com/dev/doc/bemap-api/api/map-context/roadsextractor.md)

Performs a Road-Matching (or Map-Matching) process for a specified type of vehicle within a specified polygon.
This method builds a list of `ExtractedRoadFront` on each road element within the specified polygon.
For road elements which are open in both directions according to the specified type of vehicle, two `ExtractedRoadFront` will be created, one for each direction.
The angle set on each `ExtractedRoadFront` defines the direction this point has to be reached should you use these points to perform a route calculation or trip optimization.

> NOTE: The maximum number of `ExtractedRoadFront` that can be created is limited to 1500.

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

## 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/roadsextractor/1.0`

POST data:
```javascript
{
    "geoserver": "default",
    "outputLanguage": "en",
    "coordinates": [
        {
            "lon": 7.41,
            "lat": 43.73
        },
        {
            "lon": 7.42,
            "lat": 43.73
        },
        {
            "lon": 7.42,
            "lat": 43.74
        },
        {
            "lon": 7.41,
            "lat": 43.74
        },
        {
            "lon": 7.41,
            "lat": 43.73
        }
    ],
    "transportType": "CAR",
    "adminPath": true
}
```

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__

- `coordinates` (Coordinate[], required): List of coordinates of the polygon.
  - `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.
- `outputLanguage` (string): Define the language that will be used to perform the address lookup. Objects for which defined language code is not available, the default language will be used. A US-ASCII string that defines an ISO 639-1 (2-letter) language code. The special "IC" (or "ic") language code allows you to search for a country depending on its ISO-3166 Alpha-3 or Alpha-2 country code.
- `transportType` (enum): Transportation mode. `CAR` by default.
  - `PEDESTRIAN`: Pedestrian.
  - `BICYCLE`: Bicycle.
  - `MOTORCYCLE`: Motorcycle.
  - `CAR`: Passenger car.
  - `TAXI`: Taxi.
  - `PUBLIC_BUS`: Public bus.
  - `EMERGENCY`: Emergency vehicle.
  - `DELIVERY_TRUCK`: Delivery truck. Deprecated, use `TRUCK` instead.
  - `TRUCK`: Truck.
- `classIdFilters` (string[]): List of road network class ID to filter by. A class ID can be a number e.g. `4000` or an enumeration string e.g. `ROAD_FOURTH`). No filtering by default. [List of available class ID](https://benomad.com/dev/doc/bemap-api/guides/reference/sdk-jsiv-classids.md).
- `adminPath` (boolean): Set this flag to true if you want to retrieve the complete hierarchical path of each `ExtractedRoadFront`. This option is required to get the postal addresses.
- `filterElementsHouseNumbers` (boolean): Set to true to filter road elements with house numbers only.
- `filterClippedElements` (boolean): Set this flag to true if you want to filter out elements which are not fully inside the polygon.

## Response

### Details of fields

- `roads` (ExtractedRoadFront[]): List of extracted road information.
  - `coordinate` (Coordinate): The coordinate around the middle of the extracted road.
    - `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`.
  - `angle` (integer (int32)): Angle associated with the coordinate of the extracted road. This angle defines the direction this point has to be reached should you use these points to perform a route calculation or trip optimization.
  - `label` (string): Label of the road.
  - `postalAddress` (Address): Postal address of the extracted road.
    - `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.

### Response samples
JSON Sample:
```javascript
{
  "roads": [
    {
      "coordinate": {
        "lon": 7.411,
        "lat": 43.731
      },
      "postalAddress": {
        "street": "Avenue de la Costa",
        "city": "Monaco",
        "postalCode": "98000"
      }
    }
  ]
}
```