Routing

Web services

Geocoding API documentation, available via HTTP-JSON/XML service.

URL base service:

* API KEY. Same KEY used in maps API js

HTTP requests in GET or POST
Response in JSON / XML format

Route (car)

Request:

Example:

&cmd=route&report=0&mo_o=41.120380332,1.244894304&mo_d=39.584958220,2.663190407&mocs=gdd&weight=time&iweight=realtime,toll,ferry&stagegeometry=0&stagegeometrytolerance=0&stagegeometrysrs=EPSG:4326

Where:

  • report=0 / report = 1 route report with text instructions (optional). 
  • mo_o= origin - Y,X in case of geographical coordinate system (ex: London = 51.50015,-0.12624), X,Y for other coordinate systems (mercator, UTM , etc)
  • mo_d= destination - Y,X in case of geographical coordinate system (ex: London = 51.50015,-0.12624), X,Y for other coordinate systems (mercator, UTM , etc)
  • mo_1,n= waypoints - Y,X in case of geographical coordinate system (ex: London = 51.50015,-0.12624), X,Y for other coordinate systems (mercator, UTM , etc) -> 1, ... n
  • weight= route type:
    • time (quickest)
    • distance (shortest)
    • money (quickest avoiding toll roads)
    • realtime (quickest, considering real time traffic data).
  • iweight= provides additional information on route calculation. It allows to indicate different parameters, separated by commas:
    • realtime: Use this parameter to obtain the time of the route, based on the current traffic state.
    • toll: Use this parameter to determine if the route passes through a toll road section. Use only if &report = 0
    • ferry: Use this parameter to obtain if the route passes through a ferry leg. Use only if &report = 0
  • stagegeometry=1/0 Include or not the geometry of the path (polyline) in WKT format. In case the request includes waypoints, the geometry is divided for each stage
  • stagegeometrytolerance=10 Route geometry simplification, in meters. Default: 100 m
  • stagegeometrysrs=EPSG:4326 Route geometry coordinate system (EPSG:4326 = geographic coordinate system)


Routing based on departure time:

  • weight= route type:
    • sptime (quickest, based on departure time)
    • spmoney (quickest, based on departure time and avoiding toll roads)
  • departuretime= departure date and time, in ISO 8601 format. UTC time example:  2019-10-16T07:30:12Z  *Mandatory if using weight=sptime/spmoney

 

Specific parameters to include temporary restrictions (roads closed on certain days and/or time slots):

Parameter Description
TRSTART Starting date and time measured in milliseconds since epoch (January 1, 1970 UTC). It is only taken into account to avoid temporary restrictions.
TRDEPARTURETIME Starting date and time in ISO 8601 format. Example for UTC time: 2007-04-05T14:30:12Z. It is only taken into account to avoid temporary restrictions. It is converted to TRSTART format internally.
TRINFODATE Starting date. API informs (not avoids) temporary restrictions in YYYYMMDD format.
TRINFODAYS Number of days from TRINFODATE on which will be reported the temporary restrictions. (Default 1)

 

Optional:

  • alternatives= use this parameter for getting malternative routes. It only works on routes optimized by time and distance. Default: false
  • direction= specify how to choose the direction of departure / arrival at the stops. Default: "default" value.
    • default: If it is a secondary road, uses both directions. If it is an important road, uses the one where the stop is located on the right. If an angle is specified, uses the direction closest to the angle.
    • both: uses both road directions.
  • blockrealtime=let you to prevent the passage of roads blocked by works or other damages. This blocking is applied even if there are no alternative routes: if there is no possible route, returns an error. Default: false.
  • avoidblockrealtime=let you to prevent the passage of roads blocked by works or other damages. This blocking is only applied if there are alternative routes. Default: true.
  • blockferries=never use ferries, returning error if there's no possible route. Por defecto: false.
  • avoidferries=try to avoid ferries, but will take it if's the only way to get a route. Default: true.
  • lang= report text language, if &report=1.


lang values:

Value Desc
es Spanish
fr French
de German
it Italian
ca Catalan
pt Portuguese
en English
nl Dutch

Advanced parameters: route optimization:

  • reorder=1 Optimize the route considering the travel time or distance. Up to 100 waypoints. 
  • Time restrictions:
Value Description
STARTWINDOWx_1 First date and time (FROM) restriction for every waypoint, in ISO 8601 format. Only used if reorder=1. Example: &startwindow1_1=2021-10-21T07:30:00Z
ENDWINDOWx_1 First date and time (TO) restriction for every waypoint, in ISO 8601 format. Only used if reorder=1. Example: &endwindow1_1=2021-10-21T07:40:00Z
STARTWINDOWx_2 Second date and time (FROM) restriction for every waypoint, in ISO 8601 format. Only used if reorder=1. Example: &startwindow1_2=2021-10-21T17:30:00Z
ENDWINDOWx_2 Second date and time (TO) restriction for every waypoint, in ISO 8601 format. Only used if reorder=1. Example: &endwindow1_2=2021-10-21T22:40:00Z
  • duration_x Stop duration, in seconds. Default value: 0
  • priority_x Value from 0 to 100, meaning the priority including every waypoint in the optimized route. It only will used if some waypoints can't be attended. Only used if reorder=1. 


