Get started

Sign up for an account on Nextmv Cloud to start using Nextmv Cloud for optimizing routes for a fleet of vehicles.

Once you sign up, you will be able to access Nextmv Cloud API and Console (graphical user interface) to run a model, check the status of your run, and explore the results of a run.

Nextmv Cloud API

Nextmv Cloud API provides you with endpoints to run a model, check the status of your run (GET), and get the results of a run. Follow the steps below to use Nextmv Cloud API.

Get an API key

After you have logged in to the Nextmv Cloud Console, go to the API page and click "Click to reveal API Key" under the header "Your API Key". The key will automatically be copied to your clipboard. Keep it safe, as it alone provides unfettered access to the cloud API.

Make a request

To make a request use the base URL, combined with one of the endpoint paths and headers specified below.

https://api.cloud.nextmv.io/v0/{endpoint}

Table: Available endpoints

Method

Endpoint

Description

POST

run

Create a new run

GET

{run id}/status

Get a run status

GET

{run id}/result

Get a run result

Add headers

Add the following headers to your request:

Header

Description

Accept: application/json

Request a JSON response

Authorization: Bearer {your API key}

Authorize the request

Content-Type: application/json

(for run) Request body is in JSON

Add request body

The request body must be written in JSON and follow the cloud input schema.

Get a response

Check on the status of your run via the {run id}/status endpoint. The API server should return something like the following.

{ "runID": "{your run ID}" }

This means that an instance of Hop has been spun up to solve the model with the given input. The time it takes to finish execution varies by the size of the input and solver options, but you can. A successful run will result in the following response, once completed.

{ "status": "succeeded" }

Retrieve a result

At this point, the result of your run is ready to be retrieved via the {run id}/result endpoint. It will look something like the sample output JSON below.

Modify the input of your run request to see how your result changes. If you have any questions or need help, please contact us at [email protected].

{
"hop": {
"version": "v0.7.2"
},
"options": {
"diagram": {
"expansion": {
"limit": 1
},
"restrictor": {
"type": "github.com/nextmv-io/code/hop/solve/diagram/restrict.value"
},
"width": 10
},
"limits": {
"duration": "3s"
},
"search": {
"buffer": 100,
"queuer": {
"type": "github.com/nextmv-io/code/hop/solve/queue.depth"
},
"searcher": {
"type": "github.com/nextmv-io/code/hop/solve/search.local"
}
},
"sense": "min"
},
"state": {
"vehicles": [
{
"id": "vehicle-1",
"value": 3682,
"travel_distance": 30824.842301505018,
"travel_time": 3682.4842301505028,
"route": [
{
"id": "vehicle-1-start",
"lon": -96.659222,
"lat": 33.122746,
"distance": 0,
"eta": "2021-10-17T09:00:00-06:00"
},
{
"id": "location-1",
"lon": -96.71038245222624,
"lat": 33.20580830033956,
"distance": 10391.50414831852,
"eta": "2021-10-17T09:17:19-06:00"
},
{
"id": "location-2",
"lon": -96.65613745932127,
"lat": 33.2259142720506,
"distance": 15910.82924812028,
"eta": "2021-10-17T09:28:31-06:00"
},
{
"id": "location-3",
"lon": -96.63759803136642,
"lat": 33.21528740544529,
"distance": 18001.39525293215,
"eta": "2021-10-17T09:34:00-06:00"
},
{
"id": "location-4",
"lon": -96.61356543957307,
"lat": 33.20379744909628,
"distance": 20576.530424227247,
"eta": "2021-10-17T09:40:17-06:00"
},
{
"id": "location-5",
"lon": -96.64137458150537,
"lat": 33.178801586789376,
"distance": 24374.092826725027,
"eta": "2021-10-17T09:48:37-06:00"
},
{
"id": "vehicle-1-end",
"lon": -96.659222,
"lat": 33.122746,
"distance": 30824.842301505018,
"eta": "2021-10-17T10:01:22-06:00"
}
]
},
{
"id": "vehicle-2",
"value": 5406,
"travel_distance": 48056.77689197839,
"travel_time": 5405.677689197839,
"route": [
{
"id": "vehicle-2-start",
"lon": -96.659222,
"lat": 33.122746,
"distance": 0,
"eta": "2021-10-17T09:00:00-06:00"
},
{
"id": "location-6",
"lon": -96.83157538607735,
"lat": 33.02896457334468,
"distance": 19147.828578821216,
"eta": "2021-10-17T09:31:54-06:00"
},
{
"id": "location-7",
"lon": -96.82951544963792,
"lat": 33.05170100884261,
"distance": 21683.286018576735,
"eta": "2021-10-17T09:38:08-06:00"
},
{
"id": "location-8",
"lon": -96.86007117348946,
"lat": 33.08133590083287,
"distance": 26038.292451410223,
"eta": "2021-10-17T09:47:23-06:00"
},
{
"id": "location-9",
"lon": -96.87346076034575,
"lat": 33.092841906114394,
"distance": 27825.176738548107,
"eta": "2021-10-17T09:52:22-06:00"
},
{
"id": "location-10",
"lon": -96.79586982112724,
"lat": 33.10492159118987,
"distance": 35176.62119033169,
"eta": "2021-10-17T10:06:37-06:00"
},
{
"id": "vehicle-2-end",
"lon": -96.659222,
"lat": 33.122746,
"distance": 48056.77689197839,
"eta": "2021-10-17T10:30:05-06:00"
}
]
}
],
"unassigned": [],
"value_summary": {
"value": 9088,
"total_travel_distance": 78881.6191934834,
"total_travel_time": 9088.161919348342,
"total_unassigned_penalty": 0
}
},
"statistics": {
"bounds": {
"lower": -9223372036854776000,
"upper": 9088
},
"search": {
"generated": 10,
"filtered": 0,
"expanded": 10,
"reduced": 0,
"restricted": 10,
"deferred": 10,
"explored": 0,
"solutions": 1
},
"time": {
"elapsed": "628.115µs",
"start": "2021-05-03T12:45:10.901164345Z"
},
"value": 9088
}
}