# Roads extractor

`POST https://bemap.benomad.com/bgis/service/roadsextractor/1.0`

Part of [Roads extractor](https://benomad.com/dev/doc/bemap-api/routing/roads-extractor.md).

> **Get every road in a zone.** All the road segments inside a zone you draw, for a type of vehicle, to plan a round that covers the whole zone.

Extract the roads information process for a specified type of vehicle within a specified polygon.

Provisioned per account: without it, BeMap answers `400 Access Denied`.

## Request body

JSON, `Content-Type: application/json`. Schema `RoadsExtractorRequest`.

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

`200`, schema `RoadsExtractorResponse`.

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

## Errors

- `400`: Bad Request
- `302`: no credentials were sent. Do not follow the redirect.
- `401`: the account or the API key is wrong.

How to read each one: [Errors](https://benomad.com/dev/doc/bemap-api/getting-started/errors.md).

## Example

```bash
curl -X POST 'https://bemap.benomad.com/bgis/service/roadsextractor/1.0' \
  -u 'YOUR_ACCOUNT:YOUR_API_KEY' \
  --fail-with-body \
  -H 'Content-Type: application/json' \
  -d '{
  "coordinates": [
    {
      "lat": 48.86,
      "lon": 2.337
    },
    {
      "lat": 48.862,
      "lon": 2.337
    },
    {
      "lat": 48.862,
      "lon": 2.34
    },
    {
      "lat": 48.86,
      "lon": 2.34
    }
  ],
  "transportType": "CAR",
  "outputLanguage": "fr"
}'
```

Response captured from production, long arrays and strings shortened:

```json
{
  "roads": [
    {
      "coordinate": {
        "lon": 2.3399866666666664,
        "lat": 48.86199666666667
      },
      "angle": 127,
      "label": "Rue Saint-Honoré"
    },
    {
      "coordinate": {
        "lon": 2.3392,
        "lat": 48.86166666666667
      },
      "angle": 23,
      "label": "Rue de Marengo"
    }
  ]
}
```

## Reference pages

- [Roads extractor](https://benomad.com/dev/doc/bemap-api/guides/services/roadsextractor.md)