Route calculation

Basic principles

This web service calculates an itinerary between two points and returns a full route sheet. It is possible to add optional intermediate steps.

Route calculation example 

{
        "url":"https://api.geoconcept.com/EU/GCW/geoconcept-web/api/lbs/route/v7.json",
        "type":"GET",
        "params": {
                "origin": {
                        "sample":"5.3655,43.3293"
                },
                "destination": {
                        "sample":"5.3940,43.2673"
                },
                "waypoints": {
                        "sample":""
                },
                "exclusions": {
                        "sample":"ZFE"
                }
        }
}

Parameters / properties

Input

parameter description optional default

origin

Coordinates of the start point (longitude, latitude).
The longitude and latitude coordinates are separated by the , character.

no

destination

Coordinates of the end point (longitude,latitude).
The longitude and latitude coordinates are separated by the , character

no

waypoints

List of the coordinates of the route stops. The longitude and latitude coordinates are separated by the "," character. The pairs of coordinates are separated from each other by the ";" character.

yes

method

Method to compute the route between the start point and the resources:
- distance: shortest route
- time: fastest route
- flying: as the crow flies

yes

time

format

- standard: result = route summary / bounds / geometry in wkt format / simplified geometry in wkt format / list of concatenated segments (without geometries)
- extended: result = route summary / bounds / simplified geometry in wkt format / list of non-concatenated segments (with geometries)
- summary: result = route summary
- geometry: result = route summary / bounds geometry in wkt format
- simplifiedgeometry: result = route summary / bounds / simplified geometry in wkt format
- geometries: result = route summary / geometry in wkt format
- brief: result = route summary / List of segments with duration and distance
- standardext: result = route summary / bounds / list of concatenated segments with duration and distance and geometry
- node: result = route summary / Id of snapped nodes
- compressedgeometry: result = route summary / bounds / compressed geometry with polyline encoding
- compressedsimplifiedgeometry: result = route summary / bounds / simplified compressed geometry with polyline encoding
- completegeometry: result = route summary / bounds / geometry in wkt format / concatenated segments list with geometries in wkt format
- compresscompletegeometry: result = route summary / bounds / compressed geometry with polyline encoding / concatenated segments list with geometries with polyline encoding
- tollcost: result = route summary / amount tolls cost. The amount is calculated according to the type of vehicle defined in configName as well as the date / time of departure of the startDateTime .
- custom: declare list of format items in customFormat parameter.

yes

standard

srs

projection (EPSG code such as epsg:4326 or wgs84)

yes

tolerance

Tolerance distance (in meters) for the geometry simplification.

yes

originDateTime

Origin date and time (format ISO8601: local time) example: 2014-01-21T09:00:00.000+0100 (or 2014-01-21T09:00:00.000%2B01:00) for a start on 21 January 2014, at 9.00am in Paris

yes

destinationDateTime

Destination date and time (format ISO8601: local time) example: 2014-01-21T09:00:00.000+0100 (or 2014-01-21T09:00:00.000%2B01:00) for a departure on 21 January 2014, at 9.00am in Paris

yes

exclusions

List of restriction rules to use, separated by the ; character
Available exclusion rules:
- Toll
- Infrastructure (Tunnel, Bridge)
- Hazardous material (Flammable, Dangerous, Pollutant, Toxic)
- ZFE (Zone � faible �mission, France-only) - …
- Detailled list available on the FAQ bellow.

yes

timeLine

List of intermediate durations to calculate positions along the route trajectory. Expressed in seconds, separated by the ; character. The returned position corresponds to the previous node, on the route, connectable to the network. For example, on a highway, the position returned is the last exit or service area before the requested position.

yes

snapMethod

Snap to graph method
- standard: to the nearest connectable road segment
- extended: via restricted road sections (pedestrian routes…)
- nearest: to the nearest road section only
- unrestricted: without any restriction rules - nodes: snap directly to nodes supplied by the originNode originNode, destinationNode and waypointNodes parameters or, if these first ones are not filled, snap directly to the nearest nodes origin, destination and waypoint parameters.

yes

standard

avoidArea

