The RouteCloud API is a collection of operations that can be used to solve problems in planning and routing.
The following planning and routing overview is based on a business with three customers, one depot, one delivery vehicle, and one driver.
||A series of stops representing the work or tasks that a driver has to complete, usually within a day.|
||A work item or task that a driver has to complete as part of a route. It might be associated with a geospatial location, represented by a marker.|
||A geospatial location of interest. For example, a business headquarter or customer location.|
||A type of stop that represents visiting a customer location to perform a task or work item.|
||A type of stop that represents visiting a business location to perform a task or work item. It usually involves picking up or dropping off goods.|
Calling the API
The RouteCloud API is a JSON HTTP API. The following topics describe how to interact with the API. We highly recommend that new users read through all the topics prior to making any API calls, to ensure correct and optimal operations.
Authentication is required for most RouteCloud API calls. Ideally, you specify an auth token
X-Telogis-Session-Id header on every request. See Authentication for more details.
Requests and responses are in JSON format.
Content-Type request header must be set to
Request Data Format
To increase performance and reliability on large requests,
the request body can be compressed in
Content-Encoding request header must be set to
gzip in this case.
Must be set to
Can be set to
gzip to enable gzip compression on requests and responses.
Each account has a maximum limit on the number of concurrent running tasks.
If this is exceeded, an HTTP
429 is returned.
The limit applies to the total number of concurrent running tasks across all subusers of the account.
Make sure you use features such as cancel_on_disconnect
to remain within account limits.
The build, sequence, insert, and evaluate normally return
a problem_response, which contains only a subset of the full problem data.
When the return_request field is set to
true, the full problem is returned instead.
Integrations can sometimes be made simpler when the entire input is pipelined through to the output.
When one entity references another; for example, on the route.jobs field, the subobject (for example, job) can be specified inline as part of the parent object. Alternatively, the string ID of the referenced entity can be specified. The API expects to find the referenced entity on its top-level collection (for example, problem.jobs). See referencing for more.
In the RouteCloud API all potentially long-running tasks have their responses deferred, but they can be long-polled to
return results immediately. For example, calling
/v1/build returns a new task ID, and a client can long-poll for
the result immediately by calling
See Retrieving API Results.
The RouteCloud API is stateless when sandboxes are not used. That means, no data is stored. All data must be passed in via the request. This makes it easier to integrate the RouteCloud API with another source of record.
When the RouteCloud API generates an error, it returns a meaningful HTTP status code and a structured error response. See errors for more details.
All RouteCloud API endpoints use the base URL https://routecloud.telogis.com/. RouteCloud supports the following operations:
POST- Build new routes.
POST- Determine job assignment restrictions before building new routes.
POST- Sequence a set of existing routes.
POST- Evaluate a set of existing routes to determine arrival times, costs, distances, breaks, and violations.
POST- Retrieve the best (top N potential) insertion position for a stop on a route.
POST- Insert jobs into an existing route without altering the sequence of existing jobs.
POST- Calculate a geographic centroid for the given drivers, considering the provided jobs and all constraints.
POST- Generate N zones that contain an even amount of either: Markers, Stops, Time on Site or a Capacity Metric with a set variance.
POST- Geocode addresses to latitudes and longitudes.
POST- Reverse geocode locations to addresses.
Asynchronous Task Endpoints
GET- Check the status of long-running tasks.
GET- Retrieve the status of a task.
GET- Retrieve the result of a task.
POST- Cancel a running task.
GET- Retrieve the list of existing sandboxes.
POST- Create a new sandbox.
GET- Retrieve the contents of an existing sandbox.
POST- Update the contents of an existing sandbox.
DELETE- Delete an existing sandbox.
GET- Retrieve the sequence of revisions in a sandbox.
POST- Add a revision to a sandbox.
POST- Update the expiry interval of a sandbox.
POST- Convert a problem file to canonical form.
POST- Get the route cards for the routes or problem.
GET- Get the version number of the RouteCloud API.
The RouteCloud API works with standard JSON API debug tools such as Postman.