Quick Start Guide for JavaScript Directions SDK

Prerequisites

The following are prerequisites for this guide.

About API Key

The API key is used to track API requests of the project for usage and billing. API key often acts as a unique identifier and a secret token for authentication. The API key can be requested by filling details and submitting the form at https://locationstudio.zendesk.com/hc/en-us/requests/new?ticket_form_id=360001758513.

Quick Start Steps

Use the following steps to start using the JavaScript Directions SDK.

Getting the SDK

To obtain the entire JavaScript SDK package:

  1. Go to https://git.location.studio/location.studio/JSSDK/tree/master.

  2. Register, or sign-in to your existing Comtech Location Studio® Git account.

  3. If you created a new account, access it by clicking the Confirm your account link, in the email sent to the registered email ID.

  4. On the home page, click on the download icon to obtain the JavaScript SDK zip package. As an alternative, you can clone the repository to your local system using the following command.

git clone https://git.location.studio/location.studio/JSSDK.git

After you have downloaded and extracted the zip package or cloned the repository, follow the steps described in the next sections to begin using the Directions API.

Getting Started

The following section shows how to load the API code libraries.

Loading the API Code Libraries

The first step for the JavaScript Directions SDK application is to load the necessary code libraries or modules. You will load the modules by adding the following <script> elements.

A directions application can be created by including all dependencies on the main page, referred to as sample-app.html in this guide. It includes gssdirections.min.js to interact with back-end service for obtaining the direction response details as shown in the following code snippet.

<script type="text/javascript" src="/gssdirections.min.js"></script>

Initializing the Directions Request

After loading the API code libraries, follow Initializing the Directions Request through Parsing the Directions Response Details to display a Directions response object.

Use the following steps for initializing the Directions Request.

  1. Construct a request object. The JavaScript code sample shared below, creates a request object. It contains the co-ordinates latitude 33.667488, longitude -117.698669 (Alton Pkwy, Irvine, CA) for the origin and latitude 33.668659, longitude -117.68676 (Snowberry St, Lake Forest, CA) for the destination.

var origin = new gssdirections.GSSLatLng(33.667488, -117.698669);
var destination = new gssdirections.GSSLatLng(33.668659, -117.68676);
var directionsRequest = new gssdirections.GSSDirectionsRequest(origin, destination);
directionsRequest.setOptimize('fastest');
directionsRequest.setVehicle('car');
directionsRequest.setAvoids('hov');
directionsRequest.setTrafficOption('none');

  1. The application in this scenario gathers the origin and destination locations in latitude/longitude coordinates, passed to the GSSDirectionsRequest constructor. The routing parameters described in the following table are optional.

Note
 Default values are used if the parameters are not set by the application.
Table 1. Optional Parameters

Optional Parameters

Datatype

Description

Default Value

optimize

String

The optimization method for the route. The available options are: fastest, shortest, easiest

fastest

vehicle

String

The type of vehicle that will be traveling the route. The available options are: car, truck, bicycle, pedestrian

car

avoid

String

Comma separated list of things to avoid. The available options are: hov, toll, highway, uturn, unpaved, ferry, none

hov

traffic_level

String

The available traffic options are none, avoid, and alert

alert

To know more about optional parameters, go to https://developer.location.studio/site/docs/geoservice/route/index.gsp

Invoking the Directions Service

To communicate with the back-end service to get the directions, use the method in this code snippet.

var directionsService = new gssdirections.GSSDirectionsService('PUT_YOUR_API_KEY_HERE');
directionsService.getRoute(directionsRequest, function(gssDirectionsResponse){
var str = convertResponseToString(gssDirectionsResponse);
$('#json_data').html(str);
}, function(error){
console.log("Error: " + error.status + " --> " + error.statusText);
});

Parsing the Directions Response Details

The following steps and code snippets show parsing of Directions Response and describe the parsing details.

  1. Directions Response contains one or multiple routes. To retrieve routes from Directions Response, use the following method.

var routes = gssDirectionsResponse.getRoutes();

  1. To retrieve route segments from the first route, of all the routes retrieved in the preceding step, use the following code snippet.

var routeSegments = routes[0].getRouteSegments();

  1. The route also retrieves the distance to cover the route and the estimated travel time. This code snippet shows how to retrieve these details.

var distance = route[0].getDistance();
var travelTime = route[0].getTravelTime();

  1. The route segment contains route maneuvers that describe the action needed to leave one street and enter another street to progress along the route. The following code describes how to get route maneuvers from the route segment.

Var routeManeuvers = routeSegments[0].getRouteManeuvers();

  1. The route maneuver consists of distance, average speed on the street, heading, current road name, turn road name, driving side, country side, and turn command. The route maneuver also contains co-ordinates that are required to draw polyline. This code snippet shows how to get these details.

var distance = routeManeuvers[0].getDistance();
var heading = routeManeuvers[0].getHeading();
var speed = routeManeuvers[0].getSpeed();
var currentRoadName = routeManeuvers[0].getCurrentRoadName();
var turnRoadName = routeManeuvers[0].getTurnRoadName();
var drivingSide = routeManeuvers[0].getDrivingSide();
var countryCode = routeManeuvers[0].getCountryCode();
var turnCommand = routeManeuvers[0].getTurnCommand();
var polyline = routeManeuvers[0].getPolyline();

The following image displays the response object on clicking Get Route for the sample inputs given in Initializing the Directions Request, after the Directions Response gets generated and parsed as described in Invoking the Directions Service and Parsing the Directions Response Details.

DirResp
Figure 1. Directions Response