Route

Route Service gives optimized route based on criterias which you can find below.

A Route service request must look like this:

http://www.locationbox.com.tr/locationbox/services?Key=key&Cmd=Rota&Typ=output_format &Criteria=criteria&Cons=constraints
&Dir=direction&Map=map&Width=width&Height=height&Points=points

Request Parameters

Key: LocationBox user key. (Register for user key)
Cmd: LocationBox service name. (Rota)
Typ: Response format. (XML or JSON)
Criteria (optional): Calculate the shortest (SHORT) or fastest (FAST) route. (Default: FAST)
Cons (optional): Specify the route constraints. (Toll roads, ferry etc.)

Route Constraints
FERIBOT -- Avoid ferry.
OTOYOL -- Avoid toll roads.
KAMYON -- Avoid no truck roads.

Dir (optional): Set as 1 if directions required. If not, set as 0. (Default: 0)
Map (optional): Set as 1 if map image is required. If not, set as 0. (Default:0)
Width (optional): Width of map image in pixels. (Default: 600)
Height (optional): Height of map image in pixels. (default: 400)
Encode (optional): Set as 1 if encode the data. If not, set as 0 (default: 0)
Geometry (optional): You MUST have Route Geometry package to use this parameter. Set as 1 to get route geometry. If not, set as 0.(default:0)
Ordered (optional): Set as 1 without TSP, set as 0 with TSP (default: 0)
TspType (optional): TSP Types (default: 1)

Tsp Types
1 -- Fixes the start and end Points.
2 -- Fixes the start point.
3 -- Fixes the end point.

Points: Additional points to the route to pass through. The points are specified in latitude/longitude format and separated by commas.
Route calculation requires at least two points (start point and end point).

Response Parameters

XML Response

Route service response returns in XML format when the Typ parameter is set as "XML".

Below is an example for a Route service request which is expected to return a response in XML format .

http://www.locationbox.com.tr/locationbox/services?Key=key&Cmd=Rota&Typ=XML&Criteria=FAST
&Cons=KAMYON,FERIBOT&Dir=1&Map=1&Width=600&Height=400
&Points=41.0075/29.0174,40.9971/29.0366,40.9815/29.0967,40.9602/29.0765

The response will be as following:

<response>
 <transactionid>LBS_212</transactionid>
 <status>0</status>
 <errno />
 <errdesc />
 <rota>
  <pathid>723962</pathid>
  <distance>14957</distance>
  <duration>21</duration>
  <durationwithtmc>31</durationwithtmc>   <mapurl>http://www.locationbox.com.tr/locationbox/images/map_id.png</mapurl>
  <directions>
   <direction>
    <id>0</id>
    <explanation>Başlangıç</explanation>
    <distance>0</distance>
    <duration>0</duration>
   </direction>
   <direction>
    <id>1084969701</id>
    <explanation>Çeşme-i Kebir Sokak'a dön 153 m. git</explanation>
    <distance>153</distance>
    <duration>153</duration>
   </direction>
   <direction>
    <id>1085289161</id>
    <explanation>Sağa doğru Selimiye Kışla Caddesi'ne dön 166 m. git</explanation>
    <distance>166</distance>
    <duration>166</duration>
   </direction>

   ...

   <direction>
    <id>0</id>
    <explanation>Bitiş</explanation>
    <distance>0</distance>
    <duration>0</duration>
   </direction>
  </directions>
 </rota>
</response>


JSON Response

Route service response returns in JSON format when the Typ parameter is set as "JSON".

Below is an example for a Route service request which is expected to return a response in JSON format .

http://www.locationbox.com.tr/locationbox/services?Key=key&Cmd=Rota&Typ=JSON&Criteria=FAST
&Cons=KAMYON,FERIBOT&Dir=1&Map=1&Width=600&Height=400
&Points=41.0075/29.0174,40.9971/29.0366,40.9815/29.0967,40.9602/29.0765

The response will be as following:

{ transactionid: LBS_215, status: 0, rota: { pathid: 723999, distance: 14957, duration: 21, durationwithtmc: 31, mapurl: 'http://www.locationbox.com.tr/locationbox/images/map_id.png', directions: [ { id: 0, direction: 'Başlangıç ', distance: 0, duration: 0, durationwithtmc: 31 } { id: 1084969701, direction: 'Çeşme-i Kebir Sokak'a dön 153 m. git', distance: 153, duration: 0 } { id: 1085289161, direction: 'Sağa doğru Selimiye Kışla Caddesi'ne dön 166 m. git', distance: 166, duration: 0 } { id: 1084972452, direction: 'Sağa doğru Selimiye Hamamı Sokak'a dön 30 m. git', distance: 30, duration: 0 }
...
{ id: 0, direction: 'Bitiş ', distance: 0, duration: 0 } ] } }

Generated map image for the route will be available in the url http://www.locationbox.com.tr/locationbox/images/map_id.png
and will look like the following:

transactionid: The id of response given by LocationBox Service. Every response can be tracked using transactionid when necessary.
status: Response format. (XML or JSON)

Status Codes
0 -- Success
1 -- Fail

errno: Error code
errdesc: Error definition

Error Codes
10001 Error processing your request. Please try again soon.
Cmd parameter is misspelled/not found.
10011 Error processing your request. Please check the Cmd parameter.
Cmd is not specified.
10012 Error processing your request. Please check the Key parameter.
Key is not specified.
10013 Error processing your request. Please check the Key parameter.
Key is invalid.
20012 No data found.

Rota (Route)

pathid: Id of the route. Every calculated route is stored with a path id.
distance: Total distance measurement of the route in meters.
duration: Total cost of time of the route in minutes.
durationwithtmc: Total cost of time of the route in minutes including delay caused by the road traffic.

Route Map

mapurl: The generated route map image is available through an url under the mapurl tag.("map" parameter should be set as "1" to generate a route map image.)

Directions

Each <direction> element contains description of a single direction set between two points. id: Direction id.
explanation: Explanation of direction.
distance: Length of path that the direction describes.
duration: Duration of path that the direction describes.

Notes

The calculated route can also be shown on map. See the JavaScript API for more information.
See the demo on displaying a route on the map using LocationBox JavaScript API.

Route records are deleting periodically.