Optimisation (simplified version)

(fr) Cette page n’est plus maintenue depuis la version 2022 de Geoconcept Web. Pour accéder à la documentation à jour de ce web service, veuillez suivre ce lien.

Basic principles

This web service allows you to define optimum routes while minimising travel times and distances. The ordering of points to visit is optimised on the basis of geographic and operational constraints (time slots, duration of the visit..;). It is based on the configured graph, the name of which has been specified in the Geoconcept Web administration interface.

Availability

This web service is a Geoconcept Web option: please contact us to know how to purchase this service.

Version change

Earlier versions of the web service are conserved in Geoconcept Web to ensure compatibility with earlier software versioning and development. We recommend using the most recent version.

Changes in relation to V3

  • Addition of various input parameters: "graphName", "profileId", "profileName", "configName", "snapMethod", "exclusions", "startDateTime", "avoidArea", "computeOptions", "maxCost" and "timeOut".
  • Addition in output of the list of "unreachableSteps", these being the route stops that could not be visited.

Changes in relation to V2

  • Addition of the "timewindows/timewindow" parameter.
  • The "totalDistance" and "totalTime" parameters have been renamed "distanceMeters" and "durationSeconds" respectively.
  • The Web service is no longer available in REST GET.

V3

Parameters / properties

Input

parameter description optional default

origin (optimRouteStepV3)

origin point (id,x,y)

yes

destination (optimRouteStepV3)

destination point (id,x,y)

yes

steps (optimRouteStepV3)

points to visit (id,x,y;id,x,y;…)
Several slots for visiting times in milliseconds can be specified for each point: (id,x,y,start, finish)

no

method

shortest (distance) or fastest (time) route

yes

time

graphName

"Name of the graph to use
This parameter is omitted if the configName parameter is used.

yes

profileId

Vehicle identifier (saved in the vehicle profiles)
This parameter is omitted if the configName parameter is used.

yes

profileName

Vehicle profile (saved in the vehicle profiles)
This parameter is omitted if the configName parameter is used.

yes

configName

Name of the configuration to use (defined in Geoconcept Web - Administration / Tools / Road graphs)
This replaces the use of graphName, profileId and profileName

yes

snapMethod

Snap to graph method
- standard: to the nearest connectable road section
- 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, destinationNode and waypointNodes parameters, or, if these parameters have not been set, to the nearest nodes sourced by the origin, destination and waypoint parameters

yes

standard

exclusions

List of restriction rules to use, separated by the ; character (Example: Toll, Tunnel, Bridge)

yes

startDateTime

Departure Date and Time (format ISO8601: local time) Example: 2014-01-21T09:00:00.000+01:00 (or 2014-01-21T09:00:00.000%2B01:00) for a departure date on 21 Januray 2014, at 9.00am in Paris. Caution: the + character may be misinterpreted by some browsers, and in this instance, you will need to replace it with %2B.

yes

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

computeOptions

