Route calculation

Basic principles

This web service calculates an itinerary between two points and returns a full route sheet. Adding intermediate steps is an option for the user, in the context of the configured graph or network, the name of which has been specified in the interface.

Availability

This web service is available at all times with Geoconcept Web and a graph or network.

Version change

Earlier versions of the web service are conserved in Geoconcept Web to ensure compatibility with earlier software developments. We reommend using the most recent version.

Changes in relation to v6

Addition of the "formatItems" and "fields" parameters.

Changes in relation to v5

Addition of the "maxCost", "timeOut" and "computeOptions" parameters.
Addition to the "nodes" snapMethod of snap to the nearest nodes.
"compressedgeometry" and "compressedsimplifiedgeometry" formats have been added, with 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.
Addition of the "tollcost" format, requires an access license to the HERE platform.

Changes in relation to v4

Addition of the notion of node, faster, to snap to graph nodes rather than to geographic coordinates. Addition of the following elements: "originNode", "destinationNode", "waypointNodes", "node" in the format parameter and "nodes" in the snapMethod parameter.
Addition in the response of the following items: "originNode", "destinationNode", "waypointNodes" and "carbonFootprint".
Addition of the "avoidArea" and "configName" parameters.

Changes in relation to v3

Addition of the "snapMethod" parameter
Deletion of the "projection" parameter, replaced by "srs"
Deletion of the "RejectFlags" parameter, replaced by "exclusions"
Change in the parameter type for the "distanceMeters" and "durationSeconds" parameters from String/Double to Double
The "geometryWkt" and "simplifiedWkt" parameters have been renamed "wktGeometry" and "wktSimplifiedGeometry" respectively
The "navInstruvtion" parameter has been renamed "navigationInstruction"
In RouteResultV3, addition of the "srs" parameter
The "elapsedTimeSeconds" parameter has been renamed "durationSeconds" and its type has been changed from String to Double
The "coordinates" parameter has been renamed "location"

Changes in relation to V2

Addition of the "timeLine" parameter
Deletion of the "map" and "applyMapPrecisionOut" parameters
The "distance" and "duration" parameters have been renamed "distanceMeters" and "durationSeconds" respectivly

V6

Parameters / properties

Input

parameter	description	optional	default
origin	Start point coordinates. The longitude and latitude coordinates are separated by , characters.	no
originNode	Start node. Care: a physical node does not have the same ID in another graph.	yes *
destination	Finish point coordinates. The longitude and latitude coordinates are separated by the , character	no
destinationNode	Arrival node. Care: a physical node does not have the same ID in another graph.	yes *
waypoints	Coordinates for route stops. Each pair of coordinates for a stop is framed by the <waypoint> tag The longitude and latitude coordinates are separated by the , character	yes
waypointNodes	Step nodes. Each pair of coordinates for a step is framed by the <waypointNode> tag Care: a physical node does not have the same ID in another graph.	yes *
method	the shortest (distance) and fastest (time) route	yes	time
format	- standard: result = route summary / waypoints / geometry in wkt format / simplified geometry in wkt format / list of concatenated segments (without geometries) - extended: result = route summary / waypoints / simplified geometry in wkt format / list of non-concatenated segments (with geometries) - summary: result = route summary - geometry: result = route summary / waypoints / geometry in wkt format - simplifiedgeometry: result = route summary / waypoints / simplified geometry in wkt format - geometries: result = route summary / waypoints / geometry in wkt format / simplified geometry in wkt format - brief: result = route summary / list of segments with duration and distance - standardext: result = route summary / waypoints / list of concatenated segments with duration and distance and geometry - compressedgeometry: result = route summary / waypoints / compressed geometry with polyline encoding - compressedsimplifiedgeometry: result = route summary / waypoints / simplified compressed geometry with polyline encoding - node: result = route summary + Id of snapped nodes - completegeometry : result = route summary / waypoints / eometry in wkt format / list of concatenated segments with geometry in wkt format+ - compresscompletegeometry : result = route summary / waypoints / compressed geometry with polyline encoding / list of concatenated segments and compressed geometry with polyline encoding - tollcost : résultat = route summary / cost of tolls. The cost is calculated according to the type of vehicle defined configName as well as the date/time of departure of the route startDateTime - custom: returns the list of items declared in the customFormat parameter.	yes	standard
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes
tolerance	Tolerance distance (in metres) for the geometry simplification.	yes
graphName (depreciated)	Name of the graph to use This parameter is omitted if the configName parameter is used.	yes
startDateTime	Start 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 start date of 21 January 2014, at 9.00am in Paris. Caution: the + character can be misinterpreted by browsers, so in this case, it should be replaced by %2B.	yes
profileId (depreciated)	Vehicle identifier (saved under vehicle profiles) This parameter is omitted if the configName parameter is used.	yes
profileName (depreciated)	Vehicle profile (saved in the vehicle profiles) This parameter is omitted if the configName parameter is used.	yes
exclusions	List of restriction rules to use, separated by the ; character (Example: Toll, Tunnel, Bridge)	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 path, connectable to the network. For example, on a highway, the returned position is the last exit or service area before the requested position.	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
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 (defined in Geoconcept Web - Administration / Tools / Road graphs) This replaces the use of graphName, profileId and profileName	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" - fuelType: fuel type used for calculating the carbon footprint for the route. Values available are: "UndefinedFuelType", "NoFuel", "Diesel", "UnleadedFuel", "LGP" et "CustomFuelType". Usage : "fuelType:Diesel" - averageConsumption: average consumption in litres for 100 kilometers. Use as follows: "averageConsumption:6.45" - customAverageCO2UnitEmission: defines the carbon footprint in kilograms per litre. Use as follows: "customAverageCO2UnitEmission:2.724" - snapSpeed: snap-to-graph speed in kilometers per hour. Use as follows: "snapSpeed:10"	yes
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
formatItems	List of available format items, if the format parameter 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	yes
fields	List of fields to be displayed as a result of each segment (for the 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	yes

(M18) Available from version M18 and later versions of graphs supplied by GEOCONCEPT SAS.

Output

Route (routeResultV6)

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 metres.
durationSeconds	double	0/1	Total duration of the route in seconds.
waypoints	string	0/1	Waypoints (BoundingBox) for the route geometry.
wktGeometry	string	0/1	Geometry of the route in WKT format
wktSimplified	string	0/1	Simplified geometry in WKT format.
leg (or legs in JSON / JSON-P)	subRouteV5 (or array in JSON / JSON-P)	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
timeLineItem	timeLineItemV5 (or an array in JSON / JSON-P)	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)
tollCost	Array de tollCost	0/unlimited	Toll cost information (filled in if format=tollCost).
fieldsNames	Array de fields	0/unlimited	list of requested fields with the parameter field.

Route section (subRouteV6)

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 metres.
durationSeconds	double	0/1	Duration of the route segment in seconds.
step or (or steps in JSON / JSON-P)	segmentV5 (or array in JSON / JSON-P)	0/unlimited	List of component segments in the route segments

Route segment (segmentV6)

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 metres.
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.
point	string	0/unlimited	List of coordinates separated by the , character

Route position (timeLineItemV6)

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 metres up to this position.
location	string	0/1	Coordinates of the position.

TollCost (tollCost)

parameter	type	min/max	description
amount	double	0/1	Total cost of tolls.
currency	string	0/1	Currency.
costsByCountry	Array de costsByCountry	0/unlimited	List of toll costs by country.

Cost of tolls per country (costsByCountry)

parameter	type	min/max	description
amount	double	0/1	Cost of tolls.
country	string	0/1	Country code (3-letter ISO country code).

SOAP

WSDL

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

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:routeV6>
         <!--Optional:-->
         <request>
            <origin>
               <x>-1.351448</x>
               <y>47.446923</y>
            </origin>
            <!--Optional:-->
            <originNode></originNode>
            <destination>
               <x>-1.34529</x>
               <y>47.4479931</y>
            </destination>
            <!--Optional:-->
            <destinationNode></destinationNode>
            <!--Optional:-->
            <waypoints>
               <!--Zero or more repetitions:-->
               <waypoint>
                  <x>-1.34981</x>
                  <y>47.44837</y>
               </waypoint>
            </waypoints>
            <!--Optional:-->
            <waypointNodes>
               <!--Zero or more repetitions:-->
               <waypointNode></waypointNode>
            </waypointNodes>
            <!--Optional:-->
            <srs>epsg:4326</srs>
            <!--Optional:-->
            <method>time</method>
            <!--Optional:-->
            <format>STANDARD</format>
            <!--Optional:-->
            <tolerance>0.</tolerance>
            <!--Optional:-->
            <graphName></graphName>
            <!--Optional:-->
            <startDateTime></startDateTime>
            <!--Optional:-->
            <profileId></profileId>
            <!--Optional:-->
            <profileName></profileName>
            <!--Optional:-->
            <exclusions>
               <!--Zero or more repetitions:-->
               <exclusion></exclusion>
            </exclusions>
            <!--Optional:-->
            <timeLine>
               <!--Zero or more repetitions:-->
               <timeLineItem></timeLineItem>
            </timeLine>
            <!--Optional:-->
            <snapMethod></snapMethod>
            <!--Optional:-->
            <avoidArea></avoidArea>
            <!--Optional:-->
            <computeOptions></computeOptions>
            <!--Optional:-->
            <timeOut></timeOut>
            <!--Optional:-->
            <configName></configName>
         </request>
      </sch:routeV6>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:routeV6Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <RouteResult>
            <status>OK</status>
            <distance>640 m</distance>
            <duration>0:02:06</duration>
            <distanceMeters>639.97</distanceMeters>
            <durationSeconds>126.88</durationSeconds>
            <bounds>-1.351448,47.446922;-1.345263,47.44848</bounds>
            <wktGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, [...] ,  -1.34529 47.447993)</wktGeometry>
            <wktSimplifiedGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922,  [...] , -1.34529 47.447993)</wktSimplifiedGeometry>
            <leg>
               <distance>233 m</distance>
               <duration>0:00:46</duration>
               <distanceMeters>233.1</distanceMeters>
               <durationSeconds>46.28</durationSeconds>
               <step>
                  <distance>139 m</distance>
                  <duration>0:00:29</duration>
                  <distanceMeters>138.59</distanceMeters>
                  <durationSeconds>29.28</durationSeconds>
                  <name>RUE LA FONTAINE BRUNEAU</name>
               </step>
               <step>
                  <distance>91 m</distance>
                  <duration>0:00:16</duration>
                  <distanceMeters>91.33</distanceMeters>
                  <durationSeconds>16.43</durationSeconds>
                  <navigationInstruction>FR</navigationInstruction>
                  <name>RUE DES SAULES</name>
               </step>
               <step>
                  <distance>3 m</distance>
                  <duration>0:00:00</duration>
                  <distanceMeters>3.18</distanceMeters>
                  <durationSeconds>0.57</durationSeconds>
                  <navigationInstruction>round_about_entry</navigationInstruction>
                  <name />
               </step>
            </leg>
            <leg>
               <distance>407 m</distance>
               <duration>0:01:20</duration>
               <distanceMeters>406.87</distanceMeters>
               <durationSeconds>80.6</durationSeconds>
               <step>
                  <distance>18 m</distance>
                  <duration>0:00:03</duration>
                  <distanceMeters>17.64</distanceMeters>
                  <durationSeconds>3.17</durationSeconds>
                  <name />
               </step>
               <step>
                  <distance>67 m</distance>
                  <duration>0:00:15</duration>
                  <distanceMeters>66.62</distanceMeters>
                  <durationSeconds>15.05</durationSeconds>
                  <navigationInstruction>round_about_exit</navigationInstruction>
                  <name>RUE DES FOURS</name>
               </step>
               <step>
                  <distance>36 m</distance>
                  <duration>0:00:08</duration>
                  <distanceMeters>35.74</distanceMeters>
                  <durationSeconds>8.57</durationSeconds>
                  <navigationInstruction>F</navigationInstruction>
                  <name>PLACE DE L'ÉGLISE</name>
               </step>
               <step>
                  <distance>72 m</distance>
                  <duration>0:00:15</duration>
                  <distanceMeters>72.25</distanceMeters>
                  <durationSeconds>15.24</durationSeconds>
                  <navigationInstruction>F</navigationInstruction>
                  <name>RUE DES PRESSOIRS</name>
               </step>
               <step>
                  <distance>26 m</distance>
                  <duration>0:00:04</duration>
                  <distanceMeters>26.02</distanceMeters>
                  <durationSeconds>4.68</durationSeconds>
                  <navigationInstruction>round_about_entry</navigationInstruction>
                  <name />
               </step>
               <step>
                  <distance>183 m</distance>
                  <duration>0:00:32</duration>
                  <distanceMeters>182.84</distanceMeters>
                  <durationSeconds>32.91</durationSeconds>
                  <navigationInstruction>round_about_exit</navigationInstruction>
                  <name>RUE DU BOURG DRAPÉ</name>
               </step>
               <step>
                  <distance>6 m</distance>
                  <duration>0:00:00</duration>
                  <distanceMeters>5.76</distanceMeters>
                  <durationSeconds>0.98</durationSeconds>
                  <navigationInstruction>FR</navigationInstruction>
                  <name>RUE DE LA CURE</name>
               </step>
            </leg>
            <srs>epsg:4326</srs>
            <carbonFootprint>0.0</carbonFootprint>
         </RouteResult>
      </ns2:routeV6Response>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/route/v6.json?origin=-1.351448,47.446923&destination=-1.34529,47.4479931&waypoints=-1.34981,47.44837

JSON-P query

http://<server>/<webapp>/api/lbs/route/v6.json?origin=-1.351448,47.446923&destination=-1.34529,47.4479931&waypoints=-1.34981,47.44837&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/route/v6.xml?origin=-1.351448,47.446923&destination=-1.34529,47.4479931&waypoints=-1.34981,47.44837

Response

The response is always in UTF-8 format.

JSON format

