This how-to guide assumes you already completed the steps described in the 5-minute getting started experience. To test that the Nextmv CLI is correctly configured, you can optionally run the following command on your terminal. It will get some files that are necessary to work with the Nextmv Platform. You can see the expected output as well.
The Nextmv routing app provides you with API endpoints to run a model, check the status of your run, and get run results, and a user interface to configure the app. Follow the steps below to use the app.
The Nextmv routing app is built on top of the router
and provides a configurable interface for solving vehicle routing problems. It requires a set of stops that must be serviced by a fleet of vehicles as input following a specified schema. It returns routes for each vehicle, a list of unassigned stops (if any), and search output statistics.
In this guide, you will learn how to use the Nextmv routing app with a simple example where routes are created to visit seven landmarks in Kyoto using two vehicles.
Let's see how.
Note, you will need your Nextmv API key and the Nextmv CLI to use the Nextmv routing app. Log in to Nextmv and navigate to your account page to find your key. Keep it safe, as it alone provides unfettered access to the cloud API.
Input
Save the following information in an input.json
file.
Run profile
To proceed with running the example, you will need to create a run profile via the Nextmv console. After you log in, navigate to the run profile configuration page to create or edit a run profile. Be sure to note your run profile id as you will need this below. Run profiles can also be created via the Nextmv routing app API.
Output
To execute the example, use the Nextmv CLI to specify the path to an input.json
file, write results to a file, and use a specific run profile.
The output is saved to the folder output
. The solution state should look similar to this:
You can see that six stops were assigned to one vehicle and just a single stop which is farthest from the others was assigned to the other vehicle.
Additional options can be added to the input.json
to extend this basic example. See the routing app features how-to guide for more information on how to add additional Nextmv routing app features to your input file.
Using the API directly
The Nextmv routing app is made up of a collection of API endpoints that you can query directly. This section will instruct you on doing so. However, we recommend that you use the Nextmv CLI to interact with the routing app directly, when possible.
API Key
Your Nextmv API key can be copied from under your account profile after logging in to the Nextmv Cloud console.
Endpoints
Note, all requests must be authenticated with Bearer Authentication. Make sure your request has a header containing your Nextmv API key, as such:
- Key:
Authorization
- Value:
Bearer <YOUR-API-KEY>
No API specified.
No API specified.
No API specified.
Polling
The routing app API should be used through polling.
Send a request to the /v0/run
endpoint with a JSON
body that follows the input schema, e.g.: the previous input.json
. The API server should return a runID
similar to the following:
This means that a Nextmv solver 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. Wait for approximately the duration
set in the run options
. Depending on the problem, the solver may finish sooner than the alloted time.
Poll the /v0/run/{run_id}/status
endpoint with the runID
obtained from the previous request.
- If the status of the run is
succeeded
, you may request the result using the/v0/run/{run_id}/result
endpoint. - If the status is
requested
orstarted
, it means that the solver is still running and you should wait to request the result. We recommend you set a maximum number of retries for the polling. Sleep for a short time, then poll the endpoint until there are no retries left or the status issucceeded
. Instead of retries, you can also use a timeout. - If the status is
failed
ortimed_out
, it means that you will not be able to request the result.
Request the result from the /v0/run/{run_id}/result
endpoint using the runID
obtained from the first request. The response is a JSON
payload that follows the output schema, e.g.: the previous output.json
. Modify the input of your run request to see how your result changes.
Code snippets
These code snippets demonstrate how to use the API through polling in select languages. They assume the input.json file is present in the same directory as the script.
To start, get your API key and set the following environment variable:
Run one of the following scripts:
You should obtain the same output as before.