Back to Documentation Overview

Map Annotations

Map Annotations enable you to add custom map attributes to the basemap of the rideOS routing engine. You can annotate areas, paths, and turns with additional information using the Map Annotation API.

These annotations can be used in the Path API, ETA API and Routing Profile API to create operational and avoidable constraints.

In this guide, we will:

  1. Add a map annotation
  2. Get the current status of the annotation
  3. Use this annotation to define a constraint in the Path API
  4. Delete the annotation

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: Add a map annotation

We will annotate features on the map using the AddOrReplaceAnnotation endpoint. A feature can either be an area, path or turn and we can annotate multiple features against a single annotation ID. Refer to the documentation of AddOrReplaceAnnotation for the expected format of each feature.

In this guide, as an example, we have annotated 3 features - an area, a path, and a turn.

curl --request POST https://api.rideos.ai/map-annotation/preview/AddOrReplaceAnnotation \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{
          "annotation": {
            "id": "annotation-1",
            "features": [
              {
                "area": {
                  "positions": [
                    { "latitude": 37.79810407391278, "longitude": -122.41217348165807 },
                    { "latitude": 37.79857854982762, "longitude": -122.40872867369097 },
                    { "latitude": 37.7968217251476,  "longitude": -122.40841105608867 },
                    { "latitude": 37.79649545310591, "longitude": -122.4117461997197  },
                    { "latitude": 37.79810407391278, "longitude": -122.41217348165807 }
                  ]
                }
              },
              {
                "path": {
                  "positions": [
                    { "latitude": 37.79602502056058, "longitude": -122.42020691026937 },
                    { "latitude": 37.7962305209792,  "longitude": -122.41841536896372 }
                  ]
                }
              },
              {
                "turn": {
                  "positions": [
                    { "latitude": 37.7957009485336,   "longitude": -122.42003210274581 },
                    { "latitude": 37.79526279134842,  "longitude": -122.41995289037051 }, 
                    { "latitude": 37.795367114723334, "longitude": -122.41906835218067 }
                  ]
                }
              }
            ]
          }
        }'

Step 2: Get current status of the annotation

Annotations require some processing time before they can be referenced. Thus, we will call the GetAnnotationStatus endpoint to check if our annotation has been processed.

curl --request POST https://api.rideos.ai/map-annotation/preview/GetAnnotationStatus \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{ "annotationId": "annotation-1" }'

We get the status as INACTIVE if the annotation has been added but not processed yet. We call this endpoint until the status is ACTIVE, which denotes that the annotation has been processed.

{"status":"ACTIVE"}

To know more about the different types of status, please refer to the GetAnnotationStatus endpoint.

Step 3: Use annotation to define a constraint in the Path API

Once an annotation has been added, we can reference it in the Path API and ETA API to achieve a custom routing behavior. We can also save frequently used annotations in a Routing Profile that can be further referenced in the Path API and ETA API.

In this guide, as an example, we will use these annotations as avoidable constraints in the Path API. Thus, our routing engine will create an optimized route while avoiding the annotated areas, paths, and turns.

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.79593051760093, "longitude": -122.42172689811805 },
              "heading": 0,
              "type": "STOP"
            },
            {
              "position": { "latitude": 37.787521164241866, "longitude": -122.40652763010677 },
              "heading": 0,
              "type": "STOP"
            }
          ],
          "avoidConstraintIds": ["annotation-1"]
        }'

We will also request a path without using constraints to compare the travel time and distance

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.79593051760093, "longitude": -122.42172689811805 },
              "heading": 0,
              "type": "STOP"
            },
            {
              "position": { "latitude": 37.787521164241866, "longitude": -122.40652763010677 },
              "heading": 0,
              "type": "STOP"
            }
          ]
        }'

Here are the responses we get with constraints and without it. We can see that the vehicle in the second call has a shorter travel time and covers a shorter distance as it doesn't have to avoid the road segments marked by the avoidable constraints.

# avoid constraints are set
{"travelTime":"533.591s","distance":2526.2989773112686}
# avoid constraints are not set 
{"travelTime":"463.044s","distance":2307.3837048276}

Step 4: Delete the annotation

We will now delete the annotation using the Delete Annotation endpoint.

curl --request POST https://api.rideos.ai/map-annotation/preview/DeleteAnnotation \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{ "annotationId": "annotation-1" }'

We have successfully used the Map Annotation API to add custom map attributes and further used them as constraints. You may also want to: