Introduction

The Trip Management service is your one-stop shop for generating truly compliant routes. Built upon our industry standard PC*MILER Web Services, Trip Management generates optimal routes for your delivery, inserting any fuel stops or necessary driver rest stops along the route. With these additional stops, you can more confidently determine your load’s true ETA.

This API guide will tell you how to interact with Trip Management and get you well on your way.

Resource URL

https://tripmanagement.alk.com/api/

Service Authentication

Every web service request needs to be authenticated. The process is simple. You just need to add the API key (enterprise app) or Single Sign-On token (consumer app) to the HTTP Authorization header. Examples for jQuery and Angular2 are listed below:

jQuery Example: Use HTTP POST to create a trip

var uri = "https://tripmanagement.alk.com/api/trip"; // The web service endpoint.
var request = {}; // Request data that will be sent to the service. Details for each API are listed in the help pages.
var apiKey = ""; // The API key obtained from ALK.
$.ajax({
  url: uri,
  type: "POST", // or "GET", "DELETE"
  data: request,
  contentType: "application/json; charset=utf-8",
  dataType: "json",
  beforeSend: function(xhr) {
    xhr.setRequestHeader("Authorization", apiKey);
  },
  success: function(resp) {
    // Your code goes here
  },
  error: function(resp) {
    // Your code goes here
  }
});

Angular 2 TypeScript Example: Use HTTP GET to retrieve a trip by trip id.

import {Injectable} from '@angular/core';
import {Http, Headers} from '@angular/http';
import 'rxjs/add/operator/map';

@Injectable()
export /**
 * RouteService
 */
  class RouteService {
  trueEtaUri: string = 'https://tripmanagement.alk.com/api/trip/'; // The web service endpoint.
  trueEtaApiKey: string = ''; // The API key obtained from ALK.

  /**
   * Constructor
   */
  constructor(private http: Http) {
    // Additional code for the class construction.
  }

  /**
   * Public Method: Gets trip by id.
   *
   * Parameters:
   * tripId - {number} trip id
   */
  getTrueEtaTrip(tripId: number) {
    return this.makeRequest(this.trueEtaUri + tripId);
  }

  /**
   * Private Method: Add API key to the HTTP authentication header.
   *
   * Parameters:
   * headers - {Headers} - HTTP header collection
   * authToken - {string} - API key from ALK
   */
  private createAuthorizationHeader(headers: Headers, authToken: string) {
    headers.append('Authorization', authToken);
  }

  /**
   * Private Method: Sends request to the service.
   *
   * Parameters:
   * path - {string} web service request URI
   */
  private makeRequest(path: string) {
    let headers = new Headers();
    this.createAuthorizationHeader(headers, this.trueEtaApiKey);
    return this.http.get(path, { headers: headers })
      .map((res) => res.json());
  }
}

Trip Management Workflow

The basic steps for using our trip management service

  1. Plan a trip
    POST /trip
    An optimal route is generated between all given stops, including ETAs. Rest stops are inserted, where needed, if HOS information is supplied. A tripID is created that will be used for all other actions needed to edit, update or track the trip.

  2. Modify a trip
    PUT /trip/modify
    Allows the user to add/remove/change stops in a trip. Once a trip is edited, the user must then recalculate the trip (Step 3) to get updated ETAs and new rest stops. The user may edit the trip multiple times and recalculate when they are satisfied with their changes.

  3. Get updated ETA/insert new rest stops
    PUT /trip/recalculate
    Recalculates the trip. It uses the same algorithm as planning a trip, but doesn’t require the user to supply the whole trip again—only updated HOS information and the truck’s current location.

  4. Mark a trip as in progress
    POST /trip/tripStatus
    Marks the trip as InProgress when the user Accepts the trip or when the user marks one of his or her stops as Arrived/Completed. Only trips marked as InProgress will receive event notifications.

  5. Update current position
    POST /trip/gpsposition
    Records a GPS position tied to the trip.

  6. Arrive or depart a stop
    POST /trip/stopStatus
    Changes the stop’s status. Altering the stop’s status will allow anyone viewing the trip to see the truck’s progress.

  7. Mark a trip as complete
    POST /trip/tripStatus
    Changes the trip’s status. Once a trip is complete, we will stop monitoring the trip for ETA or other notifications.

  8. Get a trip
    GET /trip/{tripId}
    Returns the current state of the trip. If any stops are marked as complete, the stop status and arrival times are shown.

Use Case No. 1

You plan and dispatch a trip. The truck runs the trip and you review it.

Example Flow

ActionAPI
Create a trip with two stopsPlan Trip
Review trip before dispatchGet Trip
Mark trip in progress (dispatch)Update Trip Status
Update current locationUpdate Positions
Arrive stop 1Update StopStatus
Depart stop 1Update StopStatus
Update current locationUpdate Positions
Arrive stop 2Update StopStatus
Mark trip as doneUpdate Trip Status
View completed tripGet Trip

Use Case No. 2

You plan a trip realize you need to change the stops. You edit the trip, dispatch it, and the driver executes it.

Example Flow

ActionAPI
Create a trip with two stopsPlan Trip
Review trip before dispatchGet Trip
Insert a third stopModify Trip
Recalculate rest stops/ETARecalculate Trip
Review trip before dispatchGet Trip
Mark trip in progress (dispatch)Update Trip Status
Update current locationUpdate Positions
Arrive stop 1Update StopStatus
Depart stop 1Update StopStatus
Update current locationUpdate Positions
Arrive stop 2Update StopStatus
Depart stop 2Update StopStatus
Update current locationUpdate Positions
Arrive stop 3Update StopStatus
Mark trip as doneUpdate Trip Status
View completed tripGet Trip

Trip Management in Action

Watch Trimble’s Rishi Mehra demonstrate the capabilities of our Trip Management API at the FreightWaves Transparency 19 conference, held in May 2019.

Last updated November 5, 2019.