nextmv Docs

Cloud API

Cloud API

The Cloud API serves as a quick-and-easy demonstration of Hop's solving capabilities for optimizing routes for a fleet of vehicles.

Step 1: Acquire API Key

In order to run the model and see results, an API key must first be acquired. Go to the Nextmv Cloud Console and click "Click to reveal" 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.

Step 2: Make a request

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

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

Available endpoints

MethodEndpointDescription
POSTrunCreate a new run
GET{run id}/statusGet a run status
GET{run id}/resultGet a run result

Headers

HeaderDescription
Accept: application/jsonRequest a JSON response
Authorization: Bearer {your API key}Authorize the request
Content-Type: application/json(for run) Request body is in JSON

Request Body

Below is an example request body to send to the run endpoint.

{
"defaults":{
"vehicles": {
"start": {
"lon": -96.659222,
"lat": 33.122746
},
"end": {
"lon": -96.659222,
"lat": 33.122746
},
"shift_start": "2021-10-17T09:00:00-06:00",
"speed": 10
},
"stops": {
"stop_duration": 120
}
},
"vehicles": [
{
"id": "vehicle-1",
"capacity": 305
},
{
"id": "vehicle-2",
"capacity": 205
}
],
"stops": [
{
"id": "location-1",
"position": {
"lon": -96.71038245222624,
"lat": 33.20580830033956
},
"quantity": -27
},
{
"id": "location-2",
"position": {
"lon": -96.65613745932127,
"lat": 33.2259142720506
},
"quantity": -30
},
{
"id": "location-3",
"position": {
"lon": -96.63759803136642,
"lat": 33.21528740544529
},
"quantity": -36
},
{
"id": "location-4",
"position": {
"lon": -96.61356543957307,
"lat": 33.20379744909628
},
"quantity": -19
},
{
"id": "location-5",
"position": {
"lon":-96.64137458150537,
"lat": 33.178801586789376
},
"quantity": -31
},
{
"id": "location-6",
"position": {
"lon": -96.83157538607735,
"lat": 33.02896457334468
},
"quantity": -15
},
{
"id": "location-7",
"position": {
"lon": -96.82951544963792,
"lat": 33.05170100884261
},
"quantity": -31
},
{
"id": "location-8",
"position": {
"lon":-96.86007117348946,
"lat": 33.08133590083287
},
"quantity": -52
},
{
"id": "location-9",
"position": {
"lon": -96.87346076034575,
"lat": 33.092841906114394
},
"quantity": -48
},
{
"id": "location-10",
"position": {
"lon": -96.79586982112724,
"lat": 33.10492159118987
},
"quantity": -40
}
]
}

Response

The API server should return something like the following.

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

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, but you can check on the status of your run via the {run id}/status endpoint. A successful run will result in the following response, once completed.

{ "status": "succeeded" }

Step 3: 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 following JSON.

{
"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
}
}

At this point, you can begin tinkering with the input of your run request to see how your result changes. If you have any questions or need help, please contact us at support@nextmv.io.