Response:

<cercalia cmd="route" version="1">
	<route dest="%" dist="356.697" hasferries="1" hastolls="1" icost="67707521,125,3" id="16474053,16410248|0.09513969,0.32824484" iweight="realtime,toll,ferry" orig="%" realtime="18:50:27" time="18:48:27" weight="time">
		<stoplist>
			<stop by="false" id="o">
				<mo id="">
					<coord x="1.24489430" y="41.120380332"/>
				</mo>
			</stop>
			<stop by="false" id="d">
				<mo id="">
					<coord x="2.663190407" y="39.584958220"/>
				</mo>
			</stop>
		</stoplist>
		<getpoicats/>
		<stages>
			<stage dest="%" dest_stop_id="d" dist="356.697" orig="%" orig_stop_id="o" realtime="18:50:27" time="18:48:27" weight=""/>
		</stages>
	</route>
	<server>http://c6.cercalia.com</server>
</cercalia>

Where:

  • id= Route id
  • dist= route distance, in km
  • time= route time (HH:MM:SS)
  • realtime= route time, including real time traffic (HH:MM:SS), if iweight=realtime
  • hasferries= informs if the route includes some ferry (only if request includes &iweight=ferry and &report=0)
  • hastolls= informs if the route includes some toll roads (only if request includes &iweight=toll and &report=0)

* Note:

In the case of routes longer than 24 hours, time is expressed in accumulated hours. Example: 2 days "48:00:00", 10 days "240:00:00".

 

Stagegeometry:

Response includes a WKT with the route polyline, using standard Well-known Text Representation for Geometry".
 

Geometry Type Text Literal Representation Comment
Point 'POINT (10 10)' a Point
LineString 'LINESTRING ( 10 10, 20 20, 30 40)' a LineString with 3 points
Polygon 'POLYGON ((10 10, 10 20, 20 20, 20 15, 10 10))' a Polygon with 1 exteriorRing and 0 interiorRings
Multipoint 'MULTIPOINT (10 10, 20 20)' a MultiPoint with 2 points
MultiLineString 'MULTILINESTRING ((10 10, 20 20), (15 15, 30 15))' a MultiLineString with 2 linestrings
MultiPolygon 'MULTIPOLYGON ( ((10 10, 10 20, 20 20, 20 15, 10 10)), ((60 60, 70 70, 80 60, 60 60 ) ))' a MultiPolygon with 2 polygons
GeomCollection 'GEOMETRYCOLLECTION (POINT (10 10), POINT (30 30), LINESTRING (15 15, 20 20))' a GeometryCollection consisting of 2 Point values and a LineString value

More info: OpenGIS® Implementation Specification for Geographic information - Simple feature access - Part 1: Common architecture.

In case of route polyline, geometry type can be LineString or MultiLineString.

Route report:

In case of &report=1, response includes the textual route description. You can get it in several languages, using &lang= parameter.

<cercalia cmd="route" version="1">
	<route coste_v1="0.0" coste_v2="0.0" coste_v3="0.0" dest="%" dist="1.2" icost="223570" id="13171123,13177702|0.18124574540503743,0.8983606557377048|" iweight="realtime" lang="es" mindist="1000" orig="%" realtime="00:03:43" time="00:03:33" weight="time">
		<stoplist>
			<stop by="false" id="o">
				<mo id="">
					<coord x="-413030" y="4900888"/>
				</mo>
			</stop>
			<stop by="false" id="d">
				<mo id="">
					<coord x="-411582" y="4900474"/>
				</mo>
			</stop>
		</stoplist>
		<getpoicats/>
		<stages>
			<stage coste_v1="0.0" coste_v2="0.0" coste_v3="0.0" dest="%" dest_stop_id="d" dist="1.2" id="1,2,3,4,5,6,7" orig="%" orig_stop_id="o" time="00:03:33">
				<wkt/>
				<sub_stage angle="353.0" id="1,2,3,4,5" name="Calle de Sagasta" type="L">
					<start x="-413030" y="4900888"/>
					<end x="-411665" y="4900635"/>
					<time>00:02:52</time>
					<time_sum>00:02:52</time_sum>
					<dist>1.0</dist>
					<dist_sum>1.0</dist_sum>
					<time_seconds>173</time_seconds>
					<dist_meters>1049</dist_meters>
					<view>0</view>
					<desc>
					Partir de <b>%</b> por Calle de Alberto Aguilera hasta llegar al cruce con Glorieta de Ruiz Jiménez.<br>Seguir recto por Glorieta de Ruiz Jiménez hasta llegar al cruce con Calle de Carranza.<br>Seguir recto por Calle de Carranza hasta llegar al cruce con Glorieta de Bilbao.<br>Girar hacia la derecha y seguir por Glorieta de Bilbao hasta llegar al cruce con Calle de Sagasta.<br>Seguir recto por Calle de Sagasta hasta llegar al cruce con Calle de Antonio Flores
					</desc>
					<municipios/>
					<poilist/>
					<arealist>
						<area name="Madrid" type="U"/>
					</arealist>
				</sub_stage>
				<sub_stage angle="65.0" id="6,7" name="Calle de Serrano Anguita" type="L">
					<start x="-411665" y="4900635"/>
					<end x="-411582" y="4900474"/>
					<time>00:00:40</time>
					<time_sum>00:03:33</time_sum>
					<dist>0.2</dist>
					<dist_sum>1.2</dist_sum>
					<time_seconds>41</time_seconds>
					<dist_meters>166</dist_meters>
					<view>0</view>
					<desc>
					Girar hacia la derecha y seguir por Calle de Antonio Flores hasta llegar al cruce con Calle de Serrano Anguita.<br>Girar hacia la izquierda y seguir por Calle de Serrano Anguita en dirección a <b>%</b>.
					</desc>
					<municipios/>
					<poilist/>
					<arealist>
						<area name="Madrid" type="U"/>
					</arealist>
				</sub_stage>
			</stage>
		</stages>
	</route>
	<server>http://cercalia-tomcat-lbs-instance4:8080</server>
