NAV Navbar

Introduction

This webpage contains documentation of the lvl5 HD mapping API.

RoadDelta

RoadDelta allows engineers and data scientists to monitor specific areas of the world for changes in the environment with unparalleled decimeter accuracy. Specifically, RoadDelta reports addition, removal and displacement of the following point features, as well as changes in driveable area.

Point Features

Driveable Area

Coverage

Pricing

Feature Price Description
RoadDelta $0.008/(meter2-day) $0.008 per m2 of monitored area, per day that monitoring is engaged

Pricing Example - 700 meter2 Intersection

California & Leavenworth Intersection

Price Calculation - Fetch Historical Changeset

"What has changed, if anything, about the traffic signs, traffic lights, or driveable area configuration of this intersection in the past 30 days?"

cost_of_query = $0.008/(m^2*day) * total_monitored_area * change_window_duration_days

cost_of_query = $0.008/(m^2*day) * 700 meters^2 * 30 days = $168

Price Calculation - Continuous Monitoring

"Send alert, if anything changes, about the traffic signs, traffic lights, or driveable area configuration of this intersection"

cost_of_notification_per_day = $0.008/(m^2*day) * total_monitored_area

cost_of_notification_per_day = $0.008/(m^2*day) * 700 m^2 = $5.6/day

RoadDelta

One-Time Check for Changes

The change history of a particular area_of_interest can be fetched directly using the following endpoint.

Fetching a Changeset

GET https://api.lvl5.ai/v1/changesets

Example Changeset Request

curl https://api.lvl5.ai/v1/changesets \
    -u lvl5_api_key \
    --request GET \
    -d '<REQUEST_BODY>'

Request Body

{
    "changes_since_date": "2018-04-23T18:25:43.511Z",
    "changes_to_date": "2018-07-27T18:25:43.511Z",
    "point_features_enabled": true,
    "driveable_area_enabled": true,
    "area_of_interest": <GeoJSON Polygon>
}

Changeset Request Attributes

Attribute Type Description
changes_since_date ISO 8601 timestamp Timestamp on map before change
changes_to_date ISO 8601 timestamp Timestamp on map after change
point_features_enabled boolean Return changes to point features in map (see pricing)
driveable_area_enabled boolean Return changes to driveable areas in map (see pricing)
area_of_interest GeoJSON Polygon Area in which changes will be reported

Continuously Monitor an Area

If you'd like to monitor a specific road or intersection for change, rather than polling for changes, you can let lvl5 POST the Changeset to an HTTPS endpoint of your choice. Register a notifier by suppling a callback_url endpoint that lvl5 will call when a Changeset that applies to your area_of_interest becomes available. If you're only interested in changes to point features (signs and traffic lights) or if you're only interested in changes to driveable area, you can set driveable_area_enabled to false or point_features_enabled to false, resepctively. If neither point_features_enabled nor driveable_area_enabled is set to true, the lvl5 API call will return an error.

Example 1

You would like to be alerted if the configuration of traffic lights changes at a particular intersection.

Registering a Notifier

POST https://api.lvl5.ai/v1/callbacks

Example Notifer Registration

curl https://api.lvl5.ai/v1/callbacks \
    -u lvl5_api_key \
    --request POST \
    -d '<REQUEST_BODY>'

Notification Registration Request Body

{
    "callback_url": "https://domain.com/endpoint",
    "point_features_enabled": true,
    "driveable_area_enabled": true,
    "area_of_interest": <GeoJSON Polygon>
}

Notification Registration Response Body

{
    "notifier_id": "f3eea169-92a5-4165-a439-fd0e1c51fd7d"
}
Attribute Type Description
callback_url string Endpoint to be called upon Changeset availability
point_features_enabled boolean Return changes to point features in map (see pricing)
driveable_area_enabled boolean Return changes to driveable areas in map (see pricing)
area_of_interest GeoJSON Polygon Area in which changes will be reported

Callback Format

Example Changeset Callback

{
    "notifier_id": "f3eea169-92a5-4165-a439-fd0e1c51fd7d",
    "changeset": {
        "point_feature_changes": [
            <PointFeatureChangeObject>,
            <PointFeatureChangeObject>
            ],
        "driveable_area_changes": [
            <DriveableAreaChangeObject>,
            <DriveableAreaChangeObject>
            ]
    }
}
Attribute Type Description
notifier_id String (UUID) ID of notifier
changeset Changeset Changeset capturing a recent change in requested monitoring area

Deregistering a Notifier

DELETE https://api.lvl5.ai/v1/callbacks/<ID>

Example Notifier Deregistration

curl https://api.lvl5.ai/v1/callbacks/<ID> \
    -u lvl5_api_key \
    --request DELETE \
    -d id=callback_id

Changeset Object

The Changeset object contains observed changes to roadways (see Types of Changes Detected, above) over a specific period of time, within a certain geographic area, determined by the user of the API. The geographic area, area_of_interest is encoded as a GeoJSON Polygon.

Sample Changeset Object

{
    "changes_since_date": "2018-04-23T18:25:43.511Z",
    "changes_to_date": "2018-07-27T18:25:43.511Z",
    "point_feature_changes": [
        <PointFeatureChangeObject>,
        <PointFeatureChangeObject>
    ],
    "driveable_area_changes": [
        <DriveableAreaChangeObject>,
        <DriveableAreaChangeObject>
    ]
}

Changeset Object Attributes

Attribute Type Description
changes_since_date ISO 8601 timestamp min(requested changes_since timestamp, earliest observation)
changes_to_date ISO 8601 timestamp the last time this area was observed
area_of_interest GeoJSON Polygon geographic area to which this Changeset applies
point_feature_changes list changes to point features (signs, traffic lights)
driveable_area_changes list changes to driveable area (road, parking spot, sidewalk, crosswalk)

PointFeatureChange Object

The PointFeatureObject contains change of a point feature such as a traffic sign or traffic light.

PointFeatureObject Attributes

Attribute Type Description
feature_id integer lvl5-unique persistent feature identifier
feature_type string (point feature type identifier) type of point feature (MAJOR_MINOR)
old_position GeoJSON Point with elevation or null point feature position (null if feature was added)
new_position GeoJSON Point with elevation or null point feature position (null if feature was removed)

Sample Point Feature Object

{
    "feature_id": 836053,
    "feature_type": "SIGN_REGULATORY",
    "old_position": <GeoJSON Point with Elevation>,
    "new_position": <GeoJSON Point with Elevation>
}
Point Feature Types
SIGN_REGULATORY
SIGN_DIRECTIONAL
TEMPORARY_TRAFFIC_CONE
TRAFFIC_LIGHT_TRAFFIC_CONTROL
TRAFFIC_LIGHT_WARNING

Examples of PointFeatureChange

DriveableAreaChange Object

The DriveableAreaChange contains change of drivable area.

DriveableAreaObject Attributes

Sample Driveable Area Object

{
    "area": <GeoJSON Polygon>,
    "approximate_altitude": 120.2,
    "old_type": "ROAD_DRIVEABLE",
    "new_type": "PARKING_SPACE"
}
Attribute Type Description
area GeoJSON Polygon Geographic area that underwent change from old_type to new_type
approximate_altitude float Approximate elevation of the area's center-of-mass
old_type string (surface type identifier) old surface type
new_type string (surface type identifier) new surface type
Surface Types
ROAD_PAVEMENT
ROAD_SHOULDER
LANE_BOUNDARY
STOP_LINE
BIKE_LANES
MANHOLE_COVER
PEDESTRIAN_CROSSWALK
SIDEWALK

Examples of DriveableAreaChange

Map Coordinate Convention

GeoJSON

We leverage the existing GeoJSON format for encoding spatial information in JSON. This means that coordinates are encoded in the WGS84 coordinate system; longitude and latitude units are decimal degrees and altitudes are measured as height (meters) above or below the WGS84 reference ellipsoid.

GeoJSON Polygon Object

Example GeoJSON Polygon

"geometry": {
    "type": "Polygon",
    "coordinates": [
        [
            [-122.4160436, 37.7913446],
            [-122.4159658, 37.790997],
            [-122.4154924, 37.7910447],
            [-122.4156077, 37.7914114],
            [-122.4160436, 37.7913446]
        ]
    ]
}

The GeoJSON Polygon object is used to describe geographic areas both in requests and responses, to and from the lvl5 API.

Example GeoJSON Polygon Describing the California/Leavenworth Intersection

California & Leavenworth Intersection

GeoJSON Point Object

Example GeoJSON Point

{
   "type": "Point",
   "coordinates": [-122.415800, 37.791181, 58.2]
}

The GeoJSON Point object is used to describe 3D points in responses from the lvl5 API.