Signup
×

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.

Categories
All
CRM-Salesforce
Salesforce Developers

Introduction

Welcome to the documentation for the Salesforce Optimization API. What is the Salesforce Optimization API? Our API (a grouping of functionalities) that is composed of endpoints which perform a single, specific task like repairing a vehicle route or scheduling a resource to perform service.

We have opened access to the API so you too can create amazing applications and products using our services. Unlike our suite of Salesforce products, the API is Salesforce agnostic and thus has utility in a wide variety of applications, for example:

  • OEM — create or improve functionality for an existing application.
  • SOLUTION IMPLEMENTATION — partners or firms that are building custom applications for a customer.
  • INDEPENDENT SOFTWARE VENDORS — build and sell your software.
  • INDIVIDUAL DEVELOPERS — people or teams are building proofs of concept or testing new ideas.

The API usage pattern is based on industry best practices and is the same experience to which you've become accustomed. As an example, consider routing optimization:

  1. Your code crafts a routing problem out of your data.
  2. Your code submits a routing problem request to the routing endpoint of our Optimization API.
  3. Our systems solve the routing problem and respond (typically within seconds) with a routing solution.
  4. Your code parses the response and does something amazing with it!
Read article
Salesforce Developers

Authentication

Accessing endpoints on the Salesforce Optimization API requires a valid API key associated with your account, and all clients must obtain authentication credentials before having access to Salesforce API's. Your API key is provided via the request header using the x-api-key parameter. Throughout the documentation, we assume this header is provided. Below is an example of a typical header JSON object:

API keys are used to track requests associated with an account for quota, billing, and analytics purposes. Please review the Terms of Service agreed to during sign-up, or contact support, if you have additional questions.

Code snippets like those below are provided for all endpoints and methods. If you find any are missing, not working, or incomplete, please submit a support request, and we'll update the docs immediately.

To provide context, consider the below examples where you would need to replace REPLACE_KEY_VALUE with your actual API key. A simple request in a shell might look something like this:

Alternatively, if you're more comfortable reading JavaScript:

Here is a final example in Python:

When you receive credentials, please take steps to secure them properly. Exposing credentials can result in unauthorized access, which can lead to billable events. To help keep your credentials secure, follow these best practices:

  • Do not embed credentials in code
  • Store credentials separately from the code base, for example using Docker Secrets or git-crypt
  • Set up account restrictions
  • Delete unused credentials
  • Regenerate credentials periodically
  • Automate detection of exposed keys using native functionality in platforms like GitHub or Gitlab, or add the functionality with tools like git-secret or git-secrets

The API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec that allows cross-domain communication from the browser. All responses have a wildcard same-origin which makes them wholly public and accessible to everyone, including any code on any site.

Read article
Salesforce Developers

Behavior

Methods

Any tool or programming language that has HTTP communication abilities, for example cURL or Postman or Python requests, can interact with our API by merely requesting the correct endpoint, for example /routing. All requests need to be made using the HTTPS protocol to ensure encryption and an extra layer of security. Additionally, most of our endpoints expect requests to be made in the standard JSON format. Our API's support the standard HTTP methods, e.g., GET, POST, and so on.

Encoding

All API's require the contents of request objects be encoded using UTF-8. To represent special characters in strings, use the %FF hexadecimal representation. For example, in German, the word "airports" is "Flughäfen" and converts to "Flugh%C3%A4fen." If you are unsure of the conversion, there are numerous online encoder/decoder tools and automated encoding/decoding in language specific libraries.

For example (in Python 3.0+):

For a full-fledged URI request (in Python 3.0+):

Success

All success responses include standard HTTP statuses consistent with IETF standards. The API returns a JSON object when a request is successful. The JSON object contents are specific to the resource and described in the detailed documentation for each resource. The API backend handles requests in one of two ways:

  • Synchronously: For smaller jobs (in terms of the number of unique locations), the request processes "quickly" (shorter than a connection timeout) and the response JSON body includes a result.
  • Asynchronously: For larger jobs, the request does not process quickly, and the response JSON body includes a jobid needed to poll the endpoint and retrieve a url to download the solution. Solutions are available at this URL for 24 hours from the timestamp included in the response header.

Failure

All failure responses include standard HTTP statuses consistent with IETF standards. In the event an error occurs, the response is a JSON with a top-level error code, error message, and other identifying information. All API errors return a JSON response with a human-readable comment describing the issue. Depending on the error returned, there may be additional objects to describe the error further. Note that if a client does not receive a response for a request within 29 seconds, the API returns an HTTP status code of 504 indicating a Gateway Timeout Error.

Read article
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:

Read article
Salesforce Developers

Versioning

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

Services

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
Salesforce Developers

Large Requests

If you provide more than 200 locations in a distance matrix requesst, the Optimization API will process the request asynchronously due to the computation time being longer than a connection timeout. As a result, the service will respond with a jobid and URI that can be used to retrieve the input using the GET method on the same endpoint. An example is shown below.

Read article

Interested?
Signup now!

arrow-image
Login / Signup as

Post taks and get it done by experts


Find great opportunities and enjoy reading