REST API, Service version 1.0.0

Roads extractor#

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#

Request
1. Mandatory parameters
2. Optional parameters
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 glossary for more details.

Parameters#

coordinatesCoordinate[]required
List of coordinates of the polygon.
Coordinate fields
- lonnumber (double)required
  Longitude in degrees decimal (WGS84).
  Also accepted as longitude.
- latnumber (double)required
  Latitude in degrees decimal (WGS84).
  Also accepted as latitude.
geoserverstring
Geoserver name.
swidxinteger (int32)deprecated
Switch index.
outputLanguagestring
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.

transportTypeenum

Transportation mode. CAR by default.

9 accepted values

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

classIdFiltersstring[]
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.
adminPathboolean
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.
filterElementsHouseNumbersboolean
Set to true to filter road elements with house numbers only.
filterClippedElementsboolean
Set this flag to true if you want to filter out elements which are not fully inside the polygon.

Response#

Details of fields#

roadsExtractedRoadFront[]
List of extracted road information.
ExtractedRoadFront fields
- coordinateCoordinate
  The coordinate around the middle of the extracted road.
  Coordinate fields
  - lonnumber (double)required
    Longitude in degrees decimal (WGS84).
    Also accepted as longitude.
  - latnumber (double)required
    Latitude in degrees decimal (WGS84).
    Also accepted as latitude.
- angleinteger (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.
- labelstring
  Label of the road.
- postalAddressAddress
  Postal address of the extracted road.
  Address fields
  - countryCodestring
    ISO code of country.
  - countrystring
    Country name.
  - statestring
    State name.
  - countystring
    County name.
  - citystring
    City name.
  - districtstring
    District name of city.
  - postalCodestring
    Postal code.
  - roadNumberstring
    Road number.
  - streetstring
    Street name.
  - streetNumberstring
    House number.
  - oppositeStreetNumberstringdeprecated
    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"
      }
    }
  ]
}