List of options for the calculation,separated by ; characters
- trafficPatterns: uses routing statistics (you will need to supply a value for the startDateTime parameter and use a graph that includes traffic patterns information)
- speedPattern (M18): uses a speed pattern as defined in the SmartRoutingVehicles.xml file, located in the `‘<GEOCONCEPT_WEB_HOME>’'\smartrouting\jee\smartrouting\conf\ folder. Use as follows: "speedPattern:slow-speed"
- length (M18): maximum authorised length in centimeters (you need to use a graph that includes Heavy Goods Vehicle attributes). Use as follows: "length:950"
- width (M18): maximum authorised width in centimeters (You will need to use a graph that includes Heavy Goods Vehicle attributes). Use as follows: "width:255"
- height (M18): maximum authorised height in centimeters (you will need to use a graph that includes Heavy Goods Vehicle attributes). Use as follows: "height:360"
- weight (M18): maximum authorised weight in kilograms (you will need to use a graph that includes Heavy Goods Vehicle attributes). Use as follows: "weight:18000"
- axles (M18): maximum authorised number of axles (you will need to use a graph that includes Heavy Goods Vehicle attributes). Use as follows: "axles:2"
- weightPerAxle (M18): maximum authorised weight per axle in kilograms (you will need to use a graph that includes Heavy Goods Vehicle attributes). Use as follows: "weightPerAxle:9000"
- snapSpeed: snap-to-graph speed in kilometers per hour. Use as follows: "snapSpeed:10"

yes

matrixProvider

matrix calculation provider
globe: as the crow flies on the globe (the coordinates must be in long/lat)
euclidean: as the crow flies on the map (the coordinates must be in metres)
smartrouting: calculation on the road network by SmartRouting
nokia: calculation on the road network via a Nokia service
provided: matrix parameter

yes

smartrouting

matrix

time/distance matrix (id1,id2,temps,distance;…)

yes

srs

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

yes

wgs84

directSpeed

Default speed during utilisation of globe or euclidean matrices

yes

50

maxCost

Maximum cost not to exceed in the calculation
-1: no maximum cost to take into account
0: take the default value defined in the SmartRouting Server configuration
if not: value in metres if method=distance or in seconds if method=time

yes

timeOut

Time out for the calculation (in milliseconds)

yes

(optimRouteStepV3) steps

parameter type min/max description

id

string

0/1

point id

duration

long

1/1

duration of a visit, in milliseconds. O by default

timeWindows/timeWindow (optimTimeWindow)

long

1/1

Time windows

Time windows (optimTimeWindow)

parameter type min/max description

start

long

1/1

start of the time window, in milliseconds. 0 by default.

end

long

1/1

time window end, in milliseconds. Long.MAX_VALUE by default

Output

parameter type min/max description

steps/step

array (optimRouteStepV3)

0/unlimited

list of route stops in sequence

distanceMeters

long

1/1

total journey distance in meters

durationSeconds

long

1/1

total journey time in seconds

unreachableSteps

array (OptimUnreachableStepV3)

0/unlimited

list of unreachable route stops.

(optimRouteStepV3) steps

parameter type min/max description

id

string

0/1

route stop ID

x

number

1/1

route stop’s X coordinate

y

number

1/1

route stop’s Y coordinate

duration

long

1/1

duration of a visit, in milliseconds. O by default

effectiveStart

long

1/1

effective start time for a visit, in milliseconds

driveDistanceBefore

int

1/1

drive time before the step, in metres

driveDistanceAfter

int

1/1

drive distance after the step, in metres

driveTimeBefore

long

1/1

drive time before the step, in milliseconds

driveTimeAfter

long

1/1

drive time after the step, in milliseconds

timeWindows/timeWindow (optimTimeWindow)

long

1/1

Time windows

Time windows (optimTimeWindow)

parameter type min/max description

start

long

1/1

start of the time window, in milliseconds. 0 by default.

end

long

1/1

time window end, in milliseconds. Long.MAX_VALUE by default

List of unreachable route stops (OptimUnreachableStepV3)

parameter type min/max description

id

string

1/1

route stop ID

x

double

1/1

Route stop’s Longitudinal position

y

double

1/1

Route stop’s Latitudinal position
SOAP

WSDL

http://<server>/<webapp>/api/ws/optimService?wsdl

Query

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header />
   <soapenv:Body>
      <sch:optimRouteV3>
         <request>
            <origin>
               <x>-1.5291995940651142</x>
               <y>47.19158811606974</y>
               <id>1</id>
               <duration>3600000</duration>
               <effectiveStart>0</effectiveStart>
               <driveDistanceBefore>0</driveDistanceBefore>
               <driveDistanceAfter>0</driveDistanceAfter>
               <driveTimeBefore>0</driveTimeBefore>
               <driveTimeAfter>0</driveTimeAfter>
            </origin>
            <destination>
               <x>-1.5405963750884433</x>
               <y>47.19752774053115</y>
               <id>5</id>
               <duration>3600000</duration>
               <effectiveStart>0</effectiveStart>
               <driveDistanceBefore>0</driveDistanceBefore>
               <driveDistanceAfter>0</driveDistanceAfter>
               <driveTimeBefore>0</driveTimeBefore>
               <driveTimeAfter>0</driveTimeAfter>
            </destination>
            <steps>
               <step>
                  <x>-1.5315788375137436</x>
                  <y>47.209701524818236</y>
                  <id>2</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>0</driveDistanceBefore>
                  <driveDistanceAfter>0</driveDistanceAfter>
                  <driveTimeBefore>0</driveTimeBefore>
                  <driveTimeAfter>0</driveTimeAfter>
                  <timeWindows>
                     <!--Zero or more repetitions:-->
                     <timeWindow>
                        <start>0</start>
                        <end>9223372036854775807</end>
                     </timeWindow>
                  </timeWindows>
               </step>
               <step>
                  <x>-1.5391738246474214</x>
                  <y>47.193576663578824</y>
                  <id>3</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>0</driveDistanceBefore>
                  <driveDistanceAfter>0</driveDistanceAfter>
                  <driveTimeBefore>0</driveTimeBefore>
                  <driveTimeAfter>0</driveTimeAfter>
                  <timeWindows>
                     <!--Zero or more repetitions:-->
                     <timeWindow>
                        <start>0</start>
                        <end>9223372036854775807</end>
                     </timeWindow>
                  </timeWindows>
               </step>
               <step>
                  <x>-1.5562968681202867</x>
                  <y>47.21808294131743</y>
                  <id>4</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>0</driveDistanceBefore>
                  <driveDistanceAfter>0</driveDistanceAfter>
                  <driveTimeBefore>0</driveTimeBefore>
                  <driveTimeAfter>0</driveTimeAfter>
               </step>
            </steps>
            <srs>epsg:4326</srs>
            <method>time</method>
         </request>
      </sch:optimRouteV3>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:optimRouteV3Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <OptimRouteResult>
            <steps>
               <step>
                  <x>-1.5291995940651142</x>
                  <y>47.19158811606974</y>
                  <id>1</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>0</driveDistanceBefore>
                  <driveDistanceAfter>1779</driveDistanceAfter>
                  <driveTimeBefore>0</driveTimeBefore>
                  <driveTimeAfter>372710</driveTimeAfter>
                  <timeWindows/>
               </step>
               <step>
                  <x>-1.5391738246474214</x>
                  <y>47.193576663578824</y>
                  <id>3</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>1779</driveDistanceBefore>
                  <driveDistanceAfter>3486</driveDistanceAfter>
                  <driveTimeBefore>372710</driveTimeBefore>
                  <driveTimeAfter>752870</driveTimeAfter>
                  <timeWindows>
                     <timeWindow>
                        <start>0</start>
                        <end>9223372036854775807</end>
                     </timeWindow>
                  </timeWindows>
               </step>
               <step>
                  <x>-1.5562968681202867</x>
                  <y>47.21808294131743</y>
                  <id>4</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>3486</driveDistanceBefore>
                  <driveDistanceAfter>3175</driveDistanceAfter>
                  <driveTimeBefore>752870</driveTimeBefore>
                  <driveTimeAfter>662230</driveTimeAfter>
                  <timeWindows/>
               </step>
               <step>
                  <x>-1.5315788375137436</x>
                  <y>47.209701524818236</y>
                  <id>2</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>3175</driveDistanceBefore>
                  <driveDistanceAfter>2713</driveDistanceAfter>
                  <driveTimeBefore>662230</driveTimeBefore>
                  <driveTimeAfter>520090</driveTimeAfter>
                  <timeWindows>
                     <timeWindow>
                        <start>0</start>
                        <end>9223372036854775807</end>
                     </timeWindow>
                  </timeWindows>
               </step>
               <step>
                  <x>-1.5405963750884433</x>
                  <y>47.19752774053115</y>
                  <id>5</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>2713</driveDistanceBefore>
                  <driveDistanceAfter>0</driveDistanceAfter>
                  <driveTimeBefore>520090</driveTimeBefore>
                  <driveTimeAfter>0</driveTimeAfter>
                  <timeWindows/>
               </step>
            </steps>
            <distanceMeters>11153</distanceMeters>
            <durationSeconds>2307</durationSeconds>
         </OptimRouteResult>
      </ns2:optimRouteV3Response>
   </soap:Body>
</soap:Envelope>
REST (POST)

Query

Query  

http://<server>/<webapp>/api/lbs/optim/route.xml

Data (XML)  

<?xml version="1.0" encoding="UTF-8"?>
<optimRouteRequestV3>
   <origin>
      <x>-1.5291995940651142</x>
      <y>47.19158811606974</y>
      <!--Optional:-->
      <id>1</id>
      <timeWindows>
         <timeWindow>
            <start>09:00</start>
            <end>20:00</end>
         </timeWindow>
      </timeWindows>
   </origin>
   <destination>
      <x>-1.5405963750884433</x>
      <y>47.19752774053115</y>
      <!--Optional:-->
      <id>5</id>
   </destination>
   <steps>
      <step>
         <x>-1.5315788375137436</x>
         <y>47.209701524818236</y>
         <id>2</id>
         <timeWindows>
            <timeWindow>
               <start>09:00</start>
               <end>20:00</end>
            </timeWindow>
         </timeWindows>
      </step>
      <step>
         <x>-1.5391738246474214</x>
         <y>47.193576663578824</y>
         <id>3</id>
      </step>
      <step>
         <x>-1.5562968681202867</x>
         <y>47.21808294131743</y>
         <id>4</id>
      </step>
   </steps>
   <method>time</method>
   <srs>epsg:4326</srs>
   <matrixProvider>SMARTROUTING</matrixProvider>
</optimRouteRequestV3>

Response

The response is always in UTF-8 format

XML Format  

<optimRouteResultV3>
   <steps>
      <step>
         <x>-1.5291995940651142</x>
         <y>47.19158811606974</y>
         <id>1</id>
         <duration>0</duration>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>0</driveDistanceBefore>
         <driveDistanceAfter>1779</driveDistanceAfter>
         <driveTimeBefore>0</driveTimeBefore>
         <driveTimeAfter>372710</driveTimeAfter>
         <timeWindows>
            <timeWindow>
               <start>0</start>
               <end>0</end>
            </timeWindow>
         </timeWindows>
      </step>
      <step>
         <x>-1.5391738246474214</x>
         <y>47.193576663578824</y>
         <id>3</id>
         <duration>0</duration>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>1779</driveDistanceBefore>
         <driveDistanceAfter>3486</driveDistanceAfter>
         <driveTimeBefore>372710</driveTimeBefore>
         <driveTimeAfter>752870</driveTimeAfter>
         <timeWindows/>
      </step>
      <step>
         <x>-1.5562968681202867</x>
         <y>47.21808294131743</y>
         <id>4</id>
         <duration>0</duration>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>3486</driveDistanceBefore>
         <driveDistanceAfter>3175</driveDistanceAfter>
         <driveTimeBefore>752870</driveTimeBefore>
         <driveTimeAfter>662230</driveTimeAfter>
         <timeWindows/>
      </step>
      <step>
         <x>-1.5315788375137436</x>
         <y>47.209701524818236</y>
         <id>2</id>
         <duration>0</duration>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>3175</driveDistanceBefore>
         <driveDistanceAfter>2713</driveDistanceAfter>
         <driveTimeBefore>662230</driveTimeBefore>
         <driveTimeAfter>520090</driveTimeAfter>
         <timeWindows>
            <timeWindow>
               <start>0</start>
               <end>0</end>
            </timeWindow>
         </timeWindows>
      </step>
      <step>
         <x>-1.5405963750884433</x>
         <y>47.19752774053115</y>
         <id>5</id>
         <duration>0</duration>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>2713</driveDistanceBefore>
         <driveDistanceAfter>0</driveDistanceAfter>
         <driveTimeBefore>520090</driveTimeBefore>
         <driveTimeAfter>0</driveTimeAfter>
         <timeWindows/>
      </step>
   </steps>
   <distanceMeters>11153</distanceMeters>
   <durationSeconds>2307</durationSeconds>
</optimRouteResultV3>

Possible responses

case of an optimization applied successfully  

<optimRouteResultV3>
   <steps>
      <step>
         <x>-1.5291995940651142</x>
         <y>47.19158811606974</y>
         <id>1</id>
         <duration>0</duration>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>0</driveDistanceBefore>
         <driveDistanceAfter>1779</driveDistanceAfter>
         <driveTimeBefore>0</driveTimeBefore>
         <driveTimeAfter>372710</driveTimeAfter>
         <timeWindows>
            <timeWindow>
               <start>0</start>
               <end>0</end>
            </timeWindow>
         </timeWindows>
      </step>
      <step>
         [...]
      </step>
   </steps>
   <distanceMeters>11153</distanceMeters>
   <durationSeconds>2307</durationSeconds>
</optimRouteResultV3>

Case of a problem with the graph: absent file, faulty filepath, etc ⇒ error with faultstring containing the description  

<soap:Fault>
    <faultcode xmlns:ns1="geoconcept.com">ns1:8</faultcode>
    <faultstring>Error in matrix computation
        Error in smartrouting
        datasource is null</faultstring>
</soap:Fault>

V2

Parameters / properties

Input

parameter description optional default

origin (optimRouteStepV2)

origin point (id,x,y)

yes

destination (optimRouteStepV2)

destination point (id,x,y)

yes

steps (optimRouteStepV2)

points to visit (id,x,y;id,x,y;…)
Several slots for visiting times in milliseconds can be specified for each point: (id,x,y,start, finish)

no

method

shortest (distance) or fastest (time) route

yes

time

matrixProvider

matrix calculation provider
globe: as the crow flies on the globe (the coordinates must be in long/lat)
euclidean: as the crow flies on the map (the coordinates must be in metres)
smartrouting: calculation on the road network by SmartRouting
nokia: calculation on the road network via a Nokia service
provided: matrix parameter

yes

smartrouting

matrix

time/distance matrix (id1,id2,temps,distance;…)

yes

srs

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

yes

wgs84

directSpeed

Default speed during utilisation of globe or euclidean matrices

yes

50

(optimRouteStepV2) steps

parameter type min/max description

id

string

0/1

point id

duration

long

1/1

duration of a visit, in milliseconds. O by default

timeWindows/timeWindow (optimTimeWindow)

long

1/1

Time windows

Time windows (optimTimeWindow)

parameter type min/max description

start

long

1/1

start of the time window, in milliseconds. 0 by default.

end

long

1/1

time window end, in milliseconds. Long.MAX_VALUE by default

Output

parameter type min/max description

steps/step

array (optimRouteStepV2)

0/unlimited

ordered points to visit

distanceMeters

long

1/1

total journey distance in meters

durationSeconds

long

1/1

total journey time in seconds

(optimRouteStepV2) steps

parameter type min/max description

id

string

0/1

point id

duration

long

1/1

duration of a visit, in milliseconds. O by default

effectiveStart

long

1/1

effective start time for a visit, in milliseconds

driveDistanceBefore

int

1/1

drive time before the step, in metres

driveDistanceAfter

int

1/1

drive distance after the step, in metres

driveTimeBefore

long

1/1

drive time before the step, in milliseconds

driveTimeAfter

long

1/1

drive time after the step, in milliseconds

timeWindows/timeWindow (optimTimeWindow)

long

1/1

Time windows

Time windows (optimTimeWindow)

parameter type min/max description

start

long

1/1

start of the time window, in milliseconds. 0 by default.

end

long

1/1

time window end, in milliseconds. Long.MAX_VALUE by default
SOAP

WSDL

http://<server>/<webapp>/api/ws/optimService?wsdl

Query

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header />
   <soapenv:Body>
      <sch:optimRouteV2>
         <request>
            <origin>
               <x>-1.5291995940651142</x>
               <y>47.19158811606974</y>
               <id>1</id>
               <duration>3600000</duration>
               <effectiveStart>0</effectiveStart>
               <driveDistanceBefore>0</driveDistanceBefore>
               <driveDistanceAfter>0</driveDistanceAfter>
               <driveTimeBefore>0</driveTimeBefore>
               <driveTimeAfter>0</driveTimeAfter>
            </origin>
            <destination>
               <x>-1.5405963750884433</x>
               <y>47.19752774053115</y>
               <id>5</id>
               <duration>3600000</duration>
               <effectiveStart>0</effectiveStart>
               <driveDistanceBefore>0</driveDistanceBefore>
               <driveDistanceAfter>0</driveDistanceAfter>
               <driveTimeBefore>0</driveTimeBefore>
               <driveTimeAfter>0</driveTimeAfter>
            </destination>
            <steps>
               <step>
                  <x>-1.5315788375137436</x>
                  <y>47.209701524818236</y>
                  <id>2</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>0</driveDistanceBefore>
                  <driveDistanceAfter>0</driveDistanceAfter>
                  <driveTimeBefore>0</driveTimeBefore>
                  <driveTimeAfter>0</driveTimeAfter>
                  <timeWindows>
                     <!--Zero or more repetitions:-->
                     <timeWindow>
                        <start>0</start>
                        <end>9223372036854775807</end>
                     </timeWindow>
                  </timeWindows>
               </step>
               <step>
                  <x>-1.5391738246474214</x>
                  <y>47.193576663578824</y>
                  <id>3</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>0</driveDistanceBefore>
                  <driveDistanceAfter>0</driveDistanceAfter>
                  <driveTimeBefore>0</driveTimeBefore>
                  <driveTimeAfter>0</driveTimeAfter>
                  <timeWindows>
                     <!--Zero or more repetitions:-->
                     <timeWindow>
                        <start>0</start>
                        <end>9223372036854775807</end>
                     </timeWindow>
                  </timeWindows>
               </step>
               <step>
                  <x>-1.5562968681202867</x>
                  <y>47.21808294131743</y>
                  <id>4</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>0</driveDistanceBefore>
                  <driveDistanceAfter>0</driveDistanceAfter>
                  <driveTimeBefore>0</driveTimeBefore>
                  <driveTimeAfter>0</driveTimeAfter>
               </step>
            </steps>
            <srs>epsg:4326</srs>
            <method>time</method>
         </request>
      </sch:optimRouteV2>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:optimRouteV2Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <OptimRouteResult>
            <steps>
               <step>
                  <x>-1.5291995940651142</x>
                  <y>47.19158811606974</y>
                  <id>1</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>0</driveDistanceBefore>
                  <driveDistanceAfter>1779</driveDistanceAfter>
                  <driveTimeBefore>0</driveTimeBefore>
                  <driveTimeAfter>372710</driveTimeAfter>
                  <timeWindows/>
               </step>
               <step>
                  <x>-1.5391738246474214</x>
                  <y>47.193576663578824</y>
                  <id>3</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>1779</driveDistanceBefore>
                  <driveDistanceAfter>3486</driveDistanceAfter>
                  <driveTimeBefore>372710</driveTimeBefore>
                  <driveTimeAfter>752870</driveTimeAfter>
                  <timeWindows>
                     <timeWindow>
                        <start>0</start>
                        <end>9223372036854775807</end>
                     </timeWindow>
                  </timeWindows>
               </step>
               <step>
                  <x>-1.5562968681202867</x>
                  <y>47.21808294131743</y>
                  <id>4</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>3486</driveDistanceBefore>
                  <driveDistanceAfter>3175</driveDistanceAfter>
                  <driveTimeBefore>752870</driveTimeBefore>
                  <driveTimeAfter>662230</driveTimeAfter>
                  <timeWindows/>
               </step>
               <step>
                  <x>-1.5315788375137436</x>
                  <y>47.209701524818236</y>
                  <id>2</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>3175</driveDistanceBefore>
                  <driveDistanceAfter>2713</driveDistanceAfter>
                  <driveTimeBefore>662230</driveTimeBefore>
                  <driveTimeAfter>520090</driveTimeAfter>
                  <timeWindows>
                     <timeWindow>
                        <start>0</start>
                        <end>9223372036854775807</end>
                     </timeWindow>
                  </timeWindows>
               </step>
               <step>
                  <x>-1.5405963750884433</x>
                  <y>47.19752774053115</y>
                  <id>5</id>
                  <duration>3600000</duration>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>2713</driveDistanceBefore>
                  <driveDistanceAfter>0</driveDistanceAfter>
                  <driveTimeBefore>520090</driveTimeBefore>
                  <driveTimeAfter>0</driveTimeAfter>
                  <timeWindows/>
               </step>
            </steps>
            <distanceMeters>11153</distanceMeters>
            <durationSeconds>2307</durationSeconds>
         </OptimRouteResult>
      </ns2:optimRouteV2Response>
   </soap:Body>
</soap:Envelope>
REST (POST)

Query

Query  

http://<server>/<webapp>/api/lbs/optim/route.xml

Data (XML)  

<?xml version="1.0" encoding="UTF-8"?>
<optimRouteRequestV2>
   <origin>
      <x>-1.5291995940651142</x>
      <y>47.19158811606974</y>
      <!--Optional:-->
      <id>1</id>
      <timeWindows>
         <timeWindow>
            <start>09:00</start>
            <end>20:00</end>
         </timeWindow>
      </timeWindows>
   </origin>
   <destination>
      <x>-1.5405963750884433</x>
      <y>47.19752774053115</y>
      <!--Optional:-->
      <id>5</id>
   </destination>
   <steps>
      <step>
         <x>-1.5315788375137436</x>
         <y>47.209701524818236</y>
         <id>2</id>
         <timeWindows>
            <timeWindow>
               <start>09:00</start>
               <end>20:00</end>
            </timeWindow>
         </timeWindows>
      </step>
      <step>
         <x>-1.5391738246474214</x>
         <y>47.193576663578824</y>
         <id>3</id>
      </step>
      <step>
         <x>-1.5562968681202867</x>
         <y>47.21808294131743</y>
         <id>4</id>
      </step>
   </steps>
   <method>time</method>
   <srs>epsg:4326</srs>
   <matrixProvider>SMARTROUTING</matrixProvider>
</optimRouteRequestV2>

Response

The response is always in UTF-8 format

XML Format  

<optimRouteResultV2>
   <steps>
      <step>
         <x>-1.5291995940651142</x>
         <y>47.19158811606974</y>
         <id>1</id>
         <duration>0</duration>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>0</driveDistanceBefore>
         <driveDistanceAfter>1779</driveDistanceAfter>
         <driveTimeBefore>0</driveTimeBefore>
         <driveTimeAfter>372710</driveTimeAfter>
         <timeWindows>
            <timeWindow>
               <start>0</start>
               <end>0</end>
            </timeWindow>
         </timeWindows>
      </step>
      <step>
         <x>-1.5391738246474214</x>
         <y>47.193576663578824</y>
         <id>3</id>
         <duration>0</duration>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>1779</driveDistanceBefore>
         <driveDistanceAfter>3486</driveDistanceAfter>
         <driveTimeBefore>372710</driveTimeBefore>
         <driveTimeAfter>752870</driveTimeAfter>
         <timeWindows/>
      </step>
      <step>
         <x>-1.5562968681202867</x>
         <y>47.21808294131743</y>
         <id>4</id>
         <duration>0</duration>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>3486</driveDistanceBefore>
         <driveDistanceAfter>3175</driveDistanceAfter>
         <driveTimeBefore>752870</driveTimeBefore>
         <driveTimeAfter>662230</driveTimeAfter>
         <timeWindows/>
      </step>
      <step>
         <x>-1.5315788375137436</x>
         <y>47.209701524818236</y>
         <id>2</id>
         <duration>0</duration>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>3175</driveDistanceBefore>
         <driveDistanceAfter>2713</driveDistanceAfter>
         <driveTimeBefore>662230</driveTimeBefore>
         <driveTimeAfter>520090</driveTimeAfter>
         <timeWindows>
            <timeWindow>
               <start>0</start>
               <end>0</end>
            </timeWindow>
         </timeWindows>
      </step>
      <step>
         <x>-1.5405963750884433</x>
         <y>47.19752774053115</y>
         <id>5</id>
         <duration>0</duration>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>2713</driveDistanceBefore>
         <driveDistanceAfter>0</driveDistanceAfter>
         <driveTimeBefore>520090</driveTimeBefore>
         <driveTimeAfter>0</driveTimeAfter>
         <timeWindows/>
      </step>
   </steps>
   <distanceMeters>11153</distanceMeters>
   <durationSeconds>2307</durationSeconds>
</optimRouteResultV2>

Possible responses

case of an optimization applied successfully  

<optimRouteResultV2>
   <steps>
      <step>
         <x>-1.5291995940651142</x>
         <y>47.19158811606974</y>
         <id>1</id>
         <duration>0</duration>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>0</driveDistanceBefore>
         <driveDistanceAfter>1779</driveDistanceAfter>
         <driveTimeBefore>0</driveTimeBefore>
         <driveTimeAfter>372710</driveTimeAfter>
         <timeWindows>
            <timeWindow>
               <start>0</start>
               <end>0</end>
            </timeWindow>
         </timeWindows>
      </step>
      <step>
         [...]
      </step>
   </steps>
   <distanceMeters>11153</distanceMeters>
   <durationSeconds>2307</durationSeconds>
</optimRouteResultV2>

Case of a problem with the graph: absent file, faulty filepath, etc ⇒ error with faultstring containing the description  

<soap:Fault>
    <faultcode xmlns:ns1="geoconcept.com">ns1:8</faultcode>
    <faultstring>Error in matrix computation
        Error in smartrouting
        datasource is null</faultstring>
</soap:Fault>

V1

Parameters / properties

Input

parameter description optional default

origin

origin point (id,x,y)

yes

destination

destination point (id,x,y)

yes

steps

points to visit (id,x,y;id,x,y;…)
Visiting times in milliseconds can be specified for each point: (id,x,y,start, finish)

no

method

shortest (distance) or fastest (time) route

yes

time

matrixProvider

matrix calculation provider
globe: as the crow flies on the globe (the coordinates must be in long/lat)
euclidean: as the crow flies on the map (the coordinates must be in metres)
smartrouting: calculation on the road network by SmartRouting
nokia: calculation on the road network via a Nokia service
provided: matrix parameter

yes

smartrouting

matrix

time/distance matrix (id1,id2,temps,distance;…)

yes

srs

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

yes

wgs84

directSpeed

Default speed during utilisation of globe or euclidean matrices

yes

50

Output

parameter type min/max description

steps/step

array (optimRouteStep)

0/unlimited

ordered points to visit

totalDistance

long

1/1

total journey distance in meters

totalTime

long

1/1

total journey time in minutes

Steps (optimRouteStep)

parameter type min/max description

id

string

0/1

point id

duration

long

1/1

duration of a visit, in milliseconds. O by default

timeWindowStart

long

1/1

start of the time window, in milliseconds. 0 by default.

timeWindowEnd

long

1/1

time window end, in milliseconds. Long.MAX_VALUE by default

effectiveStart

long

1/1

effective start time for a visit, in milliseconds

driveDistanceBefore

int

1/1

drive time before the step, in metres

driveDistanceAfter

int

1/1

drive distance after the step, in metres

driveTimeBefore

long

1/1

drive time before the step, in milliseconds

driveTimeAfter

long

1/1

drive time after the step, in milliseconds
SOAP

WSDL

http://<server>/<webapp>/api/ws/optimService?wsdl

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:optimRoute>
         <!--Optional:-->
         <request>
            <!--Optional:-->
            <origin>
               <x>-1.55306</x>
               <y>47.21812</y>
               <!--Optional:-->
               <id>0</id>
               <duration>0</duration>
               <timeWindowStart>0</timeWindowStart>
               <timeWindowEnd>0</timeWindowEnd>
               <effectiveStart>0</effectiveStart>
               <driveDistanceBefore>0</driveDistanceBefore>
               <driveDistanceAfter>0</driveDistanceAfter>
               <driveTimeBefore>0</driveTimeBefore>
               <driveTimeAfter>0</driveTimeAfter>
            </origin>
            <!--Optional:-->
            <destination>
               <x>-2.2164099</x>
               <y>47.2806206</y>
               <!--Optional:-->
               <id>1</id>
               <duration>0</duration>
               <timeWindowStart>0</timeWindowStart>
               <timeWindowEnd>0</timeWindowEnd>
               <effectiveStart>0</effectiveStart>
               <driveDistanceBefore>0</driveDistanceBefore>
               <driveDistanceAfter>0</driveDistanceAfter>
               <driveTimeBefore>0</driveTimeBefore>
               <driveTimeAfter>0</driveTimeAfter>
            </destination>
            <!--Optional:-->
            <steps>
               <!--Zero or more repetitions:-->
               <step>
                  <x>-2.02616</x>
                  <y>47.2835503</y>
                  <!--Optional:-->
               <id>2</id>
               <duration>0</duration>
               <timeWindowStart>0</timeWindowStart>
               <timeWindowEnd>0</timeWindowEnd>
               <effectiveStart>0</effectiveStart>
               <driveDistanceBefore>0</driveDistanceBefore>
               <driveDistanceAfter>0</driveDistanceAfter>
               <driveTimeBefore>0</driveTimeBefore>
               <driveTimeAfter>0</driveTimeAfter>
               </step>
            </steps>
            <!--Optional:-->
            <srs>wgs84</srs>
            <!--Optional:-->
            <method>time</method>
            <!--Optional:-->
            <matrixProvider>SMARTROUTING</matrixProvider>
            <!--Optional:-->
            <matrix>
               <!--Optional:-->
               <elements>
                  <!--Zero or more repetitions:-->
                  <element>
                     <!--Optional:-->
                     <origin></origin>
                     <!--Optional:-->
                     <destination></destination>
                     <time>1</time>
                     <distance>1</distance>
                  </element>
               </elements>
            </matrix>
            <directSpeed>0</directSpeed>
         </request>
      </sch:optimRoute>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:optimRouteResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
         <OptimRouteResult>
            <steps>
               <step>
                  <x>-1.55306</x>
                  <y>47.21812</y>
                  <id>0</id>
                  <duration>0</duration>
                  <timeWindowStart>0</timeWindowStart>
                  <timeWindowEnd>0</timeWindowEnd>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>0</driveDistanceBefore>
                  <driveDistanceAfter>47085</driveDistanceAfter>
                  <driveTimeBefore>0</driveTimeBefore>
                  <driveTimeAfter>3139890</driveTimeAfter>
               </step>
               <step>
                  <x>-2.02616</x>
                  <y>47.2835503</y>
                  <id>2</id>
                  <duration>0</duration>
                  <timeWindowStart>0</timeWindowStart>
                  <timeWindowEnd>0</timeWindowEnd>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>47085</driveDistanceBefore>
                  <driveDistanceAfter>22124</driveDistanceAfter>
                  <driveTimeBefore>3139890</driveTimeBefore>
                  <driveTimeAfter>1488050</driveTimeAfter>
               </step>
               <step>
                  <x>-2.2164099</x>
                  <y>47.2806206</y>
                  <id>1</id>
                  <duration>0</duration>
                  <timeWindowStart>0</timeWindowStart>
                  <timeWindowEnd>0</timeWindowEnd>
                  <effectiveStart>0</effectiveStart>
                  <driveDistanceBefore>22124</driveDistanceBefore>
                  <driveDistanceAfter>0</driveDistanceAfter>
                  <driveTimeBefore>1488050</driveTimeBefore>
                  <driveTimeAfter>0</driveTimeAfter>
               </step>
            </steps>
            <totalDistance>69209</totalDistance>
            <totalTime>77</totalTime>
         </OptimRouteResult>
      </ns2:optimRouteResponse>
   </soap:Body>
</soap:Envelope>
REST (POST)

Query

Query  

http://<server>/<webapp>/api/lbs/optim/route.xml

Data (XML)  

<?xml version="1.0" encoding="UTF-8"?>
<optimRouteRequest>
        <steps>
                <step>
                        <x>-1.55306</x>
                        <y>47.21812</y>
                        <id>0</id>
                </step>
                <step>
                        <x>-2.2164099</x>
                        <y>47.2806206</y>
                        <id>1</id>
                </step>
                <step>
                        <x>-2.02616</x>
                        <y>47.2835503</y>
                        <id>2</id>
                </step>
        </steps>
        <method>time</method>
        <srs>wgs84</srs>
        <matrixProvider>SMARTROUTING</matrixProvider>
</optimRouteRequest>

Response

The response is always in UTF-8 format

XML Format  

<optimRouteResult>
   <steps>
      <step>
         <x>-2.02616</x>
         <y>47.2835503</y>
         <id>2</id>
         <duration>0</duration>
         <timeWindowStart>0</timeWindowStart>
         <timeWindowEnd>9223372036854775807</timeWindowEnd>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>0</driveDistanceBefore>
         <driveDistanceAfter>22124</driveDistanceAfter>
         <driveTimeBefore>0</driveTimeBefore>
         <driveTimeAfter>1488050</driveTimeAfter>
      </step>
      <step>
         <x>-2.2164099</x>
         <y>47.2806206</y>
         <id>1</id>
         <duration>0</duration>
         <timeWindowStart>0</timeWindowStart>
         <timeWindowEnd>9223372036854775807</timeWindowEnd>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>22124</driveDistanceBefore>
         <driveDistanceAfter>63139</driveDistanceAfter>
         <driveTimeBefore>1488050</driveTimeBefore>
         <driveTimeAfter>2992570</driveTimeAfter>
      </step>
      <step>
         <x>-1.55306</x>
         <y>47.21812</y>
         <id>0</id>
         <duration>0</duration>
         <timeWindowStart>0</timeWindowStart>
         <timeWindowEnd>9223372036854775807</timeWindowEnd>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>63139</driveDistanceBefore>
         <driveDistanceAfter>0</driveDistanceAfter>
         <driveTimeBefore>2992570</driveTimeBefore>
         <driveTimeAfter>0</driveTimeAfter>
      </step>
   </steps>
   <totalDistance>85263</totalDistance>
   <totalTime>74</totalTime>
</optimRouteResult>

REST (GET)

Query

JSON query  

http://<server>/<webapp>/api/lbs/optim/route.json?steps=0,-1.55306,47.21812;1,-2.2164099,47.2806206;2,-2.02616,47.2835503&method=time&srs=wgs84

JSON-P query  

http://<server>/<webapp>/api/lbs/optim/route.json?steps=0,-1.55306,47.21812;1,-2.2164099,47.2806206;2,-2.02616,47.2835503&method=time&srs=wgs84&callback=myCallback

XML query  

http://<server>/<webapp>/api/lbs/optim/route.xml?steps=0,-1.55306,47.21812;1,-2.2164099,47.2806206;2,-2.02616,47.2835503&method=time&srs=wgs84

Response

The response is always in UTF-8 format

JSON format  

{
   "steps":    [
            {
         "x": -2.02616, "y": 47.2835503, "id": "2",
         "duration": 0, "timeWindowStart": 0, "timeWindowEnd": 9223372036854775807, "effectiveStart": 0,
         "driveDistanceBefore": 0, "driveDistanceAfter": 22124, "driveTimeBefore": 0, "driveTimeAfter": 1488050
      },
            {
         "x": -2.2164099, "y": 47.2806206, "id": "1",
         "duration": 0, "timeWindowStart": 0, "timeWindowEnd": 9223372036854775807, "effectiveStart": 0,
         "driveDistanceBefore": 22124, "driveDistanceAfter": 63139, "driveTimeBefore": 1488050, "driveTimeAfter": 2992570
      },
            {
         "x": -1.55306, "y": 47.21812, "id": "0",
         "duration": 0, "timeWindowStart": 0, "timeWindowEnd": 9223372036854775807, "effectiveStart": 0,
         "driveDistanceBefore": 63139, "driveDistanceAfter": 0, "driveTimeBefore": 2992570, "driveTimeAfter": 0
      }
   ],
   "totalDistance": 85263,
   "totalTime": 74
}

JSON-P format  

myCallback({
   "steps":    [
            {
         "x": -2.02616, "y": 47.2835503, "id": "2",
         "duration": 0, "timeWindowStart": 0, "timeWindowEnd": 9223372036854775807, "effectiveStart": 0,
         "driveDistanceBefore": 0, "driveDistanceAfter": 22124, "driveTimeBefore": 0, "driveTimeAfter": 1488050
      },
            {
         "x": -2.2164099, "y": 47.2806206, "id": "1",
         "duration": 0, "timeWindowStart": 0, "timeWindowEnd": 9223372036854775807, "effectiveStart": 0,
         "driveDistanceBefore": 22124, "driveDistanceAfter": 63139, "driveTimeBefore": 1488050, "driveTimeAfter": 2992570
      },
            {
         "x": -1.55306, "y": 47.21812, "id": "0",
         "duration": 0, "timeWindowStart": 0, "timeWindowEnd": 9223372036854775807, "effectiveStart": 0,
         "driveDistanceBefore": 63139, "driveDistanceAfter": 0, "driveTimeBefore": 2992570, "driveTimeAfter": 0
      }
   ],
   "totalDistance": 85263,
   "totalTime": 74
});

XML Format  

<optimRouteResult>
   <steps>
      <step>
         <x>-2.02616</x>
         <y>47.2835503</y>
         <id>2</id>
         <duration>0</duration>
         <timeWindowStart>0</timeWindowStart>
         <timeWindowEnd>9223372036854775807</timeWindowEnd>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>0</driveDistanceBefore>
         <driveDistanceAfter>22124</driveDistanceAfter>
         <driveTimeBefore>0</driveTimeBefore>
         <driveTimeAfter>1488050</driveTimeAfter>
      </step>
      <step>
         <x>-2.2164099</x>
         <y>47.2806206</y>
         <id>1</id>
         <duration>0</duration>
         <timeWindowStart>0</timeWindowStart>
         <timeWindowEnd>9223372036854775807</timeWindowEnd>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>22124</driveDistanceBefore>
         <driveDistanceAfter>63139</driveDistanceAfter>
         <driveTimeBefore>1488050</driveTimeBefore>
         <driveTimeAfter>2992570</driveTimeAfter>
      </step>
      <step>
         <x>-1.55306</x>
         <y>47.21812</y>
         <id>0</id>
         <duration>0</duration>
         <timeWindowStart>0</timeWindowStart>
         <timeWindowEnd>9223372036854775807</timeWindowEnd>
         <effectiveStart>0</effectiveStart>
         <driveDistanceBefore>63139</driveDistanceBefore>
         <driveDistanceAfter>0</driveDistanceAfter>
         <driveTimeBefore>2992570</driveTimeBefore>
         <driveTimeAfter>0</driveTimeAfter>
      </step>
   </steps>
   <totalDistance>85263</totalDistance>
   <totalTime>74</totalTime>
</optimRouteResult>

Possible responses

case of an optimization applied successfully  

<ns2:optimRouteResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
 <OptimRouteResult>
    <steps>
       <step>
          <x>-1.55306</x>
          <y>47.21812</y>
          <id>0</id>
          <duration>0</duration>
          <timeWindowStart>0</timeWindowStart>
          <timeWindowEnd>0</timeWindowEnd>
          <effectiveStart>0</effectiveStart>
          <driveDistanceBefore>0</driveDistanceBefore>
          <driveDistanceAfter>47085</driveDistanceAfter>
          <driveTimeBefore>0</driveTimeBefore>
          <driveTimeAfter>3139890</driveTimeAfter>
       </step>
       <step>
            ...
       </step>
    </steps>
    <totalDistance>69209</totalDistance>
    <totalTime>77</totalTime>
 </OptimRouteResult>
</ns2:optimRouteResponse>

Case of a problem with the graph: absent file, faulty filepath, etc ⇒ error with faultstring containing the description  

<soap:Fault>
    <faultcode xmlns:ns1="geoconcept.com">ns1:8</faultcode>
    <faultstring>Error in matrix computation
        Error in smartrouting
        datasource is null</faultstring>
</soap:Fault>

FAQ

1. Can you force a start and/or arrival step in the calculation of a route?
2. How can you specify, for each step, a visit duration and a visit time window?

1.

Can you force a start and/or arrival step in the calculation of a route?

Yes, you just have to use the origin and / or destination parameters respectively. The journey between the steps route stops is optimised taking into account any operational constraints, and without taking into account any logistical constraint (departure from home, arrival in a depot, ..;).

2.

How can you specify, for each step, a visit duration and a visit time window?

using the duration parameter (to indicate the duration set aside for a visit) and the timeWindowStart and timeWindowEnd parameters (to specify the start and finish time for a visit).

Prev  Up  Next
  Home