</cercalia>

Route (walking)

Only available for Spain and USA

Request:

Example:

&cmd=route&mo_o=[2.825707,41.973398|o]&mo_d=[2.825536,41.970830|d]&mocs=4326&weight=time&stagegeometry=true&stagegeometrysrs=EPSG:4326&net=espw&direction=both&report=0

Where:

  • report=0 route report text instructions not available
  • mo_o= origin (Y,X)
  • mo_d= destination (Y,X)
  • mo_1,n= waypoints (Y,X) -> 1, ... n
  • weight= route type:
    • time (quickest)
    • distance (shortest)
  • stagegeometry=1/0 Include or not the geometry of the path (polyline) in WKT format. In case the request includes waypoints, the geometry is divided for each stage
  • stagegeometrysrs=EPSG:4326 indica que la geometría de la polilínia se devolverá en coordenadas geográficas
  • stagegeometrytolerance=10 Route geometry simplification, in meters. Default: 100 m
  • stagegeometrysrs=EPSG:4326 Route geometry coordinate system (EPSG:4326 = geographic coordinate system)
  • net= country (espw, or usaw)
  • &direction=both (mandatory)

 

Advanced parameters: route optimization:

  • reorder=1 Optimize the route considering the travel time or distance. Up to 100 waypoints. 
  • Time restrictions:
Value Description
STARTWINDOWx_1 First date and time (FROM) restriction for every waypoint, in ISO 8601 format. Only used if reorder=1. Example: &startwindow1_1=2021-10-21T07:30:00Z
ENDWINDOWx_1 First date and time (TO) restriction for every waypoint, in ISO 8601 format. Only used if reorder=1. Example: &endwindow1_1=2021-10-21T07:40:00Z
STARTWINDOWx_2 Second date and time (FROM) restriction for every waypoint, in ISO 8601 format. Only used if reorder=1. Example: &startwindow1_2=2021-10-21T17:30:00Z
ENDWINDOWx_2 Second date and time (TO) restriction for every waypoint, in ISO 8601 format. Only used if reorder=1. Example: &endwindow1_2=2021-10-21T22:40:00Z
  • duration_x Stop duration, in seconds. Default value: 0
  • priority_x Value from 0 to 100, meaning the priority including every waypoint in the optimized route. It only will used if some waypoints can't be attended. Only used if reorder=1. 

 

Response:

  <cercalia cmd="route" version="1">
	<route dest="d" dist="0.306" id="9911054,9868590|0.6062123,0.5|espw" orig="o" time="00:04:35" weight="time">
		<stoplist>
			<stop by="false" id="o">
				<mo id="o">
					<coord x="2.825704625115002" y="41.97339605714581"/>
				</mo>
			</stop>
			<stop by="false" id="d">
				<mo id="d">
					<coord x="2.8255339452110193" y="41.97082858283375"/>
				</mo>
			</stop>
		</stoplist>
		<getpoicats/>
		<stages>
			<stage dest="d" dest_stop_id="d" dist="0.306" orig="o" orig_stop_id="o" time="00:04:35" weight="time">
				<wkt cs="EPSG:4326" tolerance="100.0">
				LINESTRING (2.825668865971416 41.9734025479364, 2.8255968272809073 41.97318154631235, 2.8255159789053366 41.97294692425489, 2.82554292836386 41.97229668143117, 2.8258303892547785 41.97087550888706, 2.8255339452110193 41.97082858283375)
				</wkt>
			</stage>
		</stages>
	</route>
	<server>lb3.cercalia.com</server>
</cercalia>

Where:

  • id= Route id
  • dist= route distance, in km
  • time= route time (HH:MM:SS)
     

Stagegeometry:

Response includes a WKT with the route polyline, using standard Well-known Text Representation for Geometry".
 

