Overview

The RouteCloud API is a collection of operations that can be used to solve problems in planning and routing.

Routing Terminology

The following planning and routing overview is based on a business with three customers, one depot, one delivery vehicle, and one driver. Routing Terminology

Term Description
route A series of stops representing the work or tasks that a driver has to complete, usually within a day.
stop 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.
marker A geospatial location of interest. For example, a business headquarter or customer location.
job A type of stop that represents visiting a customer location to perform a task or work item.
depot 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.

Authenticating to the API

Authentication is required for most RouteCloud API calls. Ideally, you specify an auth token via the X-Telogis-Session-Id header on every request. See Authentication for more details.

Formatting API requests and handling API responses

Data Format

Requests and responses are in JSON format. The Content-Type request header must be set to application/json.

Request Data Format

The data format for a request is a problem consisting of some endpoint-specific fields and some optional fields shared by all endpoints. See here for more details.

Note

We highly recommend that you specify the id and the name. These fields are optional, but they allow Verizon Connect support to find any relevant requests if issues are raised.

id should be a unique request ID generated by the client and name should be a human readable string describing the data.

Compression

To increase performance and reliability on large requests, the request body can be compressed in gzip format. Content-Encoding request header must be set to gzip in this case.

Request Headers

Content-Type

Must be set to application/json

Content-Encoding

Can be set to gzip to enable gzip compression on requests and responses.

API usage limits

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.

Choosing the amount of data returned by the API

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

Referenced entities vs inline entities

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.

Retrieving results from the API

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 /v1/tasks/{task_id}/result?wait=1. See Retrieving API Results.

Stateless vs stateful requests

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.

Sandboxes are a way of storing problem files on the RouteCloud API server. Sandboxes provide a way to visualize the data because you can view and edit them in the UI. See sandboxes.

Handling Errors

When the RouteCloud API generates an error, it returns a meaningful HTTP status code and a structured error response. See errors for more details.

Endpoints

All RouteCloud API endpoints use the base URL https://routecloud.telogis.com/. RouteCloud supports the following operations:

Optimization Endpoints

  • /v1/build POST - Build new routes.
  • /v1/assignment_restrictions POST - Determine job assignment restrictions before building new routes.
  • /v1/sequence POST - Sequence a set of existing routes.
  • /v1/evaluate POST - Evaluate a set of existing routes to determine arrival times, costs, distances, breaks, and violations.
  • /v1/recommend POST - Retrieve the best (top N potential) insertion position for a stop on a route.
  • /v1/insert POST - Insert jobs into an existing route without altering the sequence of existing jobs.
  • /v1/centroids POST - Calculate a geographic centroid for the given drivers, considering the provided jobs and all constraints.
  • /v1/zones POST - Generate N zones that contain an even amount of either: Markers, Stops, Time on Site or a Capacity Metric with a set variance.

Geocoding Endpoints

Asynchronous Task Endpoints

Sandbox Endpoints

Other Endpoints

  • /canonicalize POST - Convert a problem file to canonical form.
  • /v1/route_cards POST - Get the route cards for the routes or problem.
  • /version GET - Get the version number of the RouteCloud API.

API Development

Tools

The RouteCloud API works with standard JSON API debug tools such as Postman.

UI

The RouteCloud UI, Verizon Connect Scenarios, can open RouteCloud API problem files directly, and therefore can be used as a debug tool.

See Also