Back to Documentation Overview

Using our Fleet Planner API

Fleet Planner is a stateless API that finds the most optimal routes for a fleet of vehicles given a set of tasks. Unlike the Dispatch API, Fleet Planner doesn't retain state and will only re-optimize an existing set of tasks if the same set of tasks are modified and re-sent to Fleet Planner. This makes Fleet Planner optimal for cases when you have a pre-existing list of pickups/dropoffs and vehicles that need to be scheduled ahead of time. That being said, a potential stateful integration of Fleet Planner could involve maintaining states on one's own and continually calling Fleet Planner whenever said state changes.

In this guide, we'll be running through a quick example use case of Fleet Planner where we feed the API a set of tasks/available vehicles and receive a plan. All that's required to retrieve the plan is one call to the Fleet Planner API.

Prerequisite: Get the API Key

To run this example, you will need a rideOS API Key. You can sign up for one here and view it on your profile page.

Once you have the API Key, you can set the environment variable with export RIDEOS_API_KEY="YOUR_API_KEY" and use RIDEOS_API_KEY in the cURL commands given below.

Step 1: Get a recommendation plan for a fleet of vehicles and tasks.

All we need to do here is send the Fleet Planner API information about the fleet of vehicles and tasks to complete. One thing to note is that you can also schedule a specific time window for the pickup/dropoff tasks if they need to be completed at a certain time. You can find a full list of parameters for vehicles/tasks in Fleet Planner in our API documentation here.

curl --request POST 'https://api.production.rideos.ai/fleet/v2/GetPlan' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: $RIDEOS_API_KEY' \
--data '{
    "optimizeFor": "RIDE_HAIL",
    "vehicles": {
        "vehicle-0": {
            "resourceCapacity": 4,
            "vehicleId": "vehicle-0",
            "position": {
                "latitude": 37.78861129958993,
                "longitude": -122.42121679763515
            }
        }
    },
    "tasks": {
        "task-0": {
            "resourcesRequired": 1,
            "pickupStep": {
                "position": {
                    "latitude": 37.788710054546385,
                    "longitude": -122.42034205962396
                }
            },
            "dropoffStep": {
                "position": {
                    "latitude": 37.79878236715864,
                    "longitude": -122.4222166856741
                }
            }
        },
        "task-1": {
            "resourcesRequired": 1,
            "pickupStep": {
                "position": {
                    "latitude": 37.78883349777378,
                    "longitude": -122.41859090561832
                }
            },
            "dropoffStep": {
                "position": {
                    "latitude": 37.79900453502346,
                    "longitude": -122.42068402876973
                }
            }
        }
    }
}
'

Step 2: Get a recommendation plan for each vehicle/task

And that's really all there is to it! The resulting plan for our Fleet Planner call gets returned in the response.

{
    "recommendations": [
        {
            "vehicleId": "vehicle-0",
            "planRecommendation": {
                "assignedSteps": [
                    {
                        "taskId": "task-0",
                        "stepType": "PICKUP",
                        "remainingTime": 14.296854873316038,
                        "pickup": {}
                    },
                    {
                        "taskId": "task-1",
                        "stepType": "PICKUP",
                        "remainingTime": 41.571288138543096,
                        "pickup": {}
                    },
                    {
                        "taskId": "task-1",
                        "stepType": "DROPOFF",
                        "remainingTime": 246.31030744938874,
                        "dropoff": {}
                    },
                    {
                        "taskId": "task-0",
                        "stepType": "DROPOFF",
                        "remainingTime": 267.3589796045157,
                        "dropoff": {}
                    }
                ]
            }
        }
    ],
    "unresolvedTasks": []
}

Thanks for reading! If you need to manage a fleet that supports on-demand requests check out our dispatch APIs, or if you just need ETAs/paths check out our routing APIs.