RouteCloud supports a number of 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- 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.
GET- Get the version number of the RouteCloud API.
All RouteCloud API endpoints use the base URL https://routecloud.telogis.com/.
Authentication is required for most RouteCloud API calls.
Ideally an auth token would be specified via the
X-Telogis-Session-Id header on every request.
Requests and responses should be specified in JSON format.
Content-Type request header must be set to
In order to increase performance and reliability on large requests,
the request body may be compressed in
Content-Encoding request header must be set to
gzip in this case.
Every request should have the id and name field set. The id should be a unique request ID generated by the client. The name should be a human-readable string describing the data; for example, it could be the name of the territory, branch or region that the request relates to. This helps Verizon Connect Support find relevant requests if any issues are raised.
Asynchronous vs Synchronous
In the RouteCloud API all potentially long-running tasks are handled asynchronously,
but they can be long-polled in a synchronous manner.
For example, calling
/v1/build returns a new task ID,
and a client can long-poll for the result in a synchronous manner by calling
See Asynchronous vs Synchronous.
Stateless vs Stateful
The RouteCloud API is stateless when sandboxes are not being 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.
Full vs Partial Responses
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.
See Full vs Partial Responses.
Referencing vs Inlining
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, or 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 vs Inlining.
Each account has a maximum limit on the number of concurrent running tasks.
If this is exceeded, an HTTP
429 is returned.
The limit is applies to the total number of concurrent running tasks across all subusers of the account.
Users should make sure they use features such as cancel_on_disconnect
to remain within account limits.
When the RouteCloud API generates an error, it returns a meaningful HTTP status code and a structured error response. See Errors.
The RouteCloud API works with standard JSON API debug tools such as Postman.