Forbidden transit zone in WKT format (POLYGON or MULTIPOLYGON) in the requested projection (srs parameter)
Example in wgs84: POLYGON ((-1.556892 47.21689, -1.556892 47.216904, [...] -1.556892 47.21689)) - MULTIPOLYGON (((-1.556892 47.21689, -1.556892 47.216904, [...] -1.556892 47.21689)), ((-1.558639 47.218144, -1.558639 47.218193, [...] -1.558639 47.218144)))
Care: WKT geometries must be closed.

yes

configName

Name of the configuration to use:
- bicycle (not available for Japan)
- bus
- car
- delivery light vehicle
- delivery truck vehicle
- emergency truck
- emergency vehicle
- pedestrian (not available for Japan)
- taxi
- truck

yes

computeOptions

Selection of variables to use in calculations, using semi-colons ; as separators:
- speedPattern: utilization as a speed pattern. Use: "speedPattern:slow-speed"
- length: maximum authorised length in centimeters. Use: "length:950"
- width: maximum authorised width in centimeters. Use: "width:255"
- height: maximum authorised height in centimeters. Use: "height:360"
- weight: maximum authorised weight in kilograms. Use: "weight:18000"
- axles: maximum authorised number of axels. Use: "axles:2"
- weightPerAxle: maximum authorised weight per axel in kilograms. Use: "weightPerAxle:9000"
- fuelType: fuel type used to calculate carbon footprint for the journey. Available values are: "UndefinedFuelType", "NoFuel", "Diesel", "UnleadedFuel", "LGP", "CustomFuelType" and "Electrical". Use: "fuelType:Diesel"
- averageConsumption: average consumption in litres for 100 kilometers or Wh per kilometers if electrical vehicle. Use: "averageConsumption:6.45"
- cityAverageConsumption: average consumption value in city mode, in litres per 100 kilometers, or Wh per kilometers if electrical vehicle. Use: "cityAverageConsumption:4.65"
- combinedAverageConsumption: average consumption value in combined mode, in litres per 100 kilometers, or Wh per kilometers if electrical vehicle. Use: "combinedAverageConsumption:5.12"
- highwayAverageConsumption: average consumption value in highway mode, in value in litres per 100 kilometers, or Wh per kilometers if electrical vehicle. Use: "highwayAverageConsumption:5.64" - customAverageCO2UnitEmission: defines the carbon footprint in kilograms per litre. Use: "customAverageCO2UnitEmission:2.724"
- snapSpeed: snap-to-graph speed in kilometers per hour. Use: "snapSpeed:10"

yes

formatItems

List of format items to use, if route format is set to custom
- ROUTE_DISTANCE
- ROUTE_DURATION
- ROUTE_DISTANCE_FORMATTED
- ROUTE_DURATION_FORMATTED
- ROUTE_BOUNDS
- SRS
- ROUTE_CARBON_FOOTPRINT
- START_FINISH_DATETIME
- SUBROUTE_DISTANCE
- SUBROUTE_DURATION
- SUBROUTE_DISTANCE_FORMATTED
- SUBROUTE_DURATION_FORMATTED
- SEGMENT_DISTANCE
- SEGMENT_DURATION
- SEGMENT_DISTANCE_FORMATTED
- SEGMENT_DURATION_FORMATTED
- SEGMENT_NAME
- SEGMENT_NAVIGATIONINSTRUCTION
- SEGMENT_POINTSLIST
- SEGMENT_FIELDSVALUES
- SEGMENT_UNCONSOLIDATED
- ROUTE_GEOMETRY_WKT
- ROUTE_SIMPLIFIEDGEOMETRY_WKT
- ROUTE_GEOMETRY_COMPRESSED
- ROUTE_SIMPLIFIEDGEOMETRY_COMPRESSED
- SUBROUTE_GEOMETRY_WKT
- SUBROUTE_GEOMETRY_COMPRESSED
- TIMELINE
- POINTS_GRAPHNODES
- ROUTE_TOLLCOST
- COMPUTATION_TIME

oui

fields

list of fields to retrieve value for each leg (for standard and extended formats )
- Iso country code
- Country
- Postcode left
- Postcode right
- City name left
- City name right
- Ramp
- Urban
- Tunnel
- Toll
- Bicycles
- Automobiles
- Frontage
- Bridge

oui

Output

