Vehicle Routing Problem Service

The MapAnything Routing Engine (MARE) Routing API provides a very powerful and flexible way of solving your largest and most complex routing and scheduling problems. MARE allows you to specify an arbitrary planning period that can be a single day, a week, or even a year. The planning period is made up of one or more shifts which are periods of time during which a vehicle can be active. Each vehicle has an array of shifts with optional start/end location and a known start/end time. Additionally, the shifts can contain breaks and soft breaks which limit the times during which a vehicle can service orders. One can assign many properties to each service request or order, and these orders can be serviced with a heterogeneous fleet where different vehicles can have attributes to impose skill matching type restrictions. Along with normal service requests with a known duration and time window, MARE also allows you to solve routing problems that involve complex pickup and dropoff operations and complex periodic visit requirements.

Generally speaking, vehicle routing problems (VRPs) can be very difficult problems to solve computationally and typically are NP-Hard problems. This doesn’t mean that they are impossible to solve, just that finding the truly, mathematically provable optimal solution can take a very long time with running times that can increase dramatically as the problem size grows.

Given the uncertainty in travel times and the difficulty in even defining what optimal means for many rich real-world routing problems, MARE takes the approach of running a complex optimization algorithm for a “reasonable” amount of time before returning a solution. To achieve this, we divide problems into synchronous and asynchronous calls depending on the size and difficulty of the problem.

Synchronous calls are for smaller requests (less than 50 locations) and are processed immediately. Asynchronous calls are for a larger set of locations, and a job ID is returned once a request is received and validated. The user can then poll the system for job status and retrieve the results when the job completes. The payload formats for asynchronous and synchronous calls are the same. However, an asynchronous call will return a URI to retrieve the job from our cloud storage. Once it completes, the response will be purged after 24 hours.

REST API

Communication with the back end is accomplished with REST API calls to either the synchronous or asynchronous endpoint. Each request must be accompanied with a valid API key, and the associated account will be charged a number of credits depending on the size and/or complexity of the request. The well-known curl library provies a simple utility to send and process requests.

Synchronous Example:  The example below shows how to communicate with the MARE synchronous endpoint for a small problem using curl. It assumes that you have a request in the local file input.json and sends the response directly to response.json.

curl -H "Content-Type: application/json" -H'x-api-key: INSERT_YOUR_KEY' -d@input.json https://public-api.mapanything.io/mare/routing/sync > response.json

Asynchronous Example:  The example below shows how to send and process an asynchronous job. The local file big_input.json contains a large routing job and sends the initial response directly to big_response.json.

curl -H "Content-Type: application/json" -H'x-api-key: INSERT_YOUR_KEY' -d@big_input.json https://public-api.mapanything.io/mare/routing/async > big_response.json

Upon sending a valid asynchronous request, you will receive a response similar to the below

{"JobId":"mare-us-east-1-routing-11-1549046543.628501-857","JobMessage":"Check status by : GET /mare/routing/?jobid=mare-us-east-1-routing-11-1549146543.628501-857","JobStatus":"Accepted"}

You can then poll the status of your job as follows

curl -H "Content-Type: application/json" -H'x-api-key: INSERT_YOUR_KEY' https://public-api.mapanything.io/mare/routing/?jobid=mare-us-east-1-routing-11-1549146543.628501-857

If the job is running, you will receive a simple message to that effect:

{"status":"Running"}

If the job is complete, then you will receive a link from which you can download the response (the link remains valid for 24 hours):

{"url":"https://prod-us-east-1-mare-output-data.s3.amazonaws.com/2019-02-01/output-mare-us-east-1-routing-11-1549046543.628501-857.json?WSAccessKeyId=...", "status":"Completed"}