{
    "message": null,
    "status": "OK",
    "distance": "640 m",
    "duration": "0:02:09",
    "distanceMeters": 639.95,
    "durationSeconds": 129.48,
    "bounds": "-1.351448,47.446922;-1.345263,47.44848",
    "wktGeometry": "LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
    "wktSimplifiedGeometry":"LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
    "legs": [
        {
            "distance": "233 m",
            "duration": "0:00:46",
            "distanceMeters": 233.09,
            "durationSeconds": 46.84,
            "steps": [
                {
                    "distance": "139 m",
                    "duration": "0:00:29",
                    "distanceMeters": 138.59,
                    "durationSeconds": 29.83,
                    "navigationInstruction": null,
                    "name": "RUE LA FONTAINE BRUNEAU",
                    "points": []
                },
                {
                    [...]
                }
            ]
        },
        {
            "distance": "407 m",
            "duration": "0:01:22",
            "distanceMeters": 406.86,
            "durationSeconds": 82.64,
            "steps": [
                {
                    "distance": "18 m",
                    "duration": "0:00:03",
                    "distanceMeters": 17.63,
                    "durationSeconds": 3.18,
                    "navigationInstruction": null,
                    "name": "",
                    "points": []
                },
                {
                   [...]
                }
            ]
        }
    ],
    "startDateTime": null,
    "finishDateTime": null,
    "srs": null,
    "originNode": null,
    "waypointNodes": null,
    "destinationNode": null,
    "carbonFootprint": 0.195038864105688
}

JSON-P format

myCallback(
    {
        "message": null,
        "status": "OK",
        "distance": "640 m",
        "duration": "0:02:09",
        "distanceMeters": 639.95,
        "durationSeconds": 129.48,
        "bounds": "-1.351448,47.446922;-1.345263,47.44848",
        "wktGeometry": "LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
        "wktSimplifiedGeometry":"LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
        "legs": [
            {
                "distance": "233 m",
                "duration": "0:00:46",
                "distanceMeters": 233.09,
                "durationSeconds": 46.84,
                "steps": [
                    {
                        "distance": "139 m",
                        "duration": "0:00:29",
                        "distanceMeters": 138.59,
                        "durationSeconds": 29.83,
                        "navigationInstruction": null,
                        "name": "RUE LA FONTAINE BRUNEAU",
                        "points": []
                    },
                    {
                        [...]
                    }
                ]
            },
            {
                "distance": "407 m",
                "duration": "0:01:22",
                "distanceMeters": 406.86,
                "durationSeconds": 82.64,
                "steps": [
                    {
                        "distance": "18 m",
                        "duration": "0:00:03",
                        "distanceMeters": 17.63,
                        "durationSeconds": 3.18,
                        "navigationInstruction": null,
                        "name": "",
                        "points": []
                    },
                    {
                       [...]
                    }
                ]
            }
        ],
        "startDateTime": null,
        "finishDateTime": null,
        "srs": null,
        "originNode": null,
        "waypointNodes": null,
        "destinationNode": null,
        "carbonFootprint": 0.195038864105688
    }
);

XML format

<?xml version="1.0" encoding="UTF-8"?>
<routeResultV6>
        <status>OK</status>
        <distance>640 m</distance>
        <duration>0:02:09</duration>
        <distanceMeters>639.95</distanceMeters>
        <durationSeconds>129.48</durationSeconds>
        <bounds>-1.351448,47.446922;-1.345263,47.44848</bounds>
        <wktGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktGeometry>
        <wktSimplifiedGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktSimplifiedGeometry>
        <leg>
                <distance>233 m</distance>
                <duration>0:00:46</duration>
                <distanceMeters>233.09</distanceMeters>
                <durationSeconds>46.84</durationSeconds>
                <step>
                        <distance>139 m</distance>
                        <duration>0:00:29</duration>
                        <distanceMeters>138.59</distanceMeters>
                        <durationSeconds>29.83</durationSeconds>
                        <name>RUE LA FONTAINE BRUNEAU</name>
                </step>
                <step>
            [...]
                </step>
        </leg>
        <leg>
                <distance>407 m</distance>
                <duration>0:01:22</duration>
                <distanceMeters>406.86</distanceMeters>
                <durationSeconds>82.64</durationSeconds>
                <step>
                        <distance>18 m</distance>
                        <duration>0:00:03</duration>
                        <distanceMeters>17.63</distanceMeters>
                        <durationSeconds>3.18</durationSeconds>
                        <name />
                </step>
                <step>
                        [...]
                </step>
        </leg>
        <carbonFootprint>0.195038864105688</carbonFootprint>
</routeResultV6>

JavaScript API

Include the JavaScript library

var routeCtrl = new GCUI.Control.Route();
routeCtrl.route({
    url:'http://<server>/<webapp>/api/lbs/route/v5.json',
    tolerance : 100,
    origin : new OpenLayers.LonLat(0.691012, 47.384813),
    destination : new OpenLayers.LonLat(0.691012, 47.384813),
    waypoints : [ new OpenLayers.LonLat(2.344408, 49.898798) ],
    callback : function(result, options) {
        console.log(result);
    }
});

The result variable is in JSON format as described above. The callback function passed to parameter is called at the end of the route calculation.

Possible responses

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

<?xml version="1.0" encoding="UTF-8"?>
<routeResultV6>
        <status>OK</status>
        <distance>640 m</distance>
        <duration>0:02:09</duration>
        <distanceMeters>639.95</distanceMeters>
        <durationSeconds>129.48</durationSeconds>
        <bounds>-1.351448,47.446922;-1.345263,47.44848</bounds>
        <wktGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktGeometry>
        <wktSimplifiedGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktSimplifiedGeometry>
        <leg>
                <distance>233 m</distance>
                <duration>0:00:46</duration>
                <distanceMeters>233.09</distanceMeters>
                <durationSeconds>46.84</durationSeconds>
                <step>
                        <distance>139 m</distance>
                        <duration>0:00:29</duration>
                        <distanceMeters>138.59</distanceMeters>
                        <durationSeconds>29.83</durationSeconds>
                        <name>RUE LA FONTAINE BRUNEAU</name>
                </step>
                <step>
            [...]
                </step>
        </leg>
        <leg>
                <distance>407 m</distance>
                <duration>0:01:22</duration>
                <distanceMeters>406.86</distanceMeters>
                <durationSeconds>82.64</durationSeconds>
                <step>
                        <distance>18 m</distance>
                        <duration>0:00:03</duration>
                        <distanceMeters>17.63</distanceMeters>
                        <durationSeconds>3.18</durationSeconds>
                        <name />
                </step>
                <step>
                        [...]
                </step>
        </leg>
        <carbonFootprint>0.195038864105688</carbonFootprint>
</routeResultV6>

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

<routeResultV6>
   <message>Origin and destination must be not null</message>
   <status>ERROR</status>
   <distanceMeters>0.0</distanceMeters>
   <durationSeconds>0.0</durationSeconds>
</routeResultV6>

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

<routeResultV6>
   <message>Origin, destination and waypoints should be represented by a couple of coordinates</message>
   <status>ERROR</status>
   <distanceMeters>0.0</distanceMeters>
   <durationSeconds>0.0</durationSeconds>
</routeResultV6>

Case of a faulty type (serviceResult/status is ERROR)

<serviceResult>
        <message>NumberFormatException: For input string: "AAA"</message>
        <status>ERROR</status>
</serviceResult>

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

<serviceResult>
   <message>ServiceException: Error in route computation
Error in smartrouting
Failed to execute calculateRoute
com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect waypoint { 146.691012, 47.384813, 0.000000 }
failed to connect waypoint { 146.691012, 47.384813, 0.000000 }</message>
   <status>ERROR</status>
</serviceResult>

Case of a problem with the graph: absent file, faulty filepath, etc… (serviceResult/status is ERROR)

<serviceResult>
    <message>ServiceException: Error in route computation
Error in smartrouting
datasource is null</message>
    <status>ERROR</status>
</serviceResult>

V5

Parameters / properties

Input

parameter	description	optional	default
origin	Start point coordinates. The longitude and latitude coordinates are separated by , characters.	no
originNode	Start node. Care: a physical node does not have the same ID in another graph.	yes *
destination	Finish point coordinates. The longitude and latitude coordinates are separated by the , character	no
destinationNode	Arrival node. Care: a physical node does not have the same ID in another graph.	yes *
waypoints	Coordinates for route stops. Each pair of coordinates for a stop is framed by the <waypoint> tag The longitude and latitude coordinates are separated by the , character	yes
waypointNodes	Step nodes. Each pair of coordinates for a step is framed by the <waypointNode> tag Care: a physical node does not have the same ID in another graph.	yes *
method	the shortest (distance) and fastest (time) route	yes	time
format	- standard: result = route summary / waypoints / geometry in wkt format / simplified geometry in wkt format / list of concatenated segments (without geometries) - extended: result = route summary / waypoints / simplified geometry in wkt format / list of non-concatenated segments (with geometries) - summary: result = route summary - geometry: result = route summary / waypoints / geometry in wkt format - simplifiedgeometry: result = route summary / waypoints / simplified geometry in wkt format - geometries: result = route summary / waypoints / geometry in wkt format / simplified geometry in wkt format - brief: result = route summary / list of segments with duration and distance - standardext: result = route summary / waypoints / list of concatenated segments with duration and distance and geometry - compressedgeometry: result = route summary / waypoints / compressed geometry with polyline encoding - compressedsimplifiedgeometry: result = route summary / waypoints / simplified compressed geometry with polyline encoding - node: result = route summary + Id of snapped nodes - completegeometry : result = route summary / waypoints / geometry in wkt format / list of concatenated segments with geometry in wkt format+ - compresscompletegeometry : result = route summary / waypoints / compressed geometry with polyline encoding + / list of concatenated segments with compressed geometry with polyline encoding - tollcost: résultat = route summary / cost of tolls. The cost is calculated according to the type of vehicle defined configName as well as the date/time of departure of the route startDateTime.	yes	standard
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes
tolerance	Tolerance distance (in metres) for the geometry simplification.	yes
graphName (depreciated)	Name of the graph to use This parameter is omitted if the configName parameter is used.	yes
startDateTime	Start 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 start date of 21 January 2014, at 9.00am in Paris. Caution: the + character can be misinterpreted by browsers, so in this case, it should be replaced by %2B.	yes
profileId (depreciated)	Vehicle identifier (saved under vehicle profiles) This parameter is omitted if the configName parameter is used.	yes
profileName (depreciated)	Vehicle profile (saved in the vehicle profiles) This parameter is omitted if the configName parameter is used.	yes
exclusions	List of restriction rules to use, separated by the ; character (Example: Toll, Tunnel, Bridge)	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 path, connectable to the network. For example, on a highway, the returned position is the last exit or service area before the requested position.	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
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 (defined in Geoconcept Web - Administration / Tools / Road graphs) This replaces the use of graphName, profileId and profileName	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" - fuelType: fuel type used for calculating the carbon footprint for the route. Values available are: "UndefinedFuelType", "NoFuel", "Diesel", "UnleadedFuel", "LGP" et "CustomFuelType". Usage : "fuelType:Diesel" - averageConsumption: average consumption in litres for 100 kilometers. Use as follows: "averageConsumption:6.45" - customAverageCO2UnitEmission: defines the carbon footprint in kilograms per litre. Use as follows: "customAverageCO2UnitEmission:2.724" - snapSpeed: snap-to-graph speed in kilometers per hour. Use as follows: "snapSpeed:10"	yes
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

(M18) Available from version M18 and later versions of graphs supplied by GEOCONCEPT SAS.

Output

Route (routeResultV5)

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 metres.
durationSeconds	double	0/1	Total duration of the route in seconds.
waypoints	string	0/1	Waypoints (BoundingBox) for the route geometry.
wktGeometry	string	0/1	Geometry of the route in WKT format
wktSimplified	string	0/1	Simplified geometry in WKT format.
leg (or legs in JSON / JSON-P)	subRouteV5 (or array in JSON / JSON-P)	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
timeLineItem	timeLineItemV5 (or an array in JSON / JSON-P)	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)
tollCost	Array de tollCost	0/unlimited	Toll cost information (filled in if format=tollCost).

Itinerary portion (subRouteV5)

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 metres.
durationSeconds	double	0/1	Duration of the route segment in seconds.
step or (or steps in JSON / JSON-P)	segmentV5 (or array in JSON / JSON-P)	0/unlimited	List of component segments in the route segments

Route segment (segmentV5)

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 metres.
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.
point	string	0/unlimited	List of coordinates separated by the , character

Route position (timeLineItemV5)

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 metres up to this position.
location	string	0/1	Coordinates of the position.

TollCost (tollCost)

parameter	type	min/max	description
amount	double	0/1	Total cost of tolls.
currency	string	0/1	Currency.
costsByCountry	Array de costsByCountry	0/unlimited	List of toll costs by country.

Cost of tolls per country (costsByCountry)

parameter	type	min/max	description
amount	double	0/1	Cost of tolls.
country	string	0/1	Country code (3-letter ISO country code).

SOAP