Route (routeResult)

parameter type min/max description

distance

string

0/1

Total route distance, formatted:
- xx.xx Km
- xx m (if the distance is less than 1 km)

duration

string

0/1

Total duration of the route, formatted:
- HH:mm:ss (HH=hours, mm=minutes, ss=seconds)

distanceMeters

double

0/1

Total route distance in meters.

durationSeconds

double

0/1

Total duration of the route in seconds.

bounds

double

0/1

Bounds of the result route geometry.

wktGeometry

string

0/1

Geometry of the route in WKT format

wktSimplified

string

0/1

Simplified geometry in WKT format.

legs

Array of SubRouteV7

0/unlimited

List of route segments.

startDateTime

string

0/1

Start date and time (format: ISO8601 without any area code: local time)
Example: 2014-01-21T09:00:00.000+01:00 for a departure on 21 January 2014, at 9.00am in Paris

finishDateTime

string

0/1

Arrival date and time (format: ISO8601 without any area code: local time)
Example: 2014-01-21T09:00:00.000+01:00 for an arrival time on 21 January 2014, at 9.00am in Paris

timeLine

Array of TimeLineItemV7

0/unlimited

List of calculated positions.

srs

string

0/1

projection passed as input (EPSG code such as epsg:4326 or wgs84)

originNode

string

0/1

Start node identifier (entered if format=NODE).

destinationNode

string

0/1

Arrival node identifier (entered if format=NODE).

waypointNodes

waypointNodes array (string)

0/unlimited

Step nodes identifiers (entered if format=node).

carbonFootprint

double

0/1

Carbon footprint (CO2 emissions in kilograms).

energyConsumption

double

0/1

Energy consumption (Energy consumed in Litres or kWh for electrical vehicles).

tollCost

Array of tollCost

0/unlimited

Toll cost informations (entered if format=TOLLCOST).

fieldsNames

Array of string

0/unlimited

value of fields.

Itinerary portion (SubRouteV7)

parameter type min/max description

distance

string

0/1

Total route distance, formatted:
- xx.xx Km
- xx m (if the distance is less than 1 km)

duration

string

0/1

Total duration of the route, formatted:
- HH:mm:ss (HH=hours, mm=minutes, ss=seconds)

distanceMeters

double

0/1

Distance covered by the route segment in meters.

durationSeconds

double

0/1

Duration of the route segment in seconds.

steps

Array of SegmentV7

0/unlimited

List of component segments in the route segments

Route segment (SegmentV7)

parameter type min/max description

distance

string

0/1

Total route distance, formatted:
- xx.xx Km
- xx m (if the distance is less than 1 km)

duration

string

0/1

Total duration of the route, formatted:
- HH:mm:ss (HH=hours, mm=minutes, ss=seconds)

distanceMeters

double

0/1

Distance covered by the route segment in meters.

durationSeconds

double

0/1

Duration of the route segment in seconds.

navigationInstruction

string

0/1

Navigation instruction code:
- F: Straight on
- FR: Turn slightly to the right
- FL: Turn slightly to the left
- R: Turn right
- L: Turn left
- BR: Turn hard right
- BL: Turn hard left
- B: U-turn
- round_about_entry: Enter roundabout
- round_about_exit: Exit from roundabout

name

string

0/1

Segment street name.

points

string

0/unlimited

List of coordinates separated by the , character

fieldsNames

Array of string

0/unlimited

value of fields.

Route position (TimeLineItemV7)

parameter type min/max description

durationSeconds

double

0/1

Route duration in seconds up to this position.

message

string

0/1

Error message for this position.

status

string

0/1

Status of this position.

distanceMeters

double

0/1

Distance of the route in meters up to this position.

location

string

0/1

Coordinates of the position.

Toll Cost (tollCost)

parameter type min/max description

amount

double

0/1

Total cost of tolls .

currency

string

0/1

Currency.

costsByCountry

Array of costsByCountry

0/unlimited

List of toll cost by countries.

Cost by countries (costsByCountry)

parameter type min/max description

amount

double

0/1

Cost of tolls.

country

string

0/1

Country code (3-letter ISO country codes).

Possible returns

Case of a route found (routeResult/status is OK)  