Geometry Type Text Literal Representation Comment
Point 'POINT (10 10)' a Point
LineString 'LINESTRING ( 10 10, 20 20, 30 40)' a LineString with 3 points
Polygon 'POLYGON ((10 10, 10 20, 20 20, 20 15, 10 10))' a Polygon with 1 exteriorRing and 0 interiorRings
Multipoint 'MULTIPOINT (10 10, 20 20)' a MultiPoint with 2 points
MultiLineString 'MULTILINESTRING ((10 10, 20 20), (15 15, 30 15))' a MultiLineString with 2 linestrings
MultiPolygon 'MULTIPOLYGON ( ((10 10, 10 20, 20 20, 20 15, 10 10)), ((60 60, 70 70, 80 60, 60 60 ) ))' a MultiPolygon with 2 polygons
GeomCollection 'GEOMETRYCOLLECTION (POINT (10 10), POINT (30 30), LINESTRING (15 15, 20 20))' a GeometryCollection consisting of 2 Point values and a LineString value

More info: OpenGIS® Implementation Specification for Geographic information - Simple feature access - Part 1: Common architecture.

In case of route polyline, geometry type can be LineString or MultiLineString.
 

Truck routing

Truck routing includes road logistic restrictions for providing better routes. Includes:

  • Route distance and route time
  • Route polyline (in WKT format).
  • Toll costs, available in Spain, Portugal and France.
  • Truck restrictions (weight, height, length, width, max speed).

The request & response format is the same as in the case of a normal route, but additionaly includes specific parameters to indicate the types of restrictions to take into account.

Request

Common route parameters:

  • report=0 / report = 1 route report with text instructions (optional). 
  • mo_o= origin - Y,X in case of geographical coordinate system (ex: London = 51.50015,-0.12624), X,Y for other coordinate systems (mercator, UTM , etc)
  • mo_d= destination - Y,X in case of geographical coordinate system (ex: London = 51.50015,-0.12624), X,Y for other coordinate systems (mercator, UTM , etc)
  • mo_1,n= waypoints - Y,X in case of geographical coordinate system (ex: London = 51.50015,-0.12624), X,Y for other coordinate systems (mercator, UTM , etc) -> 1, ... n
  • weight= route type:
    • time (quickest)
    • distance (shortest)
    • money (quickest avoiding toll roads)
    • realtime (quickest, considering real time traffic data).
  • iweight= provides additional information on route calculation. It allows to indicate different parameters, separated by commas:
    • realtime: Use this parameter to obtain the time of the route, based on the current traffic state.
    • toll: Use this parameter to determine if the route passes through a toll road section. Use only if &report = 0
    • ferry: Use this parameter to obtain if the route passes through a ferry leg. Use only if &report = 0
  • stagegeometry=1/0 Include or not the geometry of the path (polyline) in WKT format. In case the request includes waypoints, the geometry is divided for each stage
  • stagegeometrytolerance=10 Route geometry simplification, in meters. Default: 100 m
  • stagegeometrysrs=EPSG:4326 Route geometry coordinate system (EPSG:4326 = geographic coordinate system)

 


Truck routing specific parameters:

  • net=logistics Routing specific for trucks 
Parameter Description
VWEIGHT Vehicle weight, in tons
VAXLEWEIGHT Vehicle axle weight, in tons
VHEIGHT Vehicle height, in meters
VLENGTH Vehicle lenght, in meters
VWIDTH Vehicle width, in meters
VMAXVEL Maximum vehicle speed, in km/h
BLOCKVWEIGHT Prevent usage of restricted roads with a maximum weight lower than that indicated in the VWEIGHT parameter. Default: false.
AVOIDVWEIGHT Avoid, if possible, the usage of restricted roads with a maximum weight lower than that indicated in the VWEIGHT parameter. Default: true.
BLOCKVAXLEWEIGHT Prevent usage of restricted roads with a maximum axle weight lower than that indicated in the VAXLEWEIGHT parameter. Default: false.
AVOIDVAXLEWEIGHT Avoid, if possible, the usage of restricted roads with a maximum axle weight lower than that indicated in the VAXLEWEIGHT parameter. Default: true.
BLOCKVHEIGHT Prevent usage of restricted roads with a maximum height lower than that indicated in the VHEIGHT parameter. Default: false.
AVOIDVHEIGHT Avoid, if possible, the usage of restricted roads with a maximum height lower than that indicated in the VHEIGHT parameter. Default: true.
BLOCKVLENGTH Prevent usage of restricted roads with a maximum height lower than that indicated in the VLENGTH parameter. Default: false.
AVOIDVLENGTH Avoid, if possible, the usage of restricted roads with a maximum height lower than that indicated in the VLENGTH parameter. Default: true.
BLOCKVWIDTH Prevent usage of restricted roads with a maximum height lower than that indicated in the VWIDTH parameter. Default: false.
AVOIDVWIDTH Avoid, if possible, the usage of restricted roads with a maximum height lower than that indicated in the VWIDTH parameter. Default: true.

Example:

&cmd=route&net=logistics&mo_o=40.418372,-3.676642&mo_d=40.432961,-3.649504&mo_1=40.429048,-3.666815&mo_2=40.429446,-3.653268&weight=time&VWEIGHT=12&mocs=gdd

 

Routing based on departure time:

  • weight= route type:
    • sptime (quickest, based on departure time)
    • spmoney (quickest, based on departure time and avoiding toll roads)
  • departuretime= departure date and time, in ISO 8601 format. UTC time example:  2019-10-16T07:30:12Z  *Mandatory if using weight=sptime/spmoney

 

Specific parameters to include temporary restrictions (roads closed on certain days and/or time slots):