WSDL

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

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:routeV5>
         <!--Optional:-->
         <request>
            <origin>
               <x>-1.351448</x>
               <y>47.446923</y>
            </origin>
            <!--Optional:-->
            <originNode></originNode>
            <destination>
               <x>-1.34529</x>
               <y>47.4479931</y>
            </destination>
            <!--Optional:-->
            <destinationNode></destinationNode>
            <!--Optional:-->
            <waypoints>
               <!--Zero or more repetitions:-->
               <waypoint>
                  <x>-1.34981</x>
                  <y>47.44837</y>
               </waypoint>
            </waypoints>
            <!--Optional:-->
            <waypointNodes>
               <!--Zero or more repetitions:-->
               <waypointNode></waypointNode>
            </waypointNodes>
            <!--Optional:-->
            <srs>epsg:4326</srs>
            <!--Optional:-->
            <method>time</method>
            <!--Optional:-->
            <format>STANDARD</format>
            <!--Optional:-->
            <tolerance>0.</tolerance>
            <!--Optional:-->
            <graphName></graphName>
            <!--Optional:-->
            <startDateTime></startDateTime>
            <!--Optional:-->
            <profileId></profileId>
            <!--Optional:-->
            <profileName></profileName>
            <!--Optional:-->
            <exclusions>
               <!--Zero or more repetitions:-->
               <exclusion></exclusion>
            </exclusions>
            <!--Optional:-->
            <timeLine>
               <!--Zero or more repetitions:-->
               <timeLineItem></timeLineItem>
            </timeLine>
            <!--Optional:-->
            <snapMethod></snapMethod>
            <!--Optional:-->
            <avoidArea></avoidArea>
            <!--Optional:-->
            <computeOptions></computeOptions>
            <!--Optional:-->
            <timeOut></timeOut>
            <!--Optional:-->
            <configName></configName>
         </request>
      </sch:routeV5>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:routeV5Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <RouteResult>
            <status>OK</status>
            <distance>640 m</distance>
            <duration>0:02:06</duration>
            <distanceMeters>639.97</distanceMeters>
            <durationSeconds>126.88</durationSeconds>
            <bounds>-1.351448,47.446922;-1.345263,47.44848</bounds>
            <wktGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, [...] ,  -1.34529 47.447993)</wktGeometry>
            <wktSimplifiedGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922,  [...] , -1.34529 47.447993)</wktSimplifiedGeometry>
            <leg>
               <distance>233 m</distance>
               <duration>0:00:46</duration>
               <distanceMeters>233.1</distanceMeters>
               <durationSeconds>46.28</durationSeconds>
               <step>
                  <distance>139 m</distance>
                  <duration>0:00:29</duration>
                  <distanceMeters>138.59</distanceMeters>
                  <durationSeconds>29.28</durationSeconds>
                  <name>RUE LA FONTAINE BRUNEAU</name>
               </step>
               <step>
                  <distance>91 m</distance>
                  <duration>0:00:16</duration>
                  <distanceMeters>91.33</distanceMeters>
                  <durationSeconds>16.43</durationSeconds>
                  <navigationInstruction>FR</navigationInstruction>
                  <name>RUE DES SAULES</name>
               </step>
               <step>
                  <distance>3 m</distance>
                  <duration>0:00:00</duration>
                  <distanceMeters>3.18</distanceMeters>
                  <durationSeconds>0.57</durationSeconds>
                  <navigationInstruction>round_about_entry</navigationInstruction>
                  <name />
               </step>
            </leg>
            <leg>
               <distance>407 m</distance>
               <duration>0:01:20</duration>
               <distanceMeters>406.87</distanceMeters>
               <durationSeconds>80.6</durationSeconds>
               <step>
                  <distance>18 m</distance>
                  <duration>0:00:03</duration>
                  <distanceMeters>17.64</distanceMeters>
                  <durationSeconds>3.17</durationSeconds>
                  <name />
               </step>
               <step>
                  <distance>67 m</distance>
                  <duration>0:00:15</duration>
                  <distanceMeters>66.62</distanceMeters>
                  <durationSeconds>15.05</durationSeconds>
                  <navigationInstruction>round_about_exit</navigationInstruction>
                  <name>RUE DES FOURS</name>
               </step>
               <step>
                  <distance>36 m</distance>
                  <duration>0:00:08</duration>
                  <distanceMeters>35.74</distanceMeters>
                  <durationSeconds>8.57</durationSeconds>
                  <navigationInstruction>F</navigationInstruction>
                  <name>PLACE DE L'ÉGLISE</name>
               </step>
               <step>
                  <distance>72 m</distance>
                  <duration>0:00:15</duration>
                  <distanceMeters>72.25</distanceMeters>
                  <durationSeconds>15.24</durationSeconds>
                  <navigationInstruction>F</navigationInstruction>
                  <name>RUE DES PRESSOIRS</name>
               </step>
               <step>
                  <distance>26 m</distance>
                  <duration>0:00:04</duration>
                  <distanceMeters>26.02</distanceMeters>
                  <durationSeconds>4.68</durationSeconds>
                  <navigationInstruction>round_about_entry</navigationInstruction>
                  <name />
               </step>
               <step>
                  <distance>183 m</distance>
                  <duration>0:00:32</duration>
                  <distanceMeters>182.84</distanceMeters>
                  <durationSeconds>32.91</durationSeconds>
                  <navigationInstruction>round_about_exit</navigationInstruction>
                  <name>RUE DU BOURG DRAPÉ</name>
               </step>
               <step>
                  <distance>6 m</distance>
                  <duration>0:00:00</duration>
                  <distanceMeters>5.76</distanceMeters>
                  <durationSeconds>0.98</durationSeconds>
                  <navigationInstruction>FR</navigationInstruction>
                  <name>RUE DE LA CURE</name>
               </step>
            </leg>
            <srs>epsg:4326</srs>
            <carbonFootprint>0.0</carbonFootprint>
         </RouteResult>
      </ns2:routeV5Response>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/route/v5.json?origin=-1.351448,47.446923&destination=-1.34529,47.4479931&waypoints=-1.34981,47.44837

JSON-P query

http://<server>/<webapp>/api/lbs/route/v5.json?origin=-1.351448,47.446923&destination=-1.34529,47.4479931&waypoints=-1.34981,47.44837&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/route/v5.xml?origin=-1.351448,47.446923&destination=-1.34529,47.4479931&waypoints=-1.34981,47.44837

Response

The response is always in UTF-8 format.

JSON format

{
    "message": null,
    "status": "OK",
    "distance": "640 m",
    "duration": "0:02:09",
    "distanceMeters": 639.95,
    "durationSeconds": 129.48,
    "bounds": "-1.351448,47.446922;-1.345263,47.44848",
    "wktGeometry": "LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
    "wktSimplifiedGeometry":"LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
    "legs": [
        {
            "distance": "233 m",
            "duration": "0:00:46",
            "distanceMeters": 233.09,
            "durationSeconds": 46.84,
            "steps": [
                {
                    "distance": "139 m",
                    "duration": "0:00:29",
                    "distanceMeters": 138.59,
                    "durationSeconds": 29.83,
                    "navigationInstruction": null,
                    "name": "RUE LA FONTAINE BRUNEAU",
                    "points": []
                },
                {
                    [...]
                }
            ]
        },
        {
            "distance": "407 m",
            "duration": "0:01:22",
            "distanceMeters": 406.86,
            "durationSeconds": 82.64,
            "steps": [
                {
                    "distance": "18 m",
                    "duration": "0:00:03",
                    "distanceMeters": 17.63,
                    "durationSeconds": 3.18,
                    "navigationInstruction": null,
                    "name": "",
                    "points": []
                },
                {
                   [...]
                }
            ]
        }
    ],
    "startDateTime": null,
    "finishDateTime": null,
    "srs": null,
    "originNode": null,
    "waypointNodes": null,
    "destinationNode": null,
    "carbonFootprint": 0.195038864105688
}

JSON-P format

myCallback(
    {
        "message": null,
        "status": "OK",
        "distance": "640 m",
        "duration": "0:02:09",
        "distanceMeters": 639.95,
        "durationSeconds": 129.48,
        "bounds": "-1.351448,47.446922;-1.345263,47.44848",
        "wktGeometry": "LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
        "wktSimplifiedGeometry":"LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
        "legs": [
            {
                "distance": "233 m",
                "duration": "0:00:46",
                "distanceMeters": 233.09,
                "durationSeconds": 46.84,
                "steps": [
                    {
                        "distance": "139 m",
                        "duration": "0:00:29",
                        "distanceMeters": 138.59,
                        "durationSeconds": 29.83,
                        "navigationInstruction": null,
                        "name": "RUE LA FONTAINE BRUNEAU",
                        "points": []
                    },
                    {
                        [...]
                    }
                ]
            },
            {
                "distance": "407 m",
                "duration": "0:01:22",
                "distanceMeters": 406.86,
                "durationSeconds": 82.64,
                "steps": [
                    {
                        "distance": "18 m",
                        "duration": "0:00:03",
                        "distanceMeters": 17.63,
                        "durationSeconds": 3.18,
                        "navigationInstruction": null,
                        "name": "",
                        "points": []
                    },
                    {
                       [...]
                    }
                ]
            }
        ],
        "startDateTime": null,
        "finishDateTime": null,
        "srs": null,
        "originNode": null,
        "waypointNodes": null,
        "destinationNode": null,
        "carbonFootprint": 0.195038864105688
    }
);

XML format

<?xml version="1.0" encoding="UTF-8"?>
<routeResultV5>
        <status>OK</status>
        <distance>640 m</distance>
        <duration>0:02:09</duration>
        <distanceMeters>639.95</distanceMeters>
        <durationSeconds>129.48</durationSeconds>
        <bounds>-1.351448,47.446922;-1.345263,47.44848</bounds>
        <wktGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktGeometry>
        <wktSimplifiedGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktSimplifiedGeometry>
        <leg>
                <distance>233 m</distance>
                <duration>0:00:46</duration>
                <distanceMeters>233.09</distanceMeters>
                <durationSeconds>46.84</durationSeconds>
                <step>
                        <distance>139 m</distance>
                        <duration>0:00:29</duration>
                        <distanceMeters>138.59</distanceMeters>
                        <durationSeconds>29.83</durationSeconds>
                        <name>RUE LA FONTAINE BRUNEAU</name>
                </step>
                <step>
            [...]
                </step>
        </leg>
        <leg>
                <distance>407 m</distance>
                <duration>0:01:22</duration>
                <distanceMeters>406.86</distanceMeters>
                <durationSeconds>82.64</durationSeconds>
                <step>
                        <distance>18 m</distance>
                        <duration>0:00:03</duration>
                        <distanceMeters>17.63</distanceMeters>
                        <durationSeconds>3.18</durationSeconds>
                        <name />
                </step>
                <step>
                        [...]
                </step>
        </leg>
        <carbonFootprint>0.195038864105688</carbonFootprint>
</routeResultV5>

JavaScript API

Include the JavaScript library

var routeCtrl = new GCUI.Control.Route();
routeCtrl.route({
    url:'http://<server>/<webapp>/api/lbs/route/v5.json',
    tolerance : 100,
    origin : new OpenLayers.LonLat(0.691012, 47.384813),
    destination : new OpenLayers.LonLat(0.691012, 47.384813),
    waypoints : [ new OpenLayers.LonLat(2.344408, 49.898798) ],
    callback : function(result, options) {
        console.log(result);
    }
});

The result variable is in JSON format as described above. The callback function passed to parameter is called at the end of the route calculation.

Possible responses

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

<?xml version="1.0" encoding="UTF-8"?>
<routeResultV5>
        <status>OK</status>
        <distance>640 m</distance>
        <duration>0:02:09</duration>
        <distanceMeters>639.95</distanceMeters>
        <durationSeconds>129.48</durationSeconds>
        <bounds>-1.351448,47.446922;-1.345263,47.44848</bounds>
        <wktGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktGeometry>
        <wktSimplifiedGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktSimplifiedGeometry>
        <leg>
                <distance>233 m</distance>
                <duration>0:00:46</duration>
                <distanceMeters>233.09</distanceMeters>
                <durationSeconds>46.84</durationSeconds>
                <step>
                        <distance>139 m</distance>
                        <duration>0:00:29</duration>
                        <distanceMeters>138.59</distanceMeters>
                        <durationSeconds>29.83</durationSeconds>
                        <name>RUE LA FONTAINE BRUNEAU</name>
                </step>
                <step>
            [...]
                </step>
        </leg>
        <leg>
                <distance>407 m</distance>
                <duration>0:01:22</duration>
                <distanceMeters>406.86</distanceMeters>
                <durationSeconds>82.64</durationSeconds>
                <step>
                        <distance>18 m</distance>
                        <duration>0:00:03</duration>
                        <distanceMeters>17.63</distanceMeters>
                        <durationSeconds>3.18</durationSeconds>
                        <name />
                </step>
                <step>
                        [...]
                </step>
        </leg>
        <carbonFootprint>0.195038864105688</carbonFootprint>
</routeResultV5>

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

<routeResultV5>
   <message>Origin and destination must be not null</message>
   <status>ERROR</status>
   <distanceMeters>0.0</distanceMeters>
   <durationSeconds>0.0</durationSeconds>
</routeResultV5>

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

<routeResultV5>
   <message>Origin, destination and waypoints should be represented by a couple of coordinates</message>
   <status>ERROR</status>
   <distanceMeters>0.0</distanceMeters>
   <durationSeconds>0.0</durationSeconds>
</routeResultV5>

Case of a faulty type (serviceResult/status is ERROR)

<serviceResult>
        <message>NumberFormatException: For input string: "AAA"</message>
        <status>ERROR</status>
</serviceResult>

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

<serviceResult>
   <message>ServiceException: Error in route computation
Error in smartrouting
Failed to execute calculateRoute
com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect waypoint { 146.691012, 47.384813, 0.000000 }
failed to connect waypoint { 146.691012, 47.384813, 0.000000 }</message>
   <status>ERROR</status>
</serviceResult>

Case of a problem with the graph: absent file, faulty filepath, etc… (serviceResult/status is ERROR)

<serviceResult>
    <message>ServiceException: Error in route computation
Error in smartrouting
datasource is null</message>
    <status>ERROR</status>
</serviceResult>

V4

Parameters / properties

Input