{
    "status": "OK",
    "distance": "5.23 Km",
    "duration": "0:22:24",
    "distanceMeters": 5229.86,
    "durationSeconds": 1344.15,
    "bounds": "-0.167612,51.48793;-0.125122,51.50068",
    "wktGeometry": "LINESTRING (-0.125122 51.494445, -0.125159 51.494452, -0.12519 51.49439, -0.12517 51.49399, [...])",
    "wktSimplifiedGeometry": "LINESTRING (-0.125122 51.494445, -0.125159 51.494452, -0.12519 51.49439, -0.12517 51.49399, [...])",
    "carbonFootprint": 2.493,
    "energyConsumption": 0.266,
    "computationTime": 3669.643,
    "legs": [
        {
            "distance": "3.37 Km",
            "duration": "0:14:26",
            "distanceMeters": 3374.55,
            "durationSeconds": 866.17,
            "steps": [
                {
                    "distance": "54 m",
                    "duration": "0:00:15",
                    "distanceMeters": 54.45,
                    "durationSeconds": 15.72,
                    "name": "MILLBANK"
                },
                [...]
            ]
        },
        {
            "distance": "1.86 Km",
            "duration": "0:07:57",
            "distanceMeters": 1855.31,
            "durationSeconds": 477.98,
            "steps": [
                {
                    "distance": "11 m",
                    "duration": "0:00:03",
                    "distanceMeters": 11.07,
                    "durationSeconds": 3.16,
                    "name": "BASIL STREET"
                },
               [...]
            ]
        }
    ]
}

Case of a forgotten specification of a start or finish point (routeResult/status is ERROR)  

{
    "message": "Origin, destination and waypoints should be represented by a couple of coordinates",
    "status": "ERROR",
    "legs": [
    ]
}

Case of a faulty format assigned to the start or finish point or to route stops (routeResult/status is ERROR)  

{
    "message": "Origin, destination and waypoints should be represented by a couple of coordinates",
    "status": "ERROR",
    "legs": [
    ]
}

Case of a snap-to-graph error (serviceResult/status is ERROR)  

{
    "message": "ServiceException: Error in route computation|Error in smartrouting|Failed to execute calculateRoute|com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect waypoint { -100.125122, 51.494445, 0.000000 } srs=epsg:4326|failed to connect waypoint { -100.125122, 51.494445, 0.000000 } srs=epsg:4326",
    "status": "ERROR"
}

FAQ

1. Is it possible to give priority to either journey time or journey distance?
2. Is it important what order the points are in?
3. How perform a route calculation without including any road tolls?
4. What are the maximum values allowed by predefined configName?
5. What are the exclusions available?
6. What are the Hazardous material exclusions?
7. What are Speed Patterns? How are they used?
8. How do you use heavy goods vehicle attributes?
9. How is the carbon footprint for a journey calculated?
10. What is the algorithm used for compressedgeometry and compressedsimplifiedgeometry formats?

1.

Is it possible to give priority to either journey time or journey distance?

Yes, by changing the method: distance or time.

2.

Is it important what order the points are in?

The points, whether they are start points, finish points, or way points are read and used in that order. The first point declared is considered as a start point, the second as an arrival point, and the others as way points. The order of the points is therefore very important.

3.

How perform a route calculation without including any road tolls?

Place the exclusion Toll in exclusions.

4.

What are the maximum values allowed by predefined configName?

See list below:

configName axles weightPerAxle weight height length width

bicycle

bus

2

9500

19000

350

1350

250

car

delivery light vehicle

2

1700

3400

300

680

220

delivery truck vehicle

2

9500

19000

350

1350

250

emergency truck vehicle

2

9000

18000

360

920

255

emergency vehicle

pedestrian

taxi

truck

4

19000

39000

387

1850

255

5.

What are the exclusions available?

See list below:

Exclusion Description

Toll

if added on exclusions toll road sections are not used.

BoatFerry

if added on exclusions ferry itineraries (shipping) over water are not used.

RailFerry

if added on exclusions ferry (or train) itineraries (over water and land respectively) are not used.

Tunnel

if added on exclusions tunnels are not used.

Bridge

if added on exclusions bridges are not used.

Frontage

