RealtimeTrajectoryByPath

What you’ll learn

• What is the RealtimeTrajectoryByPath endpoint? This endpoint gives real-time and road-matched vehicle trajectories for your selected linestring and specified date. This data is the raw version of what you see on the platform in the Realtime Trajectory tool.
• Why use this endpoint? RealtimeTrajectoryByPath is helpful when you want to stream real-time and road-matched trajectories into your own models and graphs.
  
  • Specific use cases include live monitoring of trips along corridors, identifying real-time bottlenecks, and powering live dashboards.
  • Limitations: Only accepts WKT linestrings and needs at least two data points per trip. Does not provide historical data, and the extracted data is raw, not road-matched, and requires post-processing. Real-time data is a subset of all Compass data and may not work well unless you are selecting major roadways (there is no guarantee of instant response until vehicles drive along the linestring).
• How to format a request for this endpoint: Provide a WKT file (only linestrings are supported). Since this is a real-time endpoint you do not to choose a date range as it is from the current point in time.
• How to understand the response from this endpoint: The endpoint will stream real-time data packets for your specified path until paused or completed. Each packet will provide information like trajectory ID, timestamp, distance along path, and speed.
• Important things to consider:
  • Not all connected vehicles transmit data frequently enough to be included for real-time trajectory. While most connected vehicles transmit position events in real-time, some transmit them in bulk or later on in the trip when the vehicle has a strong connection.
  • You will need more than 1 point to plot trajectories on a graph.

Further Links

• Road Intelligence API Docs
• If you wish to use our SDK Files, visit our GitHub here or contact sujith@compassiot.com.au‍
• Watch our Import/Export WKT Files lesson video.‍
• To understand historical trajectories, watch our TrajectoryByPath lesson video.
• Supplementary Data Dictionary

00:00

In this video, we're going to walkthrough how to use RealtimeTrajectoryByPath. So, why use this endpoint? RealtimeTrajectoryByPath is the backend to our Realtime Trajectory tool that you see on the Road Intelligence platform.

00:11

It gives you all the raw and real-time points that have a high packet frequency to possibly be part of Realtime Trajectory. Ultimately, vehicle trajectories help understand how long it takes to travel a path or intersection, identifying where vehicles stop or slow down.Since this is a streaming endpoint, once you send a request, the API will continue to stream packets until stopped.

00:30

Now let's look at how to set up a request. Before we start, make sure you're authenticated. If not, complete the Authenticate endpoint. To get started, first select RealtimeTrajectoryByPath from the left menu. On the Docs tab, you'll see what information you need to give and what you will receive. Next, we'll switch to the Try It tab.

00:50

To build your request, first you need to put in the WKT linestring you want data for. You can export WKTs from the Road Intelligence platform.

00:57

You don't need to establish a start date or end date since this is a stream of current time data. If you want trajectories for a selection in the past, you'll need to use our TrajectoryByPath endpoint. We'll link that video for you in the lesson notes below. For our streaming APIs, you can change your throttle. This means you can slow down or increase the speed.

01:16

For now, I'll leave it as is. Now click start. Now you may not get trajectory points straight away. This is because not all connected vehicles transmit data frequently enough to be included for Realtime Trajectory. While most connected vehicles transmit position events in real-time, some transmit them in bulk or later on in the trip when the vehicle has a stronger connection. This means you may not get trajectories for your path for a while, so we recommend choosing a path that you know has a lot of traffic.

Note that you also need more than one point to plot trajectories on a graph.

01:47

When the API returns packets, you'll see a packet count on the right hand side, and by clicking the Stop button, you can stop the stream.

Within each packet, there is the trajectory ID, timestamp, distance along the path the point was recorded, and the speed.

02:01

Let's take a look at how you would use our SDK files to set up a real-time stream into your own tools. When you go our GitHub, you'll see there is a repository you'll need to install.

02:10

Make sure when you access the repository you're in the language you want to run. Similar to our API docs, you'll need to complete the Authenticate endpoint before using any other endpoints. In our GitHub, we'll open the Python folder and scroll down to the RealtimeTrajectoryByPath here.

02:28

You can see that this section is similar to the API docs. So when you copy this code into your own model, you can change these fields like we did before. Just keep in mind that when you set up a stream through our SDK files, we’ll automatically close and reopen the streaming endpoint every 25 minutes.

02:44

And that's it. In this lesson, we learnt what the RealtimeTrajectoryByPath endpoint is, how to set-up your request, and start the streaming. If you need more help using our SDK files, you can find more information in the lesson notes below. We'll see you in the next video.