Welcome to Knowledge Base!

KB at your finger tips

This is one stop global knowledge base where you can learn about all the products, solutions and support features.

Salesforce Developers

Units of Measure

For units of measure, the Salesforce Optimization API uses the metric system. When in doubt, assume a standard metric unit. If you encounter uncertainty, please submit a support request, and we update the offending API to provide clarity.

  • Time: seconds
  • Distance: meters
  • Volume: arbitrary, but must be consistent across the entire request
  • Weight: arbitrary, but must be consistent across the entire request

The Salesforce Optimization API expects geographic coordinates in units of decimal degrees using the WGS84 coordinate system. The polyline format is used to encode a sequence of locations in a single string. Polylines appear in some endpoint responses, for example, the routes object in the response from the routing endpoint.

Time is expressed in two ways:

  1. ISO 8601: this is the most self-consistent, time zone independent form of time measurement and is useful for quickly parsing and processing times across many time zones. The ISO 8601 format enables users to take advantage of modern programming libraries and modules which are time zone aware.
  2. Unix time: Unix time represents a point in time as the number of seconds that have elapsed since 00:00:00 UTC on Thursday, 1 January 1970, minus leap seconds. Parameters expressed in Unix time are signed 64-bit integers. Why may you ask? So that the times are valid until 15:30:08 UTC on Sunday, 4 December 292,277,026,596... giving you plenty of time to worry about code refactoring and technical debt.

Time zone names and offsets are specified using the Internet Assigned Numbers Authority. This adoption ensures users can leverage modern DateTime parsing libraries such as CCTZ in C++ or datetime in Python or Date in Javascript.

Note that if a user submits a time as a string expression which includes a time zone offset, the time zone offset is converting to Unix time. If no time zone is given, then the API attempts to associate that particular time with a location and then the time zone of that location is used when converting to Unix time. The API maintains a private timezone service to facilitate this functionality.

To highlight the reasoning for the time format choices, consider a timestamp in seconds. Using the handy Python pytz module, one can process time in a generalized, robust manner using only a few lines of code:

Salesforce Developers


Minor updates and bug fixes are implemented continuously and preserve existing API behavior. Significant updates that alter API behavior are released to a new URL leveraging versioning, for example https://sfoptapi.com/{apiVersion}/routing where {apiVersion} might be v1 , v2 , v3 and so on. The CHANGELOG tracks all changes made to the APIs. Changes that are considered backward compatible:

  • Changing a parameter from required to optional
  • Adding enumeration values
  • Adding new functionality

API versions are embedded in the URL to ensure that releases do not create a breaking change. For example, in the release from v1 to v2 , clients on v1 are not affected because the URL to v1 is still valid and consistent with the v1 specifications.

When a legacy API version reaches its end-of-life and will no longer be accessible, all users are notified 90 days in-advance to ensure that applications update to a newer API version. Also, requests to retired API versions receive a default error response with a 30x status code and message pointing to the latest version of that API.

Our documentation is built using the OpenAPI Specification, and the full spec for each API is available at the top of the API's docs page via the "Download" button. We encourage others to continue support of the OpenAPI Initiative to ensure harmonization among the universe of API's.

Read article
Salesforce Developers

Postman Collections

Run any of the examples provided in this section using our maintained Postman Collections. A "Public PROD Environment" ships with the Postman Collection. You need to edit this environment and replace the {{apiKey}} variable with your API key. If you do not have one yet, contact us to get one.

Read article
Salesforce Developers


The Distance Matrix service takes a set of locations and provides estimates for the travel times and distances between each pair accounting for predicted traffic based on years of historical data.

The Routing Optimization service is powered by an optimization engine designed to handle a huge variety of problems and aims to help you find your optimal business solution by giving you control over how your problem is solved.

Read article
Salesforce Developers

Distance Matrix

The Distance Matrix service takes a set of locations and provides estimates for the travel times and distances between each pair accounting for predicted traffic based on years of historical data. The travel times are returned for multiple "traffic windows," periods during which predicted traffic remains roughly constant. The Distance Matrix service has been engineered using patented methods for hyper-efficiency in handling unprecedentedly large requests: up to 7,500 locations at once. The current performance is orders of magnitude faster than competing services, and vastly less expensive.

As a reminder, a distance matrix describes the distances between all sets of points in a collection. For example, if we have locations A, B, and C, then the figure below represents the distance matrix:

Distance Matrix

Take note that the diagonals of the distance matrix have value zero (0) since the distance from a location to itself is zero. Also, notice that the matrix is symmetric; that is, the distance from A-to-B is the same as B-to-A and so on, which is not always accurate in the real world road network due to one-way streets, variations in traffic patterns, and other subtleties that our backend services take into consideration.

When supplied latitudes and longitudes for locations of interest, our backend services calculate travel times and distances between each location pair using predicted traffic estimated for multiple traffic windows: periods during which predicted traffic remains roughly constant. We provide a visual example of traffic windows in the figure below using simulated data.

Traffic Windows

In this exaggerated cartoon, notice that there are distinct periods during which the travel time is constant (colored, horizontal lines) that separate into different travel time windows (vertical blue lines). Our backend services take the same approach, and in each distance matrix response, there are eight different time windows all with their travel times.

Given a set of n locations (A, B, C in the example above), the Distance Matrix service returns a square n x n matrix with each entry in the matrix representing the time and distance of traveling between a pair of locations in different time windows. The Distance Matrix service allows users to filter further these results based on the specifics of the use case. For example, as illustrated below, users can designate that some locations are only sources and others are only destinations so that the result contains only information about traveling from a source location to a destination location, thus saving calculation time and calls.

Distance Matrix Source-Destination

The Distance Matrix service supports a variety of other options that allow users to filter results further. By default, the Distance Matrix service assumes the vehicle type to be a car . However, the Distance Matrix service allows users to specify types such as bicycle , pedestrian , and truck . Trucks are a unique vehicle type that takes additional parameters, such as weight and height. Details provided below.

The response from the Distance Matrix service is simple to understand, yet complex to describe syntactically. Other companies that provide a distance matrix service do not offer the traffic time window and filtering options. Hence our more extensive Distance Matrix service has a denser response format, which is detailed below. Represented graphically, a source-destination pair in our distance matrix is an array of distance and travel times for each traffic window, as shown below.

Distance Matrix Source-Destination

Read article
Salesforce Developers

Basic Distance Matrix

The simplest example of using the distance matrix service is to apply no filters ( sources and destionations are unused) and request a single traffic window ( "weekend": true ). This simple format will result in an all-versus-all distance matrix for a single traffic window. An example of input and output is provided below.

Expand to view request sample
Expand to view response sample
Read article

Still Thinking?
Give us a try!

We embrace agility in everything we do.
Our onboarding process is both simple and meaningful.
We can't wait to welcome you on AiDOOS!