if added on exclusions Frontage roads (local roads running parallel to a higher-speed, limited-access road) are not used.

Paved

if added on exclusions tarmac road sections are not used.

Private

if added on exclusions road sections for which maintenance is provided by a private organization are not used.

Pedestrians

if added on exclusions road sections unauthorised for pedestrian use are not used. The configName parameter with a value of pedestrian uses this exclusion.

Automobiles

if added on exclusions road sections with restricted automobile access are not used. The configName parameter with a value of car uses this exclusion.

Trucks

if added on exclusions road sections with restricted access for lorries are not used. The configName with a value of truck or delivery truck vehicle or emergency truck uses this exclusion.

Bus

if added on exclusions road sections with restricted access for buses are not used. The configName with a value of bus uses this exclusion.

Deliveries

if added on exclusions road sections with restricted access for deliveries are not used. The configName with a value of delivery light vehicle or delivery truck vehicle uses this exclusion.

Taxis

if added on exclusions road sections with restricted access for taxis are not used. The configName with a value of taxi uses this exclusion.

Emergencies

if added on exclusions road sections with restricted access for emergencies are not used. The configName with a value of emergency truck or emergency vehicle uses this exclusion.

Carpools

if added on exclusions road sections with restricted access for carpools are not used.

Throughtraffic

if added on exclusions road sections with restricted access for non-local traffic are not used.

ZFE

if added on exclusions low carbon emmission areas in France will be excluded

(Hazardous material)

See description bellow.

6.

What are the Hazardous material exclusions?

Hazardous material defines a restriction to a road for any vehicle carrying the specific hazardous material. Hazardous material restrictions are government regulations and can be different per country.

  • Flammable: explosives, flammable, gas, combustible, …
  • Pollutant: goods harmful for water
  • Toxic: organic, poison, radioactive, corrosive, …
  • Dangerous: tunnel categories and others restrictions

7.

What are Speed Patterns? How are they used?

With the aim of suggesting journey times that take traffic conditions into account as accurately as possible, cars and trucks have 5 speed profiles (Speed Patterns) so various levels of road congestion can be taken into account over the timespan of a whole day:

  • standard normal-speed corresponds to the speed at a time when the traffic congestion is moderate (11h)
  • night fast-speed corresponds to very fluid traffic conditions, most often found at night time (3h)
  • busy slow-speed corresponds to the times when traffic congestion is at its densest (8h)
  • peak travel time very-slow-speed corresponds to times when traffic is densest in urban areas, and is slower than the category given above (8h)
  • default default corresponds to average speeds over a whole day

To use these, you will need to pass to parameter, when calling the web service, the following parameter computeOptions with the option speedPattern and specify the value of the Speed Pattern requested, always remembering to include a vehicle configName.
Example: 

&computeOptions=speedPattern:fast-speed&configName=car

8.

How do you use heavy goods vehicle attributes?

You need to calculate an itinerary using either a vehicle configName using the restrictions, or by overwriting the call to the web service using the parameter computeOptions with the options length, width, height, weight, axles and/or weightPerAxle.
Example for a journey with a vehicle with a height of 4.5m: 

&computeOptions=height:450

9.

How is the carbon footprint for a journey calculated?

Calculation of carbon footprint takes into account vehicle type, fuel type, and vehicle speed, road section by road section: 10 kms in a town context does not have the same carbon footprint as 10km in the countryside. It is displayed in the response when format is equal to standard (default) or extended.
The carbon footprint of the route is calculated automatically. You can overdefine the default values when the call to the web service is made using computeOptions with options fuelType, averageConsumption and/or customAverageCO2UnitEmission.
Available values are fuelType with, as possible values:

  • NoFuel
  • Diesel
  • UnleadedFuel
  • LGP
  • CustomFuelType (enables personalization of a value in kgs of CO2 per litre to specify in customAverageCO2UnitEmission)

averageConsumption allows you to indicate the average consumption for the vehicle for 100 kilometers.

10.

What is the algorithm used for compressedgeometry and compressedsimplifiedgeometry formats?

The utilization of the encoded polyline compression algorithm (Encoded Polyline Algorithm Format) enabling storage of coordinates in a single ASCII character string, thereby significantly reducing overall data volumes.

Prev  Up  Next
  Home