Calculate a Route

Use the following URL template to get a route by specifying a series of locations. A location is a specified geographical location defined by longitude and latitude that is used for navigational purposes. The route includes information such as route instructions, travel duration, travel distance or transit information. You can also request a set of route points. Request type must be POST for both XML and JSON format.

http://trackservice.trackroad.com/rest/route/key

You must login to get a key.

For more details about request and response parameters see RouteSpecification and RouteResult.

ABSTRACT SAMPLE

XML

To receive response in XML format you must specify content type text/xml or application/xml. For example:

...
httpWReq.Method = "POST";
httpWReq.ContentType = "text/xml; charset=utf-8";
httpWReq.ContentLength = data.Length;
...

XML request

The following request uses two locations with Latitude/Longitude.

<RouteSpecification>
  <Locations>
    <Location>
      <Name>Loc_1</Name>
      <LatLong>
        <Latitude>38.931594</Latitude>
        <Longitude>-77.27602</Longitude>
      </LatLong>
    </Location>
    <Location>
      <Name>Loc_2</Name>
      <LatLong>
        <Latitude>38.938467</Latitude>
        <Longitude>-77.164874</Longitude>
      </LatLong>
    </Location>
  </Locations>
  <RouteOptions>
    <Culture>en-US</Culture>
    <DistanceUnit>Mile</DistanceUnit>
    <RouteOptimize>MinimizeTime</RouteOptimize>
  </RouteOptions>
</RouteSpecification>

XML response

<RouteResult xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Errors />
  <Status>Success</Status>
  <Route>
    <Distance>8.1965073968026712</Distance>
    <Time>899</Time>
    <RouteLegs>
      <RouteLeg>
        <Distance>8.1965073968026712</Distance>
        <Time>899</Time>
        <Itinerary>
          <Items>
            <RouteItineraryItem>
              <Distance>0.14229400302234946</Distance>
              <LatLong>
                <Latitude>38.931657671928406</Latitude>
                <Longitude>-77.275997400283813</Longitude>
              </LatLong>
              <Text>Depart Thistle Ridge Ln toward Meadowlark Rd</Text>
              <Time>24</Time>
              <Warnings />
              <Hints />
            </RouteItineraryItem>
            <RouteItineraryItem>
              <Distance>0.37903642726477371</Distance>
              <LatLong>
                <Latitude>38.931759595870972</Latitude>
                <Longitude>-77.278288006782532</Longitude>
              </LatLong>
              <Text>Turn left onto Brookside Ln</Text>
              <Time>86</Time>
              <Warnings />
              <Hints />
            </RouteItineraryItem>
            ...
            <RouteItineraryItem>
              <Distance>0</Distance>
              <LatLong>
                <Latitude>38.938524127006531</Latitude>
                <Longitude>-77.164726629853249</Longitude>
              </LatLong>
              <Text>Arrive at Loc_2 on the right</Text>
              <Time>0</Time>
              <Warnings />
              <Hints>
                <RouteHint>
                  <Type>PreviousIntersection</Type>
                </RouteHint>
              </Hints>
            </RouteItineraryItem>
          </Items>
        </Itinerary>
      </RouteLeg>
    </RouteLegs>
    <Points>
      <LatLong>
        <Latitude>38.931657</Latitude>
        <Longitude>-77.275997</Longitude>
      </LatLong>
      <LatLong>
        <Latitude>38.931941</Latitude>
        <Longitude>-77.276270000000011</Longitude>
      </LatLong>
      <LatLong>
        <Latitude>38.932151000000005</Latitude>
        <Longitude>-77.276877000000013</Longitude>
      </LatLong>
    ...
      <LatLong>
        <Latitude>38.938524000000008</Latitude>
        <Longitude>-77.164725999999973</Longitude>
      </LatLong>
    </Points>
  </Route>
</RouteResult>

XML request

The following request uses two locations with Latitude/Longitude. In this example we defined map size and route color. If map size is defined you will receive map images encoded to base64string. You can also specify map center, zoom level (1-18) and hide stops on a map. For more details see RouteSpecification.

<RouteSpecification>
  <Locations>
    <Location>
      <Name>Loc_1</Name>
      <LatLong>
        <Latitude>38.931594</Latitude>
        <Longitude>-77.27602</Longitude>
      </LatLong>
    </Location>
    <Location>
      <Name>Loc_2</Name>
      <LatLong>
        <Latitude>38.938467</Latitude>
        <Longitude>-77.164874</Longitude>
      </LatLong>
    </Location>
  </Locations>
  <RouteOptions>
    <Culture>en-US</Culture>
    <DistanceUnit>Mile</DistanceUnit>
    <RouteOptimize>MinimizeTime</RouteOptimize>
    <MapSize>
      <Width>400</Width>
      <Height>200</Height>
    </MapSize>
    <RouteColor>
      <A>179</A>
      <R>0</R>
      <G>169</G>
      <B>235</B>
    </RouteColor>
  </RouteOptions>
</RouteSpecification>

XML response

<RouteResult xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Errors />
  <Status>Success</Status>
  <Route>
    <Distance>8.1965073968026712</Distance>
    <Time>899</Time>
    <RouteLegs>
      <RouteLeg>
        <Distance>8.1965073968026712</Distance>
        <Time>899</Time>
        <Itinerary>
          <Items>
            <RouteItineraryItem>
              <Distance>0.14229400302234946</Distance>
              <LatLong>
                <Latitude>38.931657671928406</Latitude>
                <Longitude>-77.275997400283813</Longitude>
              </LatLong>
              <Text>Depart Thistle Ridge Ln toward Meadowlark Rd</Text>
              <Time>24</Time>
              <Warnings />
              <Hints />
            </RouteItineraryItem>
            <RouteItineraryItem>
              <Distance>0.37903642726477371</Distance>
              <LatLong>
                <Latitude>38.931759595870972</Latitude>
                <Longitude>-77.278288006782532</Longitude>
              </LatLong>
              <Text>Turn left onto Brookside Ln</Text>
              <Time>86</Time>
              <Warnings />
              <Hints />
            </RouteItineraryItem>
          ...
            <RouteItineraryItem>
              <Distance>0</Distance>
              <LatLong>
                <Latitude>38.938524127006531</Latitude>
                <Longitude>-77.164726629853249</Longitude>
              </LatLong>
              <Text>Arrive at Loc_2 on the right</Text>
              <Time>0</Time>
              <Warnings />
              <Hints>
                <RouteHint>
                  <Type>PreviousIntersection</Type>
                </RouteHint>
              </Hints>
            </RouteItineraryItem>
          </Items>
        </Itinerary>
        <Map>iVBORw0KGgoAAAANSUhEUgAAAZAAAADICAMA...</Map>
      </RouteLeg>
    </RouteLegs>
    <Points>
      <LatLong>
        <Latitude>38.931657</Latitude>
        <Longitude>-77.275997</Longitude>
      </LatLong>
      <LatLong>
        <Latitude>38.931941</Latitude>
        <Longitude>-77.276270000000011</Longitude>
      </LatLong>
      <LatLong>
        <Latitude>38.932151000000005</Latitude>
        <Longitude>-77.276877000000013</Longitude>
      </LatLong>
      ...
      <LatLong>
        <Latitude>38.938524000000008</Latitude>
        <Longitude>-77.164725999999973</Longitude>
      </LatLong>
    </Points>
    <Map>iVBORw0KGgoAAAANSUhEUgAAAZAAAADICAMAAADxy0fQAAAAAXNSR0IArs...</Map>
  </Route>
</RouteResult>

JSON

To receive response in JSON format you must specify content type text/json or application/json. For example:

...
httpWReq.Method = "POST";
httpWReq.ContentType = "text/json; charset=utf-8";
httpWReq.ContentLength = data.Length;
...

JSON request

The following request uses two locations with latitude and longitude.

{
   "Locations":[
      {
         "MatchCode":0,
         "Name":"Loc_1",
         "Delivery":null,
         "Vehicle":null,
         "Description":null,
         "Phone":null,
         "LatLong":{
            "Latitude":38.931594,
            "Longitude":-77.27602
         },
         "Address":null,
         "Priority":0,
         "Wait":0,
         "Volume":0,
         "Weight":0,
         "Skids":0,
         "TimeConstraintArrival":"0001-01-01T00:00:00Z",
         "TimeConstraintDeparture":"0001-01-01T00:00:00Z",
         "TimeConstraintArrival2":"0001-01-01T00:00:00Z",
         "TimeConstraintDeparture2":"0001-01-01T00:00:00Z",
         "LocationType":0,
         "CanArriveEarly":true,
         "Distance":0,
         "Time":0
      },
      {
         "MatchCode":0,
         "Name":"Loc_2",
         "Delivery":null,
         "Vehicle":null,
         "Description":null,
         "Phone":null,
         "LatLong":{
            "Latitude":38.938467,
            "Longitude":-77.164874
         },
         "Address":null,
         "Priority":0,
         "Wait":0,
         "Volume":0,
         "Weight":0,
         "Skids":0,
         "TimeConstraintArrival":"0001-01-01T00:00:00Z",
         "TimeConstraintDeparture":"0001-01-01T00:00:00Z",
         "TimeConstraintArrival2":"0001-01-01T00:00:00Z",
         "TimeConstraintDeparture2":"0001-01-01T00:00:00Z",
         "LocationType":0,
         "CanArriveEarly":true,
         "Distance":0,
         "Time":0
      }
   ],
   "RouteOptions":{
      "DistanceUnit":0,
      "RouteOptimize":0,
      "Culture":"en-US",
      "MapSize":null,
      "RouteColor":null
   }
}

JSON Response

{
    "Route":{
        "Distance":8.1965073968026712,
        "Time":899,
        "RouteLegs":[
           {
               "Distance":8.1965073968026712,
               "Time":899,
               "Itinerary":{
                   "Items":[
                      {
                          "Distance":0.14229400302234946,
                          "LatLong":{
                              "Latitude":38.931657671928406,
                              "Longitude":-77.275997400283813
                          },
                          "Text":"Depart Thistle Ridge Ln toward Meadowlark Rd",
                          "Time":24,
                          "Warnings":[

                          ],
                          "Hints":[

                          ]
                      },
                      {
                          "Distance":0.37903642726477371,
                          "LatLong":{
                              "Latitude":38.931759595870972,
                              "Longitude":-77.278288006782532
                          },
                          "Text":"Turn left onto Brookside Ln",
                          "Time":86,
                          "Warnings":[

                          ],
                          "Hints":[

                          ]
                      },
                     ...
                      {
                          "Distance":0.0,
                          "LatLong":{
                              "Latitude":38.938524127006531,
                              "Longitude":-77.164726629853249
                          },
                          "Text":"Arrive at Loc_2 on the right",
                          "Time":0,
                          "Warnings":[

                          ],
                          "Hints":[
                             {
                                 "Type":0,
                                 "Text":null
                             }
                          ]
                      }
                   ]
               },
               "Map":null
           }
        ],
        "Points":[
           {
               "Latitude":38.931657,
               "Longitude":-77.275997
           },
           {
               "Latitude":38.931941,
               "Longitude":-77.276270000000011
           },
           {
               "Latitude":38.932151000000005,
               "Longitude":-77.276877000000013
           },
          ...
           {
               "Latitude":38.938524000000008,
               "Longitude":-77.164725999999973
           }
        ],
        "Map":null
    },
   "Errors":[

   ],
   "Status":1
}

See Also

RouteSpecification
RouteResult