Back to Documentation Overview

Routing Profiles

Routing profiles allow you to define different routing behaviors across the Routing, Fleet Planner, and Dispatch APIs and easily switch between them. As an example, routing profiles would allow you to easily switch between routing constraints for different autonomous and human-driven vehicles in your fleet.

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.

Setting Constraints

First we'll set up some constraints to use in our routing profiles. This can be done through a call to the constraints endpoint. The first constraint is a restricted area around most of downtown San Francisco, while the other two are smaller constraints restricting turns and avoiding a certain small section of road.

curl --request POST https://api.rideos.ai/constraints/v1/AddOrReplaceConstraints \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{
    "constraints": [
        {
            "id": "constraint_0",
            "avoidArea": {
                "positions": [
                    {
                        "latitude": 37.80535738107623,
                        "longitude": -122.42572950479695
                    },
                    {
                        "latitude": 37.807204014271484,
                        "longitude": -122.41017218082159
                    },
                    {
                        "latitude": 37.786022667936166,
                        "longitude": -122.40608199235872
                    },
                    {
                        "latitude": 37.78394460661894,
                        "longitude": -122.4214932381746
                    },
                    {
                        "latitude": 37.80535738107623,
                        "longitude": -122.42572950479695
                    }
                ]
            }
        },
        {
            "id": "constraint_1",
            "avoidPath": {
                "positions": [
                    {
                        "latitude": 37.77223689715481,
                        "longitude": -122.42318837292667
                    },
                    {
                        "latitude": 37.79443183427474,
                        "longitude": -122.39494488767747
                    }
                ]
            }
        },
        {
            "id": "constraint_2",
            "avoidTurn": {
                "positions": [
                    {
                        "latitude": 37.78375453272309,
                        "longitude": -122.4215545663252
                    },
                    {
                        "latitude": 37.78593223138598,
                        "longitude": -122.40607142392865
                    },
                    {
                        "latitude": 37.77519866677605,
                        "longitude": -122.41978318986462
                    }
                ]
            }
        }
    ]
}'

Create a Routing Profile

We can now set a routing profile that uses the all constraints that we've just created.

curl --request POST https://api.rideos.ai/routing-profile/preview/AddOrReplaceRoutingProfile \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{
  "id": "profile_0",
  "routingProfile": {
    "avoidConstraintIds": [
      "constraint_0",
      "constraint_1",
      "constraint_2"
    ]
  }
}'

However, let's say we want a profile that uses similar constraints besides the first one that blocks off a major area of downtown San Francisco. All we have to do is create another profile without the first constraint.

curl --request POST https://api.rideos.ai/routing-profile/preview/AddOrReplaceRoutingProfile \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{
  "id": "profile_1",
  "routingProfile": {
    "avoidConstraintIds": [
      "constraint_1",
      "constraint_2"
    ]
  }
}'

Use Routing Profiles in ETA/Path/Fleet Planner API

We can now apply our new routing profile to any ETA, path API, or fleet planner call. As an example, if we wanted to get the ETA of a vehicle driving through downtown San Francisco but we wanted it to avoid the areas in which we set our constraints, we would just use our routing profile:

curl --request POST https://api.rideos.ai/path/v2/GetPath \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{
  "waypoints": [
    {
      "position": {
        "latitude": 37.796162172433704,
        "longitude": -122.40673330544587
      },
      "heading": 0,
      "type": "STOP"
    },
    {
      "position": {
        "latitude": 37.79028808530567,
        "longitude": -122.42312619613266
      },
      "heading": 0,
      "type": "STOP"
    }
  ],
  "routingProfileId": "profile_0"
}'

Compare this with an ETA call with the second routing profile that we created, and you can see that our ETA gets much shorter as the vehicle doesn't have to drive around the constrained area we set.

curl --request POST https://api.rideos.ai/path/v2/GetPath \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data'{
  "waypoints": [
    {
      "position": {
        "latitude": 37.796162172433704,
        "longitude": -122.40673330544587
      },
      "heading": 0,
      "type": "STOP"
    },
    {
      "position": {
        "latitude": 37.79028808530567,
        "longitude": -122.42312619613266
      },
      "heading": 0,
      "type": "STOP"
    }
  ],
  "routingProfileId": "profile_1"
}'

Here's a snippet from the response of the first ETA call using the more restricted routing profile vs. the second ETA call showing the difference in ETA calculations:

... 
"travelTime": "1076.724s",
"distance": 5537.446507864566
...
...
"travelTime": "290.859s",
"distance": 2316.7571682833354
...

You can also use routing profiles in fleet planner. Routing profiles are defined on a per-vehicle basis, this way different vehicles with different capabilities can be given different routing profiles. One possible way this could be used is to assign different vehicles to different pickup/dropoff zones, as routing profiles could define which constraints (areas) the vehicles could travel in.

curl --request POST https://api.rideos.ai/fleet/v2/GetPlan \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{
  "vehicles": {
    "property1": {
      "position": {
        "latitude": 37.79041302,
        "longitude": -122.3921746
      },
      "heading": 0,
      "resourceCapacity": 5,
      "vehicleId": "vehicle_0",
      "restrictTaskInsertionsUpTo": 0,
      "routingProfileId": "constraint_0"
    },
    "property2": {
      "position": {
        "latitude": 37.79041302,
        "longitude": -122.3921746
      },
      "heading": 0,
      "resourceCapacity": 5,
      "vehicleId": "vehicle_0",
      "restrictTaskInsertionsUpTo": 0,
      "routingProfileId": "constraint_1"
    }
  },
  "tasks": {
    "property1": {
      "resourcesRequired": 0,
      "pickupStep": {
        "position": {
          "latitude": 37.79041302,
          "longitude": -122.3921746
        },
        "heading": 0
      },
      "dropoffStep": {
        "position": {
          "latitude": 37.79041302,
          "longitude": -122.3921746
        },
        "heading": 0
      }
    }
  }
}'

That's about it! Wrapping up, we showed how routing profiles are powerful tools to help customize how different path, ETA, and fleet planner calculations are carried out. You might also want to check out the documentation for our Routing Profile, Path, ETA, and Fleet Planner APIs.