parameter	description	optional	default
origin	Start point coordinates. The longitude and latitude coordinates are separated by , characters.	no
originNode	Start node. Care: a physical node does not have the same ID in another graph.	yes *
destination	Finish point coordinates. The longitude and latitude coordinates are separated by the , character	no
destinationNode	Arrival node. Care: a physical node does not have the same ID in another graph.	yes *
waypoints	Coordinates for route stops. Each pair of coordinates for a stop is framed by the <waypoint> tag The longitude and latitude coordinates are separated by the , character	yes
waypointNodes	Step nodes. Each pair of coordinates for a step is framed by the <waypointNode> tag Care: a physical node does not have the same ID in another graph.	yes *
method	the shortest (distance) and fastest (time) route	yes	time
format	- standard: result = route summary / waypoints / geometry in wkt format / simplified geometry in wkt format / list of concatenated segments (without geometries) - extended: result = route summary / waypoints / simplified geometry in wkt format / list of non-concatenated segments (with geometries) - summary: result = route summary - geometry: result = route summary / waypoints / geometry in wkt format - simplifiedgeometry: result = route summary / waypoints / simplified geometry in wkt format - geometries: result = route summary / waypoints / geometry in wkt format / simplified geometry in wkt format - brief: result = route summary / List of segments with duration and distance - standardext: result = route summary / waypoints / list of concatenated segments with duration and distance and geometry - node: result = route summary + Id of snapped nodes	yes	standard
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes
tolerance	Tolerance distance (in metres) for the geometry simplification.	yes
graphName	Name of the graph to use This parameter is omitted if the configName parameter is used.	yes
startDateTime	Start 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 start date of 21 January 2014, at 9.00am in Paris. Caution: the + character can be misinterpreted by browsers, so in this case, it should be replaced by %2B.	yes
profileId	Vehicle identifier (saved under 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
exclusions	List of restriction rules to use, separated by the , or ; character (Example: Toll, Tunnel, Bridge)	yes
timeLine	List of intermediate durations to calculate positions along the route trajectory. Expressed in seconds, separated by the ; character	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	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 (defined in Geoconcept Web - Administration / Tools / Road graphs) This replaces the use of graphName, profileId and profileName	yes

Output

Route (routeResultV4)

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 metres.
durationSeconds	double	0/1	Total duration of the route in seconds.
waypoints	string	0/1	Waypoints (BoundingBox) for the route geometry.
wktGeometry	string	0/1	Geometry of the route in WKT format
wktSimplified	string	0/1	Simplified geometry in WKT format.
leg (or legs in JSON / JSON-P)	subRouteV4 (or array in JSON / JSON-P)	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
timeLineItem	timeLineItemV4 (or an array in JSON / JSON-P)	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)

Itinerary portion (subRouteV4)

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 metres.
durationSeconds	double	0/1	Duration of the route segment in seconds.
step or (or steps in JSON / JSON-P)	segmentV4 (or array in JSON / JSON-P)	0/unlimited	List of component segments in the route segments

Route segment (segmentV4)

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 metres.
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.
point	string	0/unlimited	List of coordinates separated by the , character

Route position (timeLineItemV4)

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 metres up to this position.
location	string	0/1	Coordinates of the position.

SOAP

WSDL

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

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:routeV4>
         <!--Optional:-->
         <request>
            <origin>
               <x>-1.351448</x>
               <y>47.446923</y>
            </origin>
            <!--Optional:-->
            <originNode></originNode>
            <destination>
               <x>-1.34529</x>
               <y>47.4479931</y>
            </destination>
            <!--Optional:-->
            <destinationNode></destinationNode>
            <!--Optional:-->
            <waypoints>
               <!--Zero or more repetitions:-->
               <waypoint>
                  <x>-1.34981</x>
                  <y>47.44837</y>
               </waypoint>
            </waypoints>
            <!--Optional:-->
            <waypointNodes>
               <!--Zero or more repetitions:-->
               <waypointNode></waypointNode>
            </waypointNodes>
            <!--Optional:-->
            <srs>epsg:4326</srs>
            <!--Optional:-->
            <method>time</method>
            <!--Optional:-->
            <format>STANDARD</format>
            <!--Optional:-->
            <tolerance>0.</tolerance>
            <!--Optional:-->
            <graphName></graphName>
            <!--Optional:-->
            <startDateTime></startDateTime>
            <!--Optional:-->
            <profileId></profileId>
            <!--Optional:-->
            <profileName></profileName>
            <!--Optional:-->
            <exclusions>
               <!--Zero or more repetitions:-->
               <exclusion></exclusion>
            </exclusions>
            <!--Optional:-->
            <timeLine>
               <!--Zero or more repetitions:-->
               <timeLineItem></timeLineItem>
            </timeLine>
            <!--Optional:-->
            <snapMethod></snapMethod>
            <!--Optional:-->
            <avoidArea></avoidArea>
            <!--Optional:-->
            <configName></configName>
         </request>
      </sch:routeV4>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:routeV4Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <RouteResult>
            <status>OK</status>
            <distance>640 m</distance>
            <duration>0:02:06</duration>
            <distanceMeters>639.95</distanceMeters>
            <durationSeconds>126.88</durationSeconds>
            <bounds>-1.351448,47.446922;-1.345263,47.44848</bounds>
            <wktGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922,  [...] )</wktGeometry>
            <wktSimplifiedGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922,  [...] )</wktSimplifiedGeometry>
            <leg>
               <distance>233 m</distance>
               <duration>0:00:46</duration>
               <distanceMeters>233.09</distanceMeters>
               <durationSeconds>46.28</durationSeconds>
               <step>
                  <distance>139 m</distance>
                  <duration>0:00:29</duration>
                  <distanceMeters>138.59</distanceMeters>
                  <durationSeconds>29.28</durationSeconds>
                  <name>RUE LA FONTAINE BRUNEAU</name>
               </step>
               <step>
                  <distance>91 m</distance>
                  <duration>0:00:16</duration>
                  <distanceMeters>91.33</distanceMeters>
                  <durationSeconds>16.43</durationSeconds>
                  <navigationInstruction>FR</navigationInstruction>
                  <name>RUE DES SAULES</name>
               </step>
               <step>
                  <distance>3 m</distance>
                  <duration>0:00:00</duration>
                  <distanceMeters>3.17</distanceMeters>
                  <durationSeconds>0.57</durationSeconds>
                  <navigationInstruction>round_about_entry</navigationInstruction>
                  <name/>
               </step>
            </leg>
            <leg>
               <distance>407 m</distance>
               <duration>0:01:20</duration>
               <distanceMeters>406.86</distanceMeters>
               <durationSeconds>80.6</durationSeconds>
               <step>
                  <distance>18 m</distance>
                  <duration>0:00:03</duration>
                  <distanceMeters>17.63</distanceMeters>
                  <durationSeconds>3.17</durationSeconds>
                  <name/>
               </step>
               <step>
                  <distance>67 m</distance>
                  <duration>0:00:15</duration>
                  <distanceMeters>66.62</distanceMeters>
                  <durationSeconds>15.05</durationSeconds>
                  <navigationInstruction>round_about_exit</navigationInstruction>
                  <name>RUE DES FOURS</name>
               </step>
               <step>
                  <distance>36 m</distance>
                  <duration>0:00:08</duration>
                  <distanceMeters>35.74</distanceMeters>
                  <durationSeconds>8.57</durationSeconds>
                  <navigationInstruction>F</navigationInstruction>
                  <name>PLACE DE L'ÉGLISE</name>
               </step>
               <step>
                  <distance>72 m</distance>
                  <duration>0:00:15</duration>
                  <distanceMeters>72.25</distanceMeters>
                  <durationSeconds>15.24</durationSeconds>
                  <navigationInstruction>F</navigationInstruction>
                  <name>RUE DES PRESSOIRS</name>
               </step>
               <step>
                  <distance>26 m</distance>
                  <duration>0:00:04</duration>
                  <distanceMeters>26.02</distanceMeters>
                  <durationSeconds>4.68</durationSeconds>
                  <navigationInstruction>round_about_entry</navigationInstruction>
                  <name/>
               </step>
               <step>
                  <distance>183 m</distance>
                  <duration>0:00:32</duration>
                  <distanceMeters>182.84</distanceMeters>
                  <durationSeconds>32.91</durationSeconds>
                  <navigationInstruction>round_about_exit</navigationInstruction>
                  <name>RUE DU BOURG DRAPÉ</name>
               </step>
               <step>
                  <distance>6 m</distance>
                  <duration>0:00:00</duration>
                  <distanceMeters>5.76</distanceMeters>
                  <durationSeconds>0.98</durationSeconds>
                  <navigationInstruction>FR</navigationInstruction>
                  <name>RUE DE LA CURE</name>
               </step>
            </leg>
            <timeLineItem>
               <durationSeconds>0.0</durationSeconds>
               <status>OK</status>
               <distanceMeters>0.0</distanceMeters>
               <location>-1.351448,47.446923</location>
            </timeLineItem>
            <srs>epsg:4326</srs>
            <carbonFootprint>0.0</carbonFootprint>
         </RouteResult>
      </ns2:routeV4Response>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/route/v4.json?origin=-1.351448,47.446923&destination=-1.34529,47.4479931&waypoints=-1.34981,47.44837

JSON-P query

http://<server>/<webapp>/api/lbs/route/v4.json?origin=-1.351448,47.446923&destination=-1.34529,47.4479931&waypoints=-1.34981,47.44837&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/route/v4.xml?origin=-1.351448,47.446923&destination=-1.34529,47.4479931&waypoints=-1.34981,47.44837

Response

The response is always in UTF-8 format.

JSON format

{
    "message": null,
    "status": "OK",
    "distance": "640 m",
    "duration": "0:02:09",
    "distanceMeters": 639.95,
    "durationSeconds": 129.48,
    "bounds": "-1.351448,47.446922;-1.345263,47.44848",
    "wktGeometry": "LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
    "wktSimplifiedGeometry":"LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
    "legs": [
        {
            "distance": "233 m",
            "duration": "0:00:46",
            "distanceMeters": 233.09,
            "durationSeconds": 46.84,
            "steps": [
                {
                    "distance": "139 m",
                    "duration": "0:00:29",
                    "distanceMeters": 138.59,
                    "durationSeconds": 29.83,
                    "navigationInstruction": null,
                    "name": "RUE LA FONTAINE BRUNEAU",
                    "points": []
                },
                {
                    [...]
                }
            ]
        },
        {
            "distance": "407 m",
            "duration": "0:01:22",
            "distanceMeters": 406.86,
            "durationSeconds": 82.64,
            "steps": [
                {
                    "distance": "18 m",
                    "duration": "0:00:03",
                    "distanceMeters": 17.63,
                    "durationSeconds": 3.18,
                    "navigationInstruction": null,
                    "name": "",
                    "points": []
                },
                {
                   [...]
                }
            ]
        }
    ],
    "startDateTime": null,
    "finishDateTime": null,
    "srs": null,
    "originNode": null,
    "waypointNodes": null,
    "destinationNode": null,
    "carbonFootprint": 0.195038864105688
}

JSON-P format

myCallback(
    {
        "message": null,
        "status": "OK",
        "distance": "640 m",
        "duration": "0:02:09",
        "distanceMeters": 639.95,
        "durationSeconds": 129.48,
        "bounds": "-1.351448,47.446922;-1.345263,47.44848",
        "wktGeometry": "LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
        "wktSimplifiedGeometry":"LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
        "legs": [
            {
                "distance": "233 m",
                "duration": "0:00:46",
                "distanceMeters": 233.09,
                "durationSeconds": 46.84,
                "steps": [
                    {
                        "distance": "139 m",
                        "duration": "0:00:29",
                        "distanceMeters": 138.59,
                        "durationSeconds": 29.83,
                        "navigationInstruction": null,
                        "name": "RUE LA FONTAINE BRUNEAU",
                        "points": []
                    },
                    {
                        [...]
                    }
                ]
            },
            {
                "distance": "407 m",
                "duration": "0:01:22",
                "distanceMeters": 406.86,
                "durationSeconds": 82.64,
                "steps": [
                    {
                        "distance": "18 m",
                        "duration": "0:00:03",
                        "distanceMeters": 17.63,
                        "durationSeconds": 3.18,
                        "navigationInstruction": null,
                        "name": "",
                        "points": []
                    },
                    {
                       [...]
                    }
                ]
            }
        ],
        "startDateTime": null,
        "finishDateTime": null,
        "srs": null,
        "originNode": null,
        "waypointNodes": null,
        "destinationNode": null,
        "carbonFootprint": 0.195038864105688
    }
);

XML format

<?xml version="1.0" encoding="UTF-8"?>
<routeResultV4>
        <status>OK</status>
        <distance>640 m</distance>
        <duration>0:02:09</duration>
        <distanceMeters>639.95</distanceMeters>
        <durationSeconds>129.48</durationSeconds>
        <bounds>-1.351448,47.446922;-1.345263,47.44848</bounds>
        <wktGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktGeometry>
        <wktSimplifiedGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktSimplifiedGeometry>
        <leg>
                <distance>233 m</distance>
                <duration>0:00:46</duration>
                <distanceMeters>233.09</distanceMeters>
                <durationSeconds>46.84</durationSeconds>
                <step>
                        <distance>139 m</distance>
                        <duration>0:00:29</duration>
                        <distanceMeters>138.59</distanceMeters>
                        <durationSeconds>29.83</durationSeconds>
                        <name>RUE LA FONTAINE BRUNEAU</name>
                </step>
                <step>
            [...]
                </step>
        </leg>
        <leg>
                <distance>407 m</distance>
                <duration>0:01:22</duration>
                <distanceMeters>406.86</distanceMeters>
                <durationSeconds>82.64</durationSeconds>
                <step>
                        <distance>18 m</distance>
                        <duration>0:00:03</duration>
                        <distanceMeters>17.63</distanceMeters>
                        <durationSeconds>3.18</durationSeconds>
                        <name />
                </step>
                <step>
                        [...]
                </step>
        </leg>
        <carbonFootprint>0.195038864105688</carbonFootprint>
</routeResultV4>

JavaScript API

Include the JavaScript library

var routeCtrl = new GCUI.Control.Route();
routeCtrl.route({
    url:'http://<server>/<webapp>/api/lbs/route/v4.json',
    tolerance : 100,
    origin : new OpenLayers.LonLat(0.691012, 47.384813),
    destination : new OpenLayers.LonLat(0.691012, 47.384813),
    waypoints : [ new OpenLayers.LonLat(2.344408, 49.898798) ],
    callback : function(result, options) {
        console.log(result);
    }
});

The result variable is in JSON format as described above. The callback function passed to parameter is called at the end of the route calculation.

Possible responses

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

<?xml version="1.0" encoding="UTF-8"?>
<routeResultV4>
        <status>OK</status>
        <distance>640 m</distance>
        <duration>0:02:09</duration>
        <distanceMeters>639.95</distanceMeters>
        <durationSeconds>129.48</durationSeconds>
        <bounds>-1.351448,47.446922;-1.345263,47.44848</bounds>
        <wktGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktGeometry>
        <wktSimplifiedGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktSimplifiedGeometry>
        <leg>
                <distance>233 m</distance>
                <duration>0:00:46</duration>
                <distanceMeters>233.09</distanceMeters>
                <durationSeconds>46.84</durationSeconds>
                <step>
                        <distance>139 m</distance>
                        <duration>0:00:29</duration>
                        <distanceMeters>138.59</distanceMeters>
                        <durationSeconds>29.83</durationSeconds>
                        <name>RUE LA FONTAINE BRUNEAU</name>
                </step>
                <step>
            [...]
                </step>
        </leg>
        <leg>
                <distance>407 m</distance>
                <duration>0:01:22</duration>
                <distanceMeters>406.86</distanceMeters>
                <durationSeconds>82.64</durationSeconds>
                <step>
                        <distance>18 m</distance>
                        <duration>0:00:03</duration>
                        <distanceMeters>17.63</distanceMeters>
                        <durationSeconds>3.18</durationSeconds>
                        <name />
                </step>
                <step>
                        [...]
                </step>
        </leg>
        <carbonFootprint>0.195038864105688</carbonFootprint>
</routeResultV4>

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

<routeResultV4>
   <message>Origin and destination must be not null</message>
   <status>ERROR</status>
   <distanceMeters>0.0</distanceMeters>
   <durationSeconds>0.0</durationSeconds>
</routeResultV4>

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

<routeResultV4>
   <message>Origin, destination and waypoints should be represented by a couple of coordinates</message>
   <status>ERROR</status>
   <distanceMeters>0.0</distanceMeters>
   <durationSeconds>0.0</durationSeconds>
</routeResultV4>

Case of a faulty type (serviceResult/status is ERROR)

<serviceResult>
        <message>NumberFormatException: For input string: "AAA"</message>
        <status>ERROR</status>
</serviceResult>

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

<serviceResult>
   <message>ServiceException: Error in route computation
Error in smartrouting
Failed to execute calculateRoute
com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect waypoint { 146.691012, 47.384813, 0.000000 }
failed to connect waypoint { 146.691012, 47.384813, 0.000000 }</message>
   <status>ERROR</status>
</serviceResult>

Case of a problem with the graph: absent file, faulty filepath, etc… (serviceResult/status is ERROR)

<serviceResult>
    <message>ServiceException: Error in route computation
Error in smartrouting
datasource is null</message>
    <status>ERROR</status>
</serviceResult>

V3

Parameters / properties

Input

parameter	description	optional	default
origin	Start point coordinates. The longitude and latitude coordinates are separated by , characters.	no
destination	Finish point coordinates. The longitude and latitude coordinates are separated by the , character	no
waypoints	Coordinates for route stops. Each pair of coordinates for a stop is framed by the <waypoint> tag The longitude and latitude coordinates are separated by the , character	yes
method	the shortest (distance) and fastest (time) route	yes	time
format	- standard: result = route summary / waypoints / geometry in wkt format / simplified geometry in wkt format / list of concatenated segments (without geometries) - extended: result = route summary / waypoints / simplified geometry in wkt format / list of non-concatenated segments (with geometries) - summary: result = route summary - geometry: result = route summary / waypoints / geometry in wkt format - simplifiedgeometry: result = route summary / waypoints / simplified geometry in wkt format - geometries: result = route summary / waypoints / geometry in wkt format / simplified geometry in wkt format - brief: result = route summary / list of segments with duration and distance - standardext: result = route summary / waypoints / list of concatenated segments with duration distance and geometry.	yes	standard
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes
tolerance	Tolerance distance (in metres) for the geometry simplification.	yes
graphName	Name of the graph to use	yes
startDateTime	Start 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 start on 21 January 2014, at 9.00am in Paris	yes
profileId	Vehicle identifier (saved under vehicle profiles) to use	yes
profileName	Vehicle profile (saved under vehicle profiles) to use	yes
exclusions	List of restriction rules to use, separated by the , or ; character (Example: Toll, Tunnel, Bridge)	yes
timeLine	List of intermediate durations to calculate positions along the route trajectory. Expressed in seconds, separated by the ; character	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	yes	standard

Output

Route (routeResultV3)

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 metres.
durationSeconds	double	0/1	Total duration of the route in seconds.
waypoints	string	0/1	Waypoints (BoundingBox) for the route geometry.
wktGeometry	string	0/1	Geometry of the route in WKT format
wktSimplified	string	0/1	Simplified geometry in WKT format.
leg (or legs in JSON / JSON-P)	subRouteV3 (or array in JSON / JSON-P)	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
timeLineItem	timeLineItemV3 (or an array in JSON / JSON-P)	0/unlimited	List of calculated positions.
srs	string	0/1	projection passed as input (EPSG code such as epsg:4326 or wgs84)

Route subsection (SubRouteV3)

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 metres.
durationSeconds	double	0/1	Duration of the route segment in seconds.
step or (or steps in JSON / JSON-P)	segmentV3 (or array in JSON / JSON-P)	0/unlimited	List of component segments in the route segments

Route segment (segmentV3)

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 metres.
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.
point	string	0/unlimited	List of coordinates separated by the , character

Route position (timeLineItemV3)

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 metres up to this position.
location	string	0/1	Coordinates of the position.

SOAP

WSDL

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

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:routeV3>
         <!--Optional:-->
         <request>
            <origin>
               <x>-1.351448</x>
               <y>47.446923</y>
            </origin>
            <destination>
               <x>-1.34529</x>
               <y>47.4479931</y>
            </destination>
            <!--Optional:-->
            <waypoints>
               <!--Zero or more repetitions:-->
               <waypoint>
                  <x>-1.34981</x>
                  <y>47.44837</y>
               </waypoint>
            </waypoints>
            <!--Optional:-->
            <srs>epsg:4326</srs>
            <!--Optional:-->
            <method>time</method>
            <!--Optional:-->
            <format>STANDARD</format>
            <!--Optional:-->
            <tolerance>0.</tolerance>
            <!--Optional:-->
            <graphName></graphName>
            <!--Optional:-->
            <startDateTime>2015-07-29T09:00:00.000+01:00</startDateTime>
            <!--Optional:-->
            <profileId></profileId>
            <!--Optional:-->
            <profileName></profileName>
            <!--Optional:-->
            <exclusions>
               <!--Zero or more repetitions:-->
               <exclusion></exclusion>
            </exclusions>
            <!--Optional:-->
            <timeLine>
               <!--Zero or more repetitions:-->
               <timeLineItem>5</timeLineItem>
               <timeLineItem>15</timeLineItem>
            </timeLine>
            <!--Optional:-->
            <snapMethod></snapMethod>
         </request>
      </sch:routeV3>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:routeV3Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <RouteResult>
            <status>OK</status>
            <distance>640 m</distance>
            <duration>0:02:06</duration>
            <distanceMeters>639.95</distanceMeters>
            <durationSeconds>126.88</durationSeconds>
            <bounds>-1.351448,47.446922;-1.345263,47.44848</bounds>
            <wktGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922,  [...] )</wktGeometry>
            <wktSimplifiedGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922,  [...] )</wktSimplifiedGeometry>
            <leg>
               <distance>233 m</distance>
               <duration>0:00:46</duration>
               <distanceMeters>233.09</distanceMeters>
               <durationSeconds>46.28</durationSeconds>
               <step>
                  <distance>139 m</distance>
                  <duration>0:00:29</duration>
                  <distanceMeters>138.59</distanceMeters>
                  <durationSeconds>29.28</durationSeconds>
                  <name>RUE LA FONTAINE BRUNEAU</name>
               </step>
               <step>
                  <distance>91 m</distance>
                  <duration>0:00:16</duration>
                  <distanceMeters>91.33</distanceMeters>
                  <durationSeconds>16.43</durationSeconds>
                  <navigationInstruction>FR</navigationInstruction>
                  <name>RUE DES SAULES</name>
               </step>
               <step>
                  <distance>3 m</distance>
                  <duration>0:00:00</duration>
                  <distanceMeters>3.17</distanceMeters>
                  <durationSeconds>0.57</durationSeconds>
                  <navigationInstruction>round_about_entry</navigationInstruction>
                  <name/>
               </step>
            </leg>
            <leg>
               <distance>407 m</distance>
               <duration>0:01:20</duration>
               <distanceMeters>406.86</distanceMeters>
               <durationSeconds>80.6</durationSeconds>
               <step>
                  <distance>18 m</distance>
                  <duration>0:00:03</duration>
                  <distanceMeters>17.63</distanceMeters>
                  <durationSeconds>3.17</durationSeconds>
                  <name/>
               </step>
               <step>
                  <distance>67 m</distance>
                  <duration>0:00:15</duration>
                  <distanceMeters>66.62</distanceMeters>
                  <durationSeconds>15.05</durationSeconds>
                  <navigationInstruction>round_about_exit</navigationInstruction>
                  <name>RUE DES FOURS</name>
               </step>
               <step>
                  <distance>36 m</distance>
                  <duration>0:00:08</duration>
                  <distanceMeters>35.74</distanceMeters>
                  <durationSeconds>8.57</durationSeconds>
                  <navigationInstruction>F</navigationInstruction>
                  <name>PLACE DE L'ÉGLISE</name>
               </step>
               <step>
                  <distance>72 m</distance>
                  <duration>0:00:15</duration>
                  <distanceMeters>72.25</distanceMeters>
                  <durationSeconds>15.24</durationSeconds>
                  <navigationInstruction>F</navigationInstruction>
                  <name>RUE DES PRESSOIRS</name>
               </step>
               <step>
                  <distance>26 m</distance>
                  <duration>0:00:04</duration>
                  <distanceMeters>26.02</distanceMeters>
                  <durationSeconds>4.68</durationSeconds>
                  <navigationInstruction>round_about_entry</navigationInstruction>
                  <name/>
               </step>
               <step>
                  <distance>183 m</distance>
                  <duration>0:00:32</duration>
                  <distanceMeters>182.84</distanceMeters>
                  <durationSeconds>32.91</durationSeconds>
                  <navigationInstruction>round_about_exit</navigationInstruction>
                  <name>RUE DU BOURG DRAPÉ</name>
               </step>
               <step>
                  <distance>6 m</distance>
                  <duration>0:00:00</duration>
                  <distanceMeters>5.76</distanceMeters>
                  <durationSeconds>0.98</durationSeconds>
                  <navigationInstruction>FR</navigationInstruction>
                  <name>RUE DE LA CURE</name>
               </step>
            </leg>
            <startDateTime>2015-07-29T10:00:00.000+02:00</startDateTime>
            <finishDateTime>2015-07-29T10:02:06.880+02:00</finishDateTime>
            <timeLineItem>
               <durationSeconds>5.0</durationSeconds>
               <status>OK</status>
               <distanceMeters>23.66</distanceMeters>
               <location>-1.35137,47.447123</location>
            </timeLineItem>
            <timeLineItem>
               <durationSeconds>15.0</durationSeconds>
               <status>OK</status>
               <distanceMeters>71.0</distanceMeters>
               <location>-1.351204,47.447533</location>
            </timeLineItem>
            <srs>epsg:4326</srs>
         </RouteResult>
      </ns2:routeV3Response>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/route/v3.json?origin=-1.351448,47.446923&destination=-1.34529,47.4479931&waypoints=-1.34981,47.44837

JSON-P query

http://<server>/<webapp>/api/lbs/route/v3.json?origin=-1.351448,47.446923&destination=-1.34529,47.4479931&waypoints=-1.34981,47.44837&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/route/v3.xml?origin=-1.351448,47.446923&destination=-1.34529,47.4479931&waypoints=-1.34981,47.44837

Response

The response is always in UTF-8 format.

JSON format

{
   "message":null,
   "status":"OK",
   "distance":"640 m",
   "duration":"0:01:25",
   "distanceMeters":640.0,
   "durationSeconds":85.64,
   "bounds":"-1.351448,47.446922;-1.345263,47.44848",
   "wktGeometry":"LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
   "wktSimplifiedGeometry":"LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
   "legs":[
      {
         "distance":"233 m",
         "duration":"0:00:36",
         "distanceMeters":233.1,
         "durationSeconds":36.33,
         "steps":[
            {
               "distance":"139 m",
               "duration":"0:00:25",
               "distanceMeters":138.59,
               "durationSeconds":25.0,
               "navigationInstruction":null,
               "name":"RUE LA FONTAINE BRUNEAU",
               "points":[

               ]
            },
            {
                [...]
            }
         ]
      },
      {
         "distance":"407 m",
         "duration":"0:00:49",
         "distanceMeters":406.90000000000003,
         "durationSeconds":49.31,
         "steps":[
            {
               "distance":"18 m",
               "duration":"0:00:02",
               "distanceMeters":17.62,
               "durationSeconds":2.11,
               "navigationInstruction":null,
               "name":"",
               "points":[

               ]
            },
            {
               [...]
            }
         ]
      }
   ],
   "startDateTime":null,
   "finishDateTime":null,
   "srs":"epsg:4326"
}

JSON-P format

myCallback(
    {
       "message":null,
       "status":"OK",
       "distance":"640 m",
       "duration":"0:01:25",
       "distanceMeters":640.0,
       "durationSeconds":85.64,
       "bounds":"-1.351448,47.446922;-1.345263,47.44848",
       "wktGeometry":"LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
       "wktSimplifiedGeometry":"LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
       "legs":[
          {
             "distance":"233 m",
             "duration":"0:00:36",
             "distanceMeters":233.1,
             "durationSeconds":36.33,
             "steps":[
                {
                   "distance":"139 m",
                   "duration":"0:00:25",
                   "distanceMeters":138.59,
                   "durationSeconds":25.0,
                   "navigationInstruction":null,
                   "name":"RUE LA FONTAINE BRUNEAU",
                   "points":[

                   ]
                },
                {
                    [...]
                }
             ]
          },
          {
             "distance":"407 m",
             "duration":"0:00:49",
             "distanceMeters":406.90000000000003,
             "durationSeconds":49.31,
             "steps":[
                {
                   "distance":"18 m",
                   "duration":"0:00:02",
                   "distanceMeters":17.62,
                   "durationSeconds":2.11,
                   "navigationInstruction":null,
                   "name":"",
                   "points":[

                   ]
                },
                {
                   [...]
                }
             ]
          }
       ],
       "startDateTime":null,
       "finishDateTime":null,
       "srs":"epsg:4326"
    }
);

XML format

<?xml version="1.0" encoding="UTF-8"?>
<routeResultV3>
   <status>OK</status>
   <distance>640 m</distance>
   <duration>0:01:25</duration>
   <distanceMeters>640.0</distanceMeters>
   <durationSeconds>85.64</durationSeconds>
   <bounds>-1.351448,47.446922;-1.345263,47.44848</bounds>
   <wktGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktGeometry>
   <wktSimplifiedGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktSimplifiedGeometry>
   <leg>
      <distance>233 m</distance>
      <duration>0:00:36</duration>
      <distanceMeters>233.1</distanceMeters>
      <durationSeconds>36.33</durationSeconds>
      <step>
         <distance>139 m</distance>
         <duration>0:00:25</duration>
         <distanceMeters>138.59</distanceMeters>
         <durationSeconds>25.0</durationSeconds>
         <name>RUE LA FONTAINE BRUNEAU</name>
      </step>
      <step>
            [...]
      </step>
   </leg>
   <leg>
      <distance>407 m</distance>
      <duration>0:00:49</duration>
      <distanceMeters>406.90000000000003</distanceMeters>
      <durationSeconds>49.31</durationSeconds>
      <step>
         <distance>18 m</distance>
         <duration>0:00:02</duration>
         <distanceMeters>17.62</distanceMeters>
         <durationSeconds>2.11</durationSeconds>
         <name />
      </step>
      <step>
            [...]
      </step>
   </leg>
   <srs>epsg:4326</srs>
</routeResultV3>

JavaScript API

Include the JavaScript library

var routeCtrl = new GCUI.Control.Route();
routeCtrl.route({
    url:'http://<server>/<webapp>/api/lbs/route/v3.json',
    tolerance : 100,
    origin : new OpenLayers.LonLat(0.691012, 47.384813),
    destination : new OpenLayers.LonLat(0.691012, 47.384813),
    waypoints : [ new OpenLayers.LonLat(2.344408, 49.898798) ],
    callback : function(result, options) {
        console.log(result);
    }
});

The result variable is in JSON format as described above. The callback function passed to parameter is called at the end of the route calculation.

Possible responses

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

<?xml version="1.0" encoding="UTF-8"?>
<routeResultV3>
   <status>OK</status>
   <distance>640 m</distance>
   <duration>0:01:25</duration>
   <distanceMeters>640.0</distanceMeters>
   <durationSeconds>85.64</durationSeconds>
   <bounds>-1.351448,47.446922;-1.345263,47.44848</bounds>
   <wktGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktGeometry>
   <wktSimplifiedGeometry>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</wktSimplifiedGeometry>
   <leg>
      <distance>233 m</distance>
      <duration>0:00:36</duration>
      <distanceMeters>233.1</distanceMeters>
      <durationSeconds>36.33</durationSeconds>
      <step>
         <distance>139 m</distance>
         <duration>0:00:25</duration>
         <distanceMeters>138.59</distanceMeters>
         <durationSeconds>25.0</durationSeconds>
         <name>RUE LA FONTAINE BRUNEAU</name>
      </step>
      <step>
            [...]
      </step>
   </leg>
   <leg>
      <distance>407 m</distance>
      <duration>0:00:49</duration>
      <distanceMeters>406.90000000000003</distanceMeters>
      <durationSeconds>49.31</durationSeconds>
      <step>
         <distance>18 m</distance>
         <duration>0:00:02</duration>
         <distanceMeters>17.62</distanceMeters>
         <durationSeconds>2.11</durationSeconds>
         <name />
      </step>
      <step>
            [...]
      </step>
   </leg>
   <srs>epsg:4326</srs>
</routeResultV3>

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

<routeResultV3>
   <message>Origin and destination must be not null</message>
   <status>ERROR</status>
   <distanceMeters>0.0</distanceMeters>
   <durationSeconds>0.0</durationSeconds>
</routeResultV3>

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

<routeResultV3>
   <message>Origin, destination and waypoints should be represented by a couple of coordinates</message>
   <status>ERROR</status>
   <distanceMeters>0.0</distanceMeters>
   <durationSeconds>0.0</durationSeconds>
</routeResultV3>

Case of a faulty type (serviceResult/status is ERROR)

<serviceResult>
        <message>NumberFormatException: For input string: "AAA"</message>
        <status>ERROR</status>
</serviceResult>

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

<serviceResult>
   <message>ServiceException: Error in route computation
Error in smartrouting
Failed to execute calculateRoute
com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect waypoint { 146.691012, 47.384813, 0.000000 }
failed to connect waypoint { 146.691012, 47.384813, 0.000000 }</message>
   <status>ERROR</status>
</serviceResult>

Case of a problem with the graph: absent file, faulty filepath, etc… (serviceResult/status is ERROR)

<serviceResult>
    <message>ServiceException: Error in route computation
Error in smartrouting
datasource is null</message>
    <status>ERROR</status>
</serviceResult>

V2

Parameters / properties

Input

parameter	description	optional	default
origin	Start point coordinates. The longitude and latitude coordinates are separated by , characters.	no
destination	Finish point coordinates. The longitude and latitude coordinates are separated by the , character	no
waypoints	Coordinates for route stops. Each pair of coordinates for a stop is framed by the <waypoint> tag The longitude and latitude coordinates are separated by the , character	yes
method	the shortest (distance) and fastest (time) route	yes	time
format	- standard: result = route summary / waypoints / geometry in wkt format / simplified geometry in wkt format / list of concatenated segments (without geometries) - extended: result = route summary / waypoints / simplified geometry in wkt format / list of non-concatenated segments (with geometries) - summary: result = route summary - geometry: result = route summary / waypoints / geometry in wkt format - simplifiedgeometry: result = route summary / waypoints / simplified geometry in wkt format - geometries: result = route summary / waypoints / geometry in wkt format / simplified geometry in wkt format - brief: result = route summary / list of segments with duration and distance - standardext: result = route summary / waypoints / list of concatenated segments with duration distance and geometry.	yes	standard
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes
tolerance	Tolerance distance (in metres) for the geometry simplification.	yes
graphName	Name of the graph to use	yes
startDateTime	Start 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 start on 21 January 2014, at 9.00am in Paris	yes
profileId	Vehicle identifier (saved under vehicle profiles) to use	yes
profileName	Vehicle profile (saved under vehicle profiles) to use	yes
exclusions	List of restriction rules to use, separated by the , or ; character (Example: Toll, Tunnel, Bridge)	yes
timeLine	List of intermediate durations to calculate positions along the route trajectory. Expressed in seconds, separated by the ; character	yes

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	string	0/1	Total route distance in metres.
durationSeconds	string	0/1	Total duration of the route in seconds.
waypoints	string	0/1	Waypoints (BoundingBox) for the route geometry.
geometryWkt	string	0/1	Geometry of the route in WKT format
simplifiedWkt	string	0/1	Simplified geometry in WKT format.
leg (or legs in JSON / JSON-P)	subRoute (or array in JSON / JSON-P)	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
timeLineItem	timellineItem (or array in JSON / JSON-P)	0/unlimited	List of calculated positions.

Route segment (subRoute)

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	string	0/1	Distance covered by the route segment in metres.
durationSeconds	string	0/1	Duration of the route segment in seconds.
step or (or steps in JSON / JSON-P)	segment (or array in JSON / JSON-P)	0/unlimited	List of component segments in the route segments

Route segment (segment)

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	string	0/1	Distance covered by the route segment in metres.
durationSeconds	string	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.
point	string	0/unlimited	List of coordinates separated by the , character

Route position (timeLineItem)

parameter	type	min/max	description
elapsedTimeSeconds	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 metres up to this position.
coordinates	string	0/1	Coordinates of the position.

SOAP

WSDL

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

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:routeV2>
         <!--Optional:-->
         <request>
            <origin>
              <x>-1.351448</x>
              <y>47.446923</y>
            </origin>
            <destination>
               <x>-1.34529</x>
                <y>47.4479931</y>
            </destination>
            <!--Optional:-->
            <waypoints>
               <!--Zero or more repetitions:-->
               <waypoint>
                <x>-1.34981</x>
                 <y>47.44837</y>
               </waypoint>
            </waypoints>
            <!--Optional:-->
            <srs>epsg:4326</srs>
            <!--Optional:-->
            <method>time</method>
            <!--Optional:-->
            <format>STANDARD</format>
            <!--Optional:-->
            <tolerance>0.</tolerance>
            <!--Optional:-->
            <graphName></graphName>
            <!--Optional:-->
            <startDateTime>2015-07-29T09:00:00.000+01:00</startDateTime>
            <!--Optional:-->
            <profileId></profileId>
            <!--Optional:-->
            <profileName></profileName>
            <!--Zero or more repetitions:-->
            <rejectFlags></rejectFlags>
            <!--Optional:-->
            <exclusions>
               <!--Zero or more repetitions:-->
               <exclusion></exclusion>
            </exclusions>
            <!--Optional:-->
            <timeLine>
               <!--Zero or more repetitions:-->
               <timeLineItem>5</timeLineItem>
               <timeLineItem>15</timeLineItem>
            </timeLine>
         </request>
      </sch:routeV2>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:routeV2Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <RouteResult>
            <status>OK</status>
            <distance>640 m</distance>
            <duration>0:01:24</duration>
            <distanceMeters>640</distanceMeters>
            <durationSeconds>84.87</durationSeconds>
            <bounds>-1.351448,47.446922;-1.345263,47.44848</bounds>
            <geometryWkt>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</geometryWkt>
            <simplifiedWkt>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</simplifiedWkt>
            <leg>
               <distance>233 m</distance>
               <duration>0:00:36</duration>
               <distanceMeters>233.1</distanceMeters>
               <durationSeconds>36.16</durationSeconds>
               <step>
                  <distance>139 m</distance>
                  <duration>0:00:24</duration>
                  <distanceMeters>138.59</distanceMeters>
                  <durationSeconds>24.83</durationSeconds>
                  <name>RUE LA FONTAINE BRUNEAU</name>
               </step>
               <step>
                    [...]
               </step>
            </leg>
            <leg>
               <distance>407 m</distance>
               <duration>0:00:48</duration>
               <distanceMeters>406.9</distanceMeters>
               <durationSeconds>48.71</durationSeconds>
               <step>
                  <distance>18 m</distance>
                  <duration>0:00:02</duration>
                  <distanceMeters>17.62</distanceMeters>
                  <durationSeconds>2.11</durationSeconds>
                  <name/>
               </step>
               <step>
                    [...]
               </step>
            </leg>
            <startDateTime>2015-07-29T13:30:00.000+05:30</startDateTime>
            <finishDateTime>2015-07-29T13:31:24.870+05:30</finishDateTime>
            <timeLineItem>
               <elapsedTimeSeconds>5.0</elapsedTimeSeconds>
               <status>OK</status>
               <distanceMeters>27.90894700354487</distanceMeters>
               <coordinates>-1.351356,47.447160</coordinates>
            </timeLineItem>
            <timeLineItem>
               <elapsedTimeSeconds>15.0</elapsedTimeSeconds>
               <status>OK</status>
               <distanceMeters>83.72684101063462</distanceMeters>
               <coordinates>-1.351156,47.447643</coordinates>
            </timeLineItem>
         </RouteResult>
      </ns2:routeV2Response>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/route/v2.json?origin=-1.351448,47.446923&destination=-1.34529,47.4479931&waypoints=-1.34981,47.44837

JSON-P query

http://<server>/<webapp>/api/lbs/route/v2.json?origin=-1.351448,47.446923&destination=-1.34529,47.4479931&waypoints=-1.34981,47.44837&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/route/v2.xml?origin=-1.351448,47.446923&destination=-1.34529,47.4479931&waypoints=-1.34981,47.44837

Response

The response is always in UTF-8 format.

JSON format

{
   "message":null,
   "status":"OK",
   "distance":"640 m",
   "duration":"0:02:06",
   "distanceMeters":"639.97",
   "durationSeconds":"126.55",
   "bounds":"-1.351448,47.446922;-1.345263,47.44848",
   "geometryWkt":"LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
   "simplifiedWkt":"LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
   "legs":[
      {
         "distance":"233 m",
         "duration":"0:00:46",
         "distanceMeters":"233.09",
         "durationSeconds":"46.21",
         "steps":[
            {
               "distance":"139 m",
               "duration":"0:00:29",
               "distanceMeters":"138.59",
               "durationSeconds":"29.21",
               "navInstruction":null,
               "name":"RUE LA FONTAINE BRUNEAU",
               "points":[

               ]
            },
            {
                [...]
            }
         ]
      },
      {
         "distance":"407 m",
         "duration":"0:01:20",
         "distanceMeters":"406.88",
         "durationSeconds":"80.34",
         "steps":[
            {
               "distance":"18 m",
               "duration":"0:00:03",
               "distanceMeters":"17.63",
               "durationSeconds":"3.17",
               "navInstruction":null,
               "name":"",
               "points":[

               ]
            },
            {
                [...]
            }
         ]
      }
   ],
   "startDateTime":null,
   "finishDateTime":null
}

JSON-P format

myCallback(
    {
       "message":null,
       "status":"OK",
       "distance":"640 m",
       "duration":"0:02:06",
       "distanceMeters":"639.97",
       "durationSeconds":"126.55",
       "bounds":"-1.351448,47.446922;-1.345263,47.44848",
       "geometryWkt":"LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
       "simplifiedWkt":"LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])",
       "legs":[
          {
             "distance":"233 m",
             "duration":"0:00:46",
             "distanceMeters":"233.09",
             "durationSeconds":"46.21",
             "steps":[
                {
                   "distance":"139 m",
                   "duration":"0:00:29",
                   "distanceMeters":"138.59",
                   "durationSeconds":"29.21",
                   "navInstruction":null,
                   "name":"RUE LA FONTAINE BRUNEAU",
                   "points":[

                   ]
                },
                {
                    [...]
                }
             ]
          },
          {
             "distance":"407 m",
             "duration":"0:01:20",
             "distanceMeters":"406.88",
             "durationSeconds":"80.34",
             "steps":[
                {
                   "distance":"18 m",
                   "duration":"0:00:03",
                   "distanceMeters":"17.63",
                   "durationSeconds":"3.17",
                   "navInstruction":null,
                   "name":"",
                   "points":[

                   ]
                },
                {
                    [...]
                }
             ]
          }
       ],
       "startDateTime":null,
       "finishDateTime":null
    }
);

XML format

<?xml version="1.0" encoding="UTF-8"?>
<routeResult>
   <status>OK</status>
   <distance>640 m</distance>
   <duration>0:02:06</duration>
   <distanceMeters>639.97</distanceMeters>
   <durationSeconds>126.55</durationSeconds>
   <bounds>-1.351448,47.446922;-1.345263,47.44848</bounds>
   <geometryWkt>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</geometryWkt>
   <simplifiedWkt>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</simplifiedWkt>
   <leg>
      <distance>233 m</distance>
      <duration>0:00:46</duration>
      <distanceMeters>233.09</distanceMeters>
      <durationSeconds>46.21</durationSeconds>
      <step>
         <distance>139 m</distance>
         <duration>0:00:29</duration>
         <distanceMeters>138.59</distanceMeters>
         <durationSeconds>29.21</durationSeconds>
         <name>RUE LA FONTAINE BRUNEAU</name>
      </step>
      <step>
         [...]
      </step>
   </leg>
   <leg>
      <distance>407 m</distance>
      <duration>0:01:20</duration>
      <distanceMeters>406.88</distanceMeters>
      <durationSeconds>80.34</durationSeconds>
      <step>
         <distance>18 m</distance>
         <duration>0:00:03</duration>
         <distanceMeters>17.63</distanceMeters>
         <durationSeconds>3.17</durationSeconds>
         <name />
      </step>
      <step>
         [...]
      </step>
   </leg>
</routeResult>

JavaScript API

Include the JavaScript library

var routeCtrl = new GCUI.Control.Route();
routeCtrl.route({
    url:'http://<server>/<webapp>/api/lbs/route/v2.json',
    tolerance : 100,
    origin : new OpenLayers.LonLat(0.691012, 47.384813),
    destination : new OpenLayers.LonLat(0.691012, 47.384813),
    waypoints : [ new OpenLayers.LonLat(2.344408, 49.898798) ],
    callback : function(result, options) {
        console.log(result);
    }
});

The result variable is in JSON format as described above. The callback function passed to parameter is called at the end of the route calculation.

Possible responses

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

<?xml version="1.0" encoding="UTF-8"?>
<routeResult>
   <status>OK</status>
   <distance>640 m</distance>
   <duration>0:02:06</duration>
   <distanceMeters>639.97</distanceMeters>
   <durationSeconds>126.55</durationSeconds>
   <bounds>-1.351448,47.446922;-1.345263,47.44848</bounds>
   <geometryWkt>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</geometryWkt>
   <simplifiedWkt>LINESTRING (-1.351448 47.446923, -1.351439 47.446922, -1.35142 47.44699, [...])</simplifiedWkt>
   <leg>
      <distance>233 m</distance>
      <duration>0:00:46</duration>
      <distanceMeters>233.09</distanceMeters>
      <durationSeconds>46.21</durationSeconds>
      <step>
         <distance>139 m</distance>
         <duration>0:00:29</duration>
         <distanceMeters>138.59</distanceMeters>
         <durationSeconds>29.21</durationSeconds>
         <name>RUE LA FONTAINE BRUNEAU</name>
      </step>
      <step>
         [...]
      </step>
   </leg>
   <leg>
      <distance>407 m</distance>
      <duration>0:01:20</duration>
      <distanceMeters>406.88</distanceMeters>
      <durationSeconds>80.34</durationSeconds>
      <step>
         <distance>18 m</distance>
         <duration>0:00:03</duration>
         <distanceMeters>17.63</distanceMeters>
         <durationSeconds>3.17</durationSeconds>
         <name />
      </step>
      <step>
         [...]
      </step>
   </leg>
</routeResult>

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

<routeResult>
   <message>Origin and destination must be not null</message>
   <status>ERROR</status>
</routeResult>

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

<routeResult>
   <message>Origin, destination and waypoints should be represented by a couple of coordinates</message>
   <status>ERROR</status>
</routeResult>

Case of a faulty type (serviceResult/status is ERROR)

<serviceResult>
        <message>NumberFormatException: For input string: "AAA"</message>
        <status>ERROR</status>
</serviceResult>

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

<serviceResult>
   <message>ServiceException: Error in route computation
Error in smartrouting
Failed to execute calculateRoute
com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect waypoint { 146.691012, 47.384813, 0.000000 }
failed to connect waypoint { 146.691012, 47.384813, 0.000000 }</message>
   <status>ERROR</status>
</serviceResult>

Case of a problem with the graph: absent file, faulty filepath, etc… (serviceResult/status is ERROR)

<serviceResult>
    <message>ServiceException: Error in route computation
Error in smartrouting
datasource is null</message>
    <status>ERROR</status>
</serviceResult>

V1

Parameters / properties

Input

parameter	description	optional	default
origin	Start point coordinates. The longitude and latitude coordinates are separated by , characters.	no
destination	Finish point coordinates. The longitude and latitude coordinates are separated by the , character	no
waypoints	Coordinates for route stops. Each pair of coordinates for a stop is framed by the <waypoint> tag The longitude and latitude coordinates are separated by the , character	yes
method	the shortest (distance) and fastest (time) route	yes	time
format	- standard: result = route summary / waypoints / geometry in wkt format / simplified geometry in wkt format / list of concatenated segments (without geometries) - extended: result = route summary / waypoints / simplified geometry in wkt format / list of non-concatenated segments (with geometries) - summary: result = route summary - geometry: result = route summary / waypoints / geometry in wkt format - simplifiedgeometry: result = route summary / waypoints / simplified geometry in wkt format - geometries: result = route summary / waypoints / geometry in wkt format / simplified geometry in wkt format - brief: result = route summary / list of segments with duration and distance - standardext: result = route summary / waypoints / list of concatenated segments with duration distance and geometry.	yes	standard
projection	Deprecated, replaced by srs	yes
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes
tolerance	Tolerance distance (in metres) for the geometry simplification.	yes
graphName	Name of the graph to use	yes
map	Deprecated: Name of the map to use	yes
applyMapPrecisionOut	Deprecated: Precision of the map	yes
startDateTime	Start 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 start on 21 January 2014, at 9.00am in Paris	yes
profileId	Vehicle identifier (saved under vehicle profiles) to use	yes
profileName	Vehicle profile (saved under vehicle profiles) to use	yes
rejectFlags	Deprecated, replaced by exclusions	yes
exclusions	List of restriction rules to use, separated by the , or ; character (Example: Toll, Tunnel, Bridge)	yes

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	string	0/1	Total route distance in metres.
durationSeconds	string	0/1	Total duration of the route in seconds.
waypoints	string	0/1	Waypoints (BoundingBox) for the route geometry.
geometryWkt	string	0/1	Geometry of the route in WKT format
simplifiedWkt	string	0/1	Simplified geometry in WKT format.
leg (or legs in JSON / JSON-P)	subRoute (or array in JSON / JSON-P)	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
timeLineItem	timellineItem (or array in JSON / JSON-P)	0/unlimited	Not implemented in this version.

Route segment (subRoute)

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	string	0/1	Distance covered by the route segment in metres.
durationSeconds	string	0/1	Duration of the route segment in seconds.
step or (or steps in JSON / JSON-P)	segment (or array in JSON / JSON-P)	0/unlimited	List of component segments in the route segments

Route segment (segment)

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	string	0/1	Distance covered by the route segment in metres.
durationSeconds	string	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.
point	string	0/unlimited	List of coordinates separated by the , character

SOAP

WSDL

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

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:route>
         <!--Optional:-->
         <request>
            <origin>
               <x>0.691012</x>
               <y>47.384813</y>
            </origin>
            <destination>
               <x>0.693012</x>
               <y>47.385813</y>
            </destination>
            <!--Optional:-->
            <waypoints>
               <!--Zero or more repetitions:-->
               <waypoint>
                  <x>0.692012</x>
                  <y>47.384813</y>
               </waypoint>
            </waypoints>
            <!--Optional:-->
            <srs></srs>
            <!--Optional:-->
            <method></method>
            <!--Optional:-->
            <format></format>
            <!--Optional:-->
            <tolerance></tolerance>
            <!--Optional:-->
            <graphName></graphName>
            <!--Optional:-->
            <startDateTime></startDateTime>
            <!--Optional:-->
            <profileId></profileId>
            <!--Optional:-->
            <profileName></profileName>
            <!--Zero or more repetitions:-->
            <rejectFlags></rejectFlags>
            <!--Optional:-->
            <exclusions>
               <!--Zero or more repetitions:-->
               <exclusion></exclusion>
            </exclusions>
         </request>
      </sch:route>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:routeResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
         <RouteResult>
            <status>OK</status>
            <distance>577 m</distance>
            <duration>0:02:49</duration>
            <bounds>0.69089,47.38404;0.693012,47.386078</bounds>
            <geometryWkt>LINESTRING (0.6910119767724592 47.38481290982329, 0.6910138207911578 47.384806371938815, ...)</geometryWkt>
            <simplifiedWkt>LINESTRING (0.6910119767724592 47.38481290982329, 0.6910138207911578 47.384806371938815, ...)</simplifiedWkt>
            <leg>
               <distance>266 m</distance>
               <duration>0:01:08</duration>
               <step>
                  <distance>10</distance>
                  <duration>2</duration>
                  <name>RUE EUPATORIA</name>
               </step>
               <step>
                  <distance>86</distance>
                  <duration>18</duration>
                  <navInstruction>L</navInstruction>
                  <name>AVENUE DE GRAMMONT</name>
               </step>
               <step>
                  <distance>13</distance>
                  <duration>2</duration>
                  <navInstruction>L</navInstruction>
                  <name>PLACE VAILLANT</name>
               </step>
               <step>
                  <distance>66</distance>
                  <duration>12</duration>
                  <navInstruction>L</navInstruction>
                  <name>AVENUE DE GRAMMONT</name>
               </step>
               <step>
                  <distance>89</distance>
                  <duration>32</duration>
                  <navInstruction>R</navInstruction>
                  <name>RUE PARMENTIER</name>
               </step>
            </leg>
            <leg>
               <distance>311 m</distance>
               <duration>0:01:40</duration>
               <step>
                  <distance>90</distance>
                  <duration>33</duration>
                  <name>RUE PARMENTIER</name>
               </step>
               <step>
                  <distance>153</distance>
                  <duration>32</duration>
                  <navInstruction>L</navInstruction>
                  <name>RUE MICHELET</name>
               </step>
               <step>
                  <distance>66</distance>
                  <duration>35</duration>
                  <navInstruction>R</navInstruction>
                  <name>RUE DUPORTAL</name>
               </step>
            </leg>
         </RouteResult>
      </ns2:routeResponse>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/route.json?origin=0.691012,47.384813&destination=0.693012,47.385813&waypoints=0.692012,47.384813

JSON-P query

http://<server>/<webapp>/api/lbs/route.json?origin=0.691012,47.384813&destination=0.693012,47.385813&waypoints=0.692012,47.384813&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/route.xml?origin=0.691012,47.384813&destination=0.693012,47.385813&waypoints=0.692012,47.384813

Response

The response is always in UTF-8 format.

JSON format

{
        "message":null,"status":"OK",
        "distance":"577 m","duration":"0:02:49","bounds":"475757.89,2266229.66;475920.47,2266453.7",
        "geometryWkt":"LINESTRING (475767.17 2266316.12, 475767.3 2266315.39, ...)",
        "legs":
                [
                        {"distance":"266 m","duration":"0:01:08",
                                "steps":
                                        [
                                                {"distance":"10","duration":"2","navInstruction":null,"name":"RUE EUPATORIA","points":[]},
                                                {"distance":"86","duration":"18","navInstruction":"L","name":"AVENUE DE GRAMMONT","points":[]},
                                                {"distance":"13","duration":"2","navInstruction":"L","name":"PLACE VAILLANT","points":[]},
                                                {"distance":"66","duration":"12","navInstruction":"L","name":"AVENUE DE GRAMMONT","points":[]},
                                                {"distance":"89","duration":"32","navInstruction":"R","name":"RUE PARMENTIER","points":[]}
                                        ]
                        },
                        {"distance":"311 m","duration":"0:01:40",
                                "steps":
                                        [
                                                {"distance":"90","duration":"33","navInstruction":null,"name":"RUE PARMENTIER","points":[]},
                                                {"distance":"153","duration":"32","navInstruction":"L","name":"RUE MICHELET","points":[]},
                                                {"distance":"66","duration":"35","navInstruction":"R","name":"RUE DUPORTAL","points":[]}
                                        ]
                                }
                ],
        "startDateTime":null,"finishDateTime":null
}

JSON-P format

myCallback(
        {
                "message":null,"status":"OK",
                "distance":"577 m","duration":"0:02:49","bounds":"475757.89,2266229.66;475920.47,2266453.7",
                "geometryWkt":"LINESTRING (475767.17 2266316.12, 475767.3 2266315.39, ...)",
                "legs":
                        [
                                {"distance":"266 m","duration":"0:01:08",
                                "steps":
                                        [
                                                {"distance":"10","duration":"2","navInstruction":null,"name":"RUE EUPATORIA","points":[]},
                                                {"distance":"86","duration":"18","navInstruction":"L","name":"AVENUE DE GRAMMONT","points":[]},
                                                {"distance":"13","duration":"2","navInstruction":"L","name":"PLACE VAILLANT","points":[]},
                                                {"distance":"66","duration":"12","navInstruction":"L","name":"AVENUE DE GRAMMONT","points":[]},
                                                {"distance":"89","duration":"32","navInstruction":"R","name":"RUE PARMENTIER","points":[]}
                                        ]
                                },
                                {"distance":"311 m","duration":"0:01:40",
                                "steps":
                                        [
                                                {"distance":"90","duration":"33","navInstruction":null,"name":"RUE PARMENTIER","points":[]},
                                                {"distance":"153","duration":"32","navInstruction":"L","name":"RUE MICHELET","points":[]},
                                                {"distance":"66","duration":"35","navInstruction":"R","name":"RUE DUPORTAL","points":[]}
                                        ]
                                }
                        ],
                "startDateTime":null,"finishDateTime":null
        }
);

XML format

<routeResult>
        <status>OK</status>
        <distance>577 m</distance>
        <duration>0:02:49</duration>
        <bounds>475757.89,2266229.66;475920.47,2266453.7</bounds>
        <geometryWkt>LINESTRING (475767.17 2266316.12, 475767.3 2266315.39, ...)</geometryWkt>
        <simplifiedWkt>LINESTRING (475767.17 2266316.12, 475767.3 2266315.39, ...)</simplifiedWkt>
        <leg>
                <distance>266 m</distance>
                <duration>0:01:08</duration>
                <step>
                        <distance>10</distance>
                        <duration>2</duration>
                        <name>RUE EUPATORIA</name>
                </step>
                <step>
                        <distance>86</distance>
                        <duration>18</duration>
                        <navInstruction>L</navInstruction>
                        <name>AVENUE DE GRAMMONT</name>
                </step>
                <step>
                        <distance>13</distance>
                        <duration>2</duration>
                        <navInstruction>L</navInstruction>
                        <name>PLACE VAILLANT</name>
                </step>
                <step>
                        <distance>66</distance>
                        <duration>12</duration>
                        <navInstruction>L</navInstruction>
                        <name>AVENUE DE GRAMMONT</name>
                </step>
                <step>
                        <distance>89</distance>
                        <duration>32</duration>
                        <navInstruction>R</navInstruction>
                        <name>RUE PARMENTIER</name>
                </step>
        </leg>
        <leg>
                <distance>311 m</distance>
                <duration>0:01:40</duration>
                <step>
                        <distance>90</distance>
                        <duration>33</duration>
                        <name>RUE PARMENTIER</name>
                </step>
                <step>
                        <distance>153</distance>
                        <duration>32</duration>
                        <navInstruction>L</navInstruction>
                        <name>RUE MICHELET</name>
                </step>
                <step>
                        <distance>66</distance>
                        <duration>35</duration>
                        <navInstruction>R</navInstruction>
                        <name>RUE DUPORTAL</name>
                </step>
        </leg>
</routeResult>

JavaScript API

Include the JavaScript library

var routeCtrl = new GCUI.Control.Route();
routeCtrl.route({
    url:'http://<server>/<webapp>/api/lbs/route.json',
    tolerance : 100,
    origin : new OpenLayers.LonLat(0.691012, 47.384813),
    destination : new OpenLayers.LonLat(0.691012, 47.384813),
    waypoints : [ new OpenLayers.LonLat(2.344408, 49.898798) ],
    callback : function(result, options) {
        console.log(result);
    }
});

The result variable is in JSON format as described above. The callback function passed to parameter is called at the end of the route calculation.

Possible responses

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

<routeResult>
    <status>OK</status>
    <distance>1.66 Km</distance>
    <duration>0:04:53</duration>
    <bounds>2.423385,48.84452;2.43999,48.84741</bounds>
    <geometryWkt>LINESTRING (2.4233899276812516 48.84461991900793, 2.4233847309012826 48.84462042192212, ...)</geometryWkt>
    <simplifiedWkt>LINESTRING (2.4233899276812516 48.84461991900793, 2.4233847309012826 48.84462042192212, ...)</simplifiedWkt>
    <leg>
        <distance>1.66 Km</distance>
        <duration>0:04:53</duration>
        <step>
            <distance>147</distance>
            <duration>31</duration>
            <name>AVENUE PASTEUR</name>
        </step>
        <step>
            <distance>1108</distance>
            <duration>159</duration>
            <navInstruction>R</navInstruction>
            <name>AVENUE DE PARIS</name>
        </step>
                ...
        </step>
    </leg>
</routeResult>

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

<routeResult>
    <message>Origin and destination must be not null</message>
    <status>ERROR</status>
</routeResult>

Case of a faulty type (serviceResult/status is ERROR)

<serviceResult>
        <message>NumberFormatException: For input string: "AAA"</message>
        <status>ERROR</status>
</serviceResult>

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

<serviceResult>
    <message>ServiceException: Error in route computation
Error in smartrouting
Failed to execute calculateRoute
com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect waypoint { 243966.000000, 48.847410, 0.000000 }
failed to connect waypoint { 243966.000000, 48.847410, 0.000000 }</message>
    <status>ERROR</status>
</serviceResult>

Case of a problem with the graph: absent file, faulty filepath, etc… (serviceResult/status is ERROR)

<serviceResult>
    <message>ServiceException: Error in route computation
Error in smartrouting
datasource is null</message>
    <status>ERROR</status>
</serviceResult>

FAQ

1. Is it possible to give priority to either journey time or distance?
2. Can I use aliases instead of .siti file names to call a datasource?
3. How can I use route statistics?
4. Is the order of points important?
5. How can I perform a route calculation excluding toll roads?
6. What are Speed Patterns? How can I use them?
7. How to use Heavy Goods Vehicle attributes?
8. How is carbon footprint for a route calculated?

1.	Is it possible to give priority to either journey time or distance?
	Yes, by changing the method `method` distance or time.
2.	Can I use aliases instead of .siti file names to call a datasource?
	Yes, refer to details in the FAQ of the reverse geocoding Web Service.
3.	How can I use route statistics?
	Check that the graph does contain these statistics and use these parameters: `computeOptions` with a value of trafficPatterns and `startDateTime` to specify the departure date/time.
4.	Is the order of points important?
	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.
5.	How can I perform a route calculation excluding toll roads?
	If the Toll constraint has been included in the graph, place an exclusion in `exclusions`: <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas"> <soapenv:Header/> <soapenv:Body> <sch:route> <!--Optional:--> <request> <origin> <x>0.691012</x> <y>47.384813</y> </origin> <destination> <x>0.693012</x> <y>47.385813</y> </destination> <!--Zero or more repetitions:--> <waypoints> <waypoint> <x>0.692012</x> <y>47.384813</y> </waypoint> </waypoints> <!--Optional:--> <srs></srs> <!--Optional:--> <method></method> <!--Optional:--> <format></format> <tolerance></tolerance> <!--Optional:--> <graphName></graphName> <!--Optional:--> <startDateTime></startDateTime> <!--Optional:--> <profileId></profileId> <!--Optional:--> <profileName></profileName> <!--Zero or more repetitions:--> <exclusions>Toll</exclusions> </request> </sch:route> </soapenv:Body> </soapenv:Envelope>
6.	What are Speed Patterns? How can I use them?
	In order to propose journey times that are as accurate as possible and reflect changing traffic conditions, graphs supplied by GEOCONCEPT SAS include, from version M18 upwards, 5 speed profiles (Speed Patterns) for cars and lorries, to take into account the different levels of congestion during the course of one day: standard normal-speed corresponds to the speed at a time when the roads have an average congestion level (eg 11.00am) night fast-speed corresponds to a very fluid traffic situation, often experienced at night-time (3.00am) congested slow-speed corresponds to the times when traffic is densest (8.00am) rush hour very-slow-speed corresponds to times when traffic is densest in urban and built-up areas, and is slower than the speed above (8.00am) default default corresponds to speeds averaged out over an entire day To use them, you need to pass to parameter, when calling the web service, the `computeOptions` parameter with the speedPattern option and specify the value of the Speed Pattern requested, without forgetting a vehicle profile Example: + http://<server>/<webapp>/api/lbs/route/v5.xml?origin=-1.519363,47.215945&destination=-1.559309,47.213465&computeOptions=speedPattern:fast-speed&profileId=1 + Returns a journey of 707 seconds as against 817 seconds for a slow-speed speedPattern.
7.	How to use Heavy Goods Vehicle attributes?
	The graph must include the attributes for Heavy Goods Vehicles (as standard in the graphs supplied by GEOCONCEPT SAS from version M18 upwards) and either calculate an itinerary using a vehicle profile using restrictions (cf. the catalogue of vehicles, editable, defined in the SmartRoutingVehicles.xml file, stored in the folder `‘<GEOCONCEPT_WEB_HOME>’'\smartrouting\jee\smartrouting\conf\ ), or overwrite the call to the web service by using the `computeOptions` parameter with the options length, width, height, weight, axles and/or weightPerAxle. Example for a journey with a vehicle 4.5 metres high: http://<server>/<webapp>/api/lbs/route/v5.xml?origin=-1.543363,47.215945&destination=-1.550309,47.213465&computeOptions=height:450 Returns a journey of 1,529 metres as against 624 metres without any height restriction.
8.	How is carbon footprint for a route calculated?
	The carbon footprint calculation takes into account vehicle type, fuel type, and speed - road section by road section: note that 10 km in a built-up area does not have the same carbon footprint as 10 kms in the countryside. The carbon footprint for the itinerary is calculated automatically EITHER using a vehicle profile that has pre-assigned restrictions as defined in the vehicle catalogue, which can be edited, and is located in the SmartRoutingVehicles.xml file in the folder `‘<GEOCONCEPT_WEB_HOME>’'\smartrouting\jee\smartrouting\conf\ ), OR by overwriting the restriction values at the time of the call to the web service using `computeOptions` and the fuelType, averageConsumption and/or customAverageCO2UnitEmission options. The available values are fuelType with possible values: NoFuel Diesel UnleadedFuel LGP CustomFuelType (allows you to personalise a value in kgs of CO2 per litre, to be entered under customAverageCO2UnitEmission) averageConsumption allows you to indicate the average vehicle consumption for 100 kilometers Example, for the following configuration: + <vehicle id="10" name="Car"> <speedProfile>Cars</speedProfile> <speedProfileId>3</speedProfileId> <rejectFlag>Automobiles</rejectFlag> <snapSpeed>4</snapSpeed> <fuelType>UndefinedFuelType</fuelType> </vehicle> <vehicle id="11" name="Car UnleadedFuel"> <speedProfile>Cars</speedProfile> <speedProfileId>3</speedProfileId> <rejectFlag>Automobiles</rejectFlag> <speedPatternsProfile>Cars SpeedPatterns</speedPatternsProfile> <snapSpeed>4</snapSpeed> <fuelType>UnleadedFuel</fuelType> <averageConsumption>7.27</averageConsumption> </vehicle> <vehicle id="12" name="Car Diesel"> <speedProfile>Cars</speedProfile> <speedProfileId>3</speedProfileId> <rejectFlag>Automobiles</rejectFlag> <speedPatternsProfile>Cars SpeedPatterns</speedPatternsProfile> <snapSpeed>4</snapSpeed> <fuelType>Diesel</fuelType> <averageConsumption>6.06</averageConsumption> </vehicle> <vehicle id="30" name="Truck CustomFuelType"> <speedProfile>Trucks</speedProfile> <speedProfileId>5</speedProfileId> <rejectFlag>Trucks</rejectFlag> <snapSpeed>4</snapSpeed> <fuelType>CustomFuelType</fuelType> <customAverageCO2UnitEmission>5</customAverageCO2UnitEmission> </vehicle> <vehicle id="32" name="Truck Diesel"> <speedProfile>Trucks</speedProfile> <speedProfileId>5</speedProfileId> <rejectFlag>Trucks</rejectFlag> <speedPatternsProfile>Trucks SpeedPatterns</speedPatternsProfile> <snapSpeed>4</snapSpeed> <fuelType>Diesel</fuelType> <averageConsumption>34</averageConsumption> </vehicle> + the following is obtained: + Car + http://<server>/<webapp>/api/lbs/route/v5.xml?origin=-0.978536,47.443316&destination=-2.511388,47.303726&profileId=10 + returns in kgs the CO2 equivalent: + <carbonFootprint>0.0</carbonFootprint> + Car UnleadedFuel + http://<server>/<webapp>/api/lbs/route/v5.xml?origin=-0.978536,47.443316&destination=-2.511388,47.303726&profileId=11 + returns in kgs the CO2 equivalent: + <carbonFootprint>31.151</carbonFootprint> + Car Diesel + http://<server>/<webapp>/api/lbs/route/v5.xml?origin=-0.978536,47.443316&destination=-2.511388,47.303726&profileId=12 + returns in kgs the CO2 equivalent: + <carbonFootprint>26.117</carbonFootprint> + Truck CustomFuelType + http://<server>/<webapp>/api/lbs/route/v5.xml?origin=-0.978536,47.443316&destination=-2.511388,47.303726&profileId=30 + returns in kgs the CO2 equivalent: + <carbonFootprint>43.914</carbonFootprint> + Truck Diesel + http://<server>/<webapp>/api/lbs/route/v5.xml?origin=-0.978536,47.443316&destination=-2.511388,47.303726&profileId=32 + returns in kgs the CO2 equivalent: + <carbonFootprint>153.081</carbonFootprint>

Prev	Up	Next
	Home

Web Services documentation of Geoconcept Web - Web Services

Basic principles

Availability

Version change

V6

Parameters / properties

SOAP

REST

Possible responses

V5

Parameters / properties

SOAP

REST

Possible responses

V4

Parameters / properties

SOAP

REST

Possible responses

V3

Parameters / properties

SOAP

REST

Possible responses

V2

Parameters / properties

SOAP

REST

Possible responses

V1

Parameters / properties

SOAP

REST

Possible responses

FAQ