Parameter Description
TRSTART Starting date and time measured in milliseconds since epoch (January 1, 1970 UTC). It is only taken into account to avoid temporary restrictions.
TRDEPARTURETIME Starting date and time in ISO 8601 format. Example for UTC time: 2007-04-05T14:30:12Z. It is only taken into account to avoid temporary restrictions. It is converted to TRSTART format internally.
TRINFODATE Starting date. API informs (not avoids) temporary restrictions in YYYYMMDD format.
TRINFODAYS Number of days from TRINFODATE on which will be reported the temporary restrictions. (Default 1)

 

Optional:

  • alternatives= use this parameter for getting malternative routes. It only works on routes optimized by time and distance. Default: false
  • direction= specify how to choose the direction of departure / arrival at the stops. Default: "default" value.
    • default: If it is a secondary road, uses both directions. If it is an important road, uses the one where the stop is located on the right. If an angle is specified, uses the direction closest to the angle.
    • both: uses both road directions.
  • blockrealtime=let you to prevent the passage of roads blocked by works or other damages. This blocking is applied even if there are no alternative routes: if there is no possible route, returns an error. Default: false.
  • avoidblockrealtime=let you to prevent the passage of roads blocked by works or other damages. This blocking is only applied if there are alternative routes. Default: true.
  • blockferries=never use ferries, returning error if there's no possible route. Por defecto: false.
  • avoidferries=try to avoid ferries, but will take it if's the only way to get a route. Default: true.
  • lang= report text language, if &report=1.


lang values:

Value Desc
es Spanish
fr French
de German
it Italian
ca Catalan
pt Portuguese
en English
nl Dutch

Advanced parameters: route optimization:

  • reorder=1 Optimize the route considering the travel time or distance. Up to 100 waypoints. 
  • Time restrictions:
Value Description
STARTWINDOWx_1 First date and time (FROM) restriction for every waypoint, in ISO 8601 format. Only used if reorder=1. Example: &startwindow1_1=2021-10-21T07:30:00Z
ENDWINDOWx_1 First date and time (TO) restriction for every waypoint, in ISO 8601 format. Only used if reorder=1. Example: &endwindow1_1=2021-10-21T07:40:00Z
STARTWINDOWx_2 Second date and time (FROM) restriction for every waypoint, in ISO 8601 format. Only used if reorder=1. Example: &startwindow1_2=2021-10-21T17:30:00Z
ENDWINDOWx_2 Second date and time (TO) restriction for every waypoint, in ISO 8601 format. Only used if reorder=1. Example: &endwindow1_2=2021-10-21T22:40:00Z
  • duration_x Stop duration, in seconds. Default value: 0
  • priority_x Value from 0 to 100, meaning the priority including every waypoint in the optimized route. It only will used if some waypoints can't be attended. Only used if reorder=1. 

Response

Elem

Elem

Elem

Elem

Elem

Description

@id

 

 

 

 

Route ID

@orig

 

 

 

 

Starting point name

@dest

 

 

 

 

Destination point name

@lang

 

 

 

 

Repport language

@dist

 

 

 

 

Route distance

@time

 

 

 

 

Route time

@weight

 

 

 

 

Route type

stoplist

 

 

 

 

 

stop

 

 

 

 

@id

 

 

Stop ID (orig, dest, stage1, stage2)

ge

 

 

Stop is a geographical entity

@id

 

Geographical entity ID

@name

 

Geographical entity name

@type

 

Geographical entity type (ctry = country,ct = city,st = street,...)

name

Valor

Place name

city

@id

City ID

Valor

City Name

municipality

@id

Municipality ID

valor

Municipality name

subregion

@id

Subregion ID

valor

Subregion name

region

@id

Region ID

valor

Region name

country

@id

Country ID

valor

Country name

coord

@x

Coord X

@y

Coord Y

poi

 

 

Stop is a POI (Point of Interest)

@category_id

 

POI category

@id

 

POI ID

name

Valor

POI name

info

Valor

POI information

coord

@x

Coord X

@y

Coord Y

mo

 

 

Stop is a mobile object (coordinates)

@id

 

Mobile object ID

satus

Valor

Status

desc

Valor

Description

coord

@x

Coord X

@y

Coord Y

estages

 

 

 

 

 

stage

 

 

 

 

@orig

 

 

Stage origin

@dest

 

 

Stage destination

substage

 

 

 

@id

 

Substage ID

@angle

 

Junction angle with the previous stage

@name

 

Substage name

@type

 

Substage road type  *

desc

Valor

Substage description

time

Valor

Substage time

time_sum

Valor

Accumulated time

dist

Valor

Substage distance

dist_sum

Valor

Accumulated distance

start

 

 

 

@x

Coord. X starting point

 

@y

Coord. Y starting point

end

 

 

 

@x

Coord. X end point

 

@y

Coord. Y end point

restrictions

 

Logistics road restrictions list

restriction

See Road restrictions list

municipios

 

Municipalities crossed along the route

municipio

Municipality

@id

ID

@name

Name

* @type values (substage road type):

Value

Description

A

Highway

G

Ferry

I

Main road

K

Secondary road

J

Local roads, with no name

L

Main streets

M

Minor streets

R

Roundabout

S

Junction

T

Service road

Logistic road restriction elements

Each substage of the route report includes the restrictions that have been found and their coordinates.

<restrictions>
	<restriction height="2.2" x="245771" y="5046066"/>
	<restriction height="2.2" x="246247" y="5046538"/>
</restrictions>

Element

Elem

Description

restriction

 

 

@x

Coord X

@y

Coord Y

@weight

Maximum vehicle weight (if reported).

@axleweight

Maximum vehicle axle weight (if reported).

@height

Maximum vehicle height (if reported).

@width

Maximum vehicle width (if reported).

@length

Maximum vehicle length (if reported).

 

Multipoint massive routing

Calculate the distance and driving time between all the points indicated, with all possible combinations respecting the order. For example, you can include:

  • Several assistance vehicles (with their current location) that can attend to an incident.
  • The location of an incident to attend (for example a damaged car).
  • The destination workshop where to take the car.
  • The return bases to which the vehicles have to finish the service.

In this way, it calculates all the route combinations, respecting the order vehicle assistance -> damaged vehicle -> destination workshop -> base where to return

Likewise, it can take into account the traffic state, as in the case of the generic route calculation.

Request:

Example:

&cmd=route&molist_o=[40.390477919,-3.663617190,|Vehiculo1],[%2040.401144209,-3.692551925|Vehiculo2]&mo_1=[40.387970785,-3.722825150|Incidencia]&molist_2=[40.404172767,-3.698283176|Taller1],[%2040.352579254,-3.716509993|Taller2]&molist_d=[40.334976144,-3.761398808|Base1],[%2040.266864021,-3.752307858|Base2]&mocs=gdd&weight=time

Where:

  • Starting poin / points:
    • mo_o= starting point [Y,X|ID]
    • molist_o= list of starting points [Y,X|ID2],[Y,X|ID2] ...
  • Route waypoint / waypoints:
    • mo_1= waypoint [Y,X|ID]
    • molist_1= list of waypoints [Y,X|ID2],[Y,X|ID2] ...
  • Optional: 2nd waypoint / waypoints (and so on):
    • mo_2= waypoint [Y,X|ID]
    • molist_2= list waypoints [Y,X|ID2],[Y,X|ID2] ...
  • Route destination point / points:
    • mo_d= destination point [Y,X|ID]
    • molist_d= list of destination points [Y,X|ID2],[Y,X|ID2] ...
  • mocs=gdd coordinate system (gdd = geographical - lat, long)
  • weight= Route type
    • time (quickest)
    • distance (shortest)
    • money (quickest avoiding toll roads)
    • realtime (quickest, considering real time traffic data).
  • iweight= provides additional information on route calculation. It allows to indicate different parameters, separated by commas:
    • realtime: Use this parameter to obtain the time of the route, based on the current traffic state.
    • toll: Use this parameter to determine if the route passes through a toll road section. Use only if &report = 0
    • ferry: Use this parameter to obtain if the route passes through a ferry leg. Use only if &report = 0

 

Routing based on departure time:

  • weight= route type:
    • sptime (quickest, based on departure time)
    • spmoney (quickest, based on departure time and avoiding toll roads)
  • departuretime= departure date and time, in ISO 8601 format. UTC time example:  2019-10-16T07:30:12Z  *Mandatory if using weight=sptime/spmoney.

 

Response:

  <cercalia cmd="route" version="1">
   <route dest="Base1" dist="23.9" id="13174411,13206236,13184886,13672512|0.4314835,1.0,0.94561416,0.65883976" orig="Vehiculo1" time="00:44:16" weight="*">
      <stoplist>
         <stop by="false" id="o">
            <mo id="Vehiculo1">
               <coord x="-3.663617189530327" y="40.39047791946798"/>
            </mo>
         </stop>
         <stop by="false" id="1">
            <mo id="Incidencia">
               <coord x="-3.7228251499066443" y="40.387970785252115"/>
            </mo>
         </stop>
         <stop by="false" id="2">
            <mo id="Taller1">
               <coord x="-3.698283176344499" y="40.404172767495176"/>
            </mo>
         </stop>
         <stop by="false" id="d">
            <mo id="Base1">
               <coord x="-3.761398808206737" y="40.33497614352786"/>
            </mo>
         </stop>
      </stoplist>
      <getpoicats/>
      <stages>
         <stage dest="Incidencia" dest_stop_id="0" dist="8.5" orig="Vehiculo1" orig_stop_id="o" time="00:15:23" weight="time"/>
         <stage dest="Taller1" dest_stop_id="0" dist="4.4" orig="Incidencia" orig_stop_id="o" time="00:13:07" weight="time"/>
         <stage dest="Base1" dest_stop_id="0" dist="11.0" orig="Taller1" orig_stop_id="o" time="00:15:46" weight="time"/>
      </stages>
   </route>
   <route dest="Base1" dist="20.3" id="12951122,13206236,13184886,13672512|0.3542734,1.0,0.94561416,0.65883976" orig="Vehiculo2" time="00:39:34" weight="*">
      <stoplist>
         <stop by="false" id="o">
            <mo id="Vehiculo2">
               <coord x="-3.692551924831817" y="40.40114420888145"/>
            </mo>
         </stop>
         <stop by="false" id="1">
            <mo id="Incidencia">
               <coord x="-3.7228251499066443" y="40.387970785252115"/>
            </mo>
         </stop>
         <stop by="false" id="2">
            <mo id="Taller1">
               <coord x="-3.698283176344499" y="40.404172767495176"/>
            </mo>
         </stop>
         <stop by="false" id="d">
            <mo id="Base1">
               <coord x="-3.761398808206737" y="40.33497614352786"/>
            </mo>
         </stop>
      </stoplist>
      <getpoicats/>
      <stages>
         <stage dest="Incidencia" dest_stop_id="0" dist="4.8" orig="Vehiculo2" orig_stop_id="1" time="00:10:41" weight="time"/>
         <stage dest="Taller1" dest_stop_id="0" dist="4.4" orig="Incidencia" orig_stop_id="o" time="00:13:07" weight="time"/>
         <stage dest="Base1" dest_stop_id="0" dist="11.0" orig="Taller1" orig_stop_id="o" time="00:15:46" weight="time"/>
      </stages>
   </route>
   <route dest="Base1" dist="25.8" id="13174411,13206236,13089655,13672512|0.4314835,1.0,0.38120848,0.65883976" orig="Vehiculo1" time="00:44:17" weight="*">
      <stoplist>
         <stop by="false" id="o">
            <mo id="Vehiculo1">
               <coord x="-3.663617189530327" y="40.39047791946798"/>
            </mo>
         </stop>
         <stop by="false" id="1">
            <mo id="Incidencia">
               <coord x="-3.7228251499066443" y="40.387970785252115"/>
            </mo>
         </stop>
         <stop by="false" id="2">
            <mo id="Taller2">
               <coord x="-3.716509993459284" y="40.352579253586725"/>
            </mo>
         </stop>
         <stop by="false" id="d">
            <mo id="Base1">
               <coord x="-3.761398808206737" y="40.33497614352786"/>
            </mo>
         </stop>
      </stoplist>
      <getpoicats/>
      <stages>
         <stage dest="Incidencia" dest_stop_id="0" dist="8.5" orig="Vehiculo1" orig_stop_id="o" time="00:15:23" weight="time"/>
         <stage dest="Taller2" dest_stop_id="1" dist="9.2" orig="Incidencia" orig_stop_id="o" time="00:16:38" weight="time"/>
         <stage dest="Base1" dest_stop_id="0" dist="8.1" orig="Taller2" orig_stop_id="1" time="00:12:16" weight="time"/>
      </stages>
   </route>
   <route dest="Base1" dist="22.2" id="12951122,13206236,13089655,13672512|0.3542734,1.0,0.38120848,0.65883976" orig="Vehiculo2" time="00:39:35" weight="*">
      <stoplist>
         <stop by="false" id="o">
            <mo id="Vehiculo2">
               <coord x="-3.692551924831817" y="40.40114420888145"/>
            </mo>
         </stop>
         <stop by="false" id="1">
            <mo id="Incidencia">
               <coord x="-3.7228251499066443" y="40.387970785252115"/>
            </mo>
         </stop>
         <stop by="false" id="2">
            <mo id="Taller2">
               <coord x="-3.716509993459284" y="40.352579253586725"/>
            </mo>
         </stop>
         <stop by="false" id="d">
            <mo id="Base1">
               <coord x="-3.761398808206737" y="40.33497614352786"/>
            </mo>
         </stop>
      </stoplist>
      <getpoicats/>
      <stages>
         <stage dest="Incidencia" dest_stop_id="0" dist="4.8" orig="Vehiculo2" orig_stop_id="1" time="00:10:41" weight="time"/>
         <stage dest="Taller2" dest_stop_id="1" dist="9.2" orig="Incidencia" orig_stop_id="o" time="00:16:38" weight="time"/>
         <stage dest="Base1" dest_stop_id="0" dist="8.1" orig="Taller2" orig_stop_id="1" time="00:12:16" weight="time"/>
      </stages>
   </route>
   <route dest="Base2" dist="30.6" id="13174411,13206236,13184886,13737176|0.4314835,1.0,0.94561416,0.35529318" orig="Vehiculo1" time="00:45:41" weight="*">
      <stoplist>
         <stop by="false" id="o">
            <mo id="Vehiculo1">
               <coord x="-3.663617189530327" y="40.39047791946798"/>
            </mo>
         </stop>
         <stop by="false" id="1">
            <mo id="Incidencia">
               <coord x="-3.7228251499066443" y="40.387970785252115"/>
            </mo>
         </stop>
         <stop by="false" id="2">
            <mo id="Taller1">
               <coord x="-3.698283176344499" y="40.404172767495176"/>
            </mo>
         </stop>
         <stop by="false" id="d">
            <mo id="Base2">
               <coord x="-3.7523078575314477" y="40.26686402112744"/>
            </mo>
         </stop>
      </stoplist>
      <getpoicats/>
      <stages>
         <stage dest="Incidencia" dest_stop_id="0" dist="8.5" orig="Vehiculo1" orig_stop_id="o" time="00:15:23" weight="time"/>
         <stage dest="Taller1" dest_stop_id="0" dist="4.4" orig="Incidencia" orig_stop_id="o" time="00:13:07" weight="time"/>
         <stage dest="Base2" dest_stop_id="1" dist="17.7" orig="Taller1" orig_stop_id="o" time="00:17:11" weight="time"/>
      </stages>
   </route>
   <route dest="Base2" dist="27.0" id="12951122,13206236,13184886,13737176|0.3542734,1.0,0.94561416,0.35529318" orig="Vehiculo2" time="00:40:59" weight="*">
      <stoplist>
         <stop by="false" id="o">
            <mo id="Vehiculo2">
               <coord x="-3.692551924831817" y="40.40114420888145"/>
            </mo>
         </stop>
         <stop by="false" id="1">
            <mo id="Incidencia">
               <coord x="-3.7228251499066443" y="40.387970785252115"/>
            </mo>
         </stop>
         <stop by="false" id="2">
            <mo id="Taller1">
               <coord x="-3.698283176344499" y="40.404172767495176"/>
            </mo>
         </stop>
         <stop by="false" id="d">
            <mo id="Base2">
               <coord x="-3.7523078575314477" y="40.26686402112744"/>
            </mo>
         </stop>
      </stoplist>
      <getpoicats/>
      <stages>
         <stage dest="Incidencia" dest_stop_id="0" dist="4.8" orig="Vehiculo2" orig_stop_id="1" time="00:10:41" weight="time"/>
         <stage dest="Taller1" dest_stop_id="0" dist="4.4" orig="Incidencia" orig_stop_id="o" time="00:13:07" weight="time"/>
         <stage dest="Base2" dest_stop_id="1" dist="17.7" orig="Taller1" orig_stop_id="o" time="00:17:11" weight="time"/>
      </stages>
   </route>
   <route dest="Base2" dist="34.1" id="13174411,13206236,13089655,13737176|0.4314835,1.0,0.38120848,0.35529318" orig="Vehiculo1" time="00:48:25" weight="*">
      <stoplist>
         <stop by="false" id="o">
            <mo id="Vehiculo1">
               <coord x="-3.663617189530327" y="40.39047791946798"/>
            </mo>
         </stop>
         <stop by="false" id="1">
            <mo id="Incidencia">
               <coord x="-3.7228251499066443" y="40.387970785252115"/>
            </mo>
         </stop>
         <stop by="false" id="2">
            <mo id="Taller2">
               <coord x="-3.716509993459284" y="40.352579253586725"/>
            </mo>
         </stop>
         <stop by="false" id="d">
            <mo id="Base2">
               <coord x="-3.7523078575314477" y="40.26686402112744"/>
            </mo>
         </stop>
      </stoplist>
      <getpoicats/>
      <stages>
         <stage dest="Incidencia" dest_stop_id="0" dist="8.5" orig="Vehiculo1" orig_stop_id="o" time="00:15:23" weight="time"/>
         <stage dest="Taller2" dest_stop_id="1" dist="9.2" orig="Incidencia" orig_stop_id="o" time="00:16:38" weight="time"/>
         <stage dest="Base2" dest_stop_id="1" dist="16.4" orig="Taller2" orig_stop_id="1" time="00:16:24" weight="time"/>
      </stages>
   </route>
   <route dest="Base2" dist="30.4" id="12951122,13206236,13089655,13737176|0.3542734,1.0,0.38120848,0.35529318" orig="Vehiculo2" time="00:43:43" weight="*">
      <stoplist>
         <stop by="false" id="o">
            <mo id="Vehiculo2">
               <coord x="-3.692551924831817" y="40.40114420888145"/>
            </mo>
         </stop>
         <stop by="false" id="1">
            <mo id="Incidencia">
               <coord x="-3.7228251499066443" y="40.387970785252115"/>
            </mo>
         </stop>
         <stop by="false" id="2">
            <mo id="Taller2">
               <coord x="-3.716509993459284" y="40.352579253586725"/>
            </mo>
         </stop>
         <stop by="false" id="d">
            <mo id="Base2">
               <coord x="-3.7523078575314477" y="40.26686402112744"/>
            </mo>
         </stop>
      </stoplist>
      <getpoicats/>
      <stages>
         <stage dest="Incidencia" dest_stop_id="0" dist="4.8" orig="Vehiculo2" orig_stop_id="1" time="00:10:41" weight="time"/>
         <stage dest="Taller2" dest_stop_id="1" dist="9.2" orig="Incidencia" orig_stop_id="o" time="00:16:38" weight="time"/>
         <stage dest="Base2" dest_stop_id="1" dist="16.4" orig="Taller2" orig_stop_id="1" time="00:16:24" weight="time"/>
      </stages>
   </route>
   <server>lb.cercalia.com</server>
</cercalia>

Where:

  • id= route ID
  • dist= route distance, in km
  • time= route time (HH:MM:SS)
  • realtime= route time, including real time traffic (HH:MM:SS), if iweight=realtime
  • hasferries= informs if the route includes some ferry (only if request includes &iweight=ferry and &report=0)
  • hastolls= informs if the route includes some toll roads (only if request includes &iweight=toll and &report=0)

Demo