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