Route optimization API for developers: A tour of the Nextmv Cloud API

Nextmv Cloud is as simple as JSON in / JSON out. Follow this short tutorial to get started with the API and optimize routes for any use case. Just POST your file and GET your results.

Route optimization with Nextmv Cloud

Nextmv Cloud has a full roster of vehicle routing features to make optimizing your routing use case a breeze – from delivery to distribution and sourcing.

Many folks get started by testing out the pre-loaded, use-case specific sample input files in the cloud console itself. Running files in the console is ideal for analyzing the routes on the map and digging into charts that break down the solution value.


If you’re ready to start using your own files or would rather test using the command line (or like to use tools like Postman), this is the tutorial for you. 

First, sign up or log into Nextmv Cloud. It’s free to get started! 

Get your API key

Once you’re into the console, navigate to the API page on the left hand side.

Reveal your API key. Once you’ve clicked on the button, your API key will automatically be copied to your clipboard.

Feel free to follow the guided experience on the page or run it on your own machine using the directions below. 

Post the file

We opted to demonstrate using cURL, but the following components can also be used with API platforms like Postman. Let’s get started!

In this POST request, you’ll notice the following:

  • The Nextmv Cloud API endpoint (Use https://api.cloud.nextmv.io/v0/run)
  • Your API key (You copied this in the previous step)
  • JSON with vehicles, stops, and constraints (Feel free to copy exactly what’s below or create your own file following the input schema)

 Paste the following into your terminal:



curl -X 'POST' \
  'https://api.cloud.nextmv.io/v0/run' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR-API-KEY \
  -H 'Content-Type: application/json' \
  -d '{
  "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
    }
  ]
}'



You should get a result that looks like the following. You’ll need your run-id in just a moment so make sure to copy it.  



{ "runID": "YOUR_RUN_ID" }


Get the run status

Ok, now let’s see how the run went. 

Paste the following into your terminal. Make sure to use your unique run-id.




curl -X 'GET' \
  'https://api.cloud.nextmv.io/v0/run/YOUR_RUN_ID/status' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

You’ll see something like this returned as a status:



{
  "status": "succeeded"
}

If you saw “succeeded” then it’s time to move on to the next step!


Seeing an error code? Not to worry. Hop into the documentation for more information on what’s going on.

Get your result

And now for the exciting part! Let’s see your optimized route. 

Paste the following into your terminal, remembering to use your run-id and API key:



curl -X 'GET' \
  'https://api.cloud.nextmv.io/v0/run/YOUR_RUN_ID' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'


You’ll see something like the JSON below returned.


The results outline the optimized routes for each vehicle as well as a few key details about your run and returned solution.

Congrats on a successful run!


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

Learn more

Looking for a bit more detail? Head to the docs for more routing examples and quickstart code snippets.


Have a question? Please reach out to us! We always enjoy chatting about optimization.

Video by:
No items found.