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.

How Does it Work?

Using our RESTful APIs, you can plan a trip from origin to destination with as many stops as necessary in between.

Trip Planning

During trip planning, you can add dwell times, HOS breaks and use historical traffic to generate a realistic ETA for each stop. You can also set a Vehicle Routing Profile, which assures that the route and drive times are appropriate for the vehicle being driven. The trip is saved under a unique Trip ID and information about the trip can be accessed and updated at any time using this ID.

Trip Execution

During execution, you can feed GPS locations of the vehicle to the Trip Management service and it will monitor the progress of the trip. Any deviations from the originally planned route, scheduled arrival times or HOS breaks are recorded and shared via notifications. As a result, end customers get a trip with predicted arrival times rather than “estimated” arrival times and all stakeholders can stay on top of the progress of a trip during execution.

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 Angular 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 Trimble Maps.
$.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 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 Trimble Maps.

  /**
   * 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 Trimble Maps
   */
  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

Below are the basic steps for using our trip management service. Please see the Workflow page for more details.

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 trip automatically recalculates to update ETAs and rest stops, if necessary. The user may edit the trip multiple times. After modifying a trip, call Get Trip to view the updated trip.

3. 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 their stops as Arrived/Completed. Only trips marked as InProgress will receive event notifications.

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

5. 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.

6. 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.

7. 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

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

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.