This lesson has notes and guides only.
00:00
In this video, we're going to walkthrough how to use RealtimeRawPointsByGeometry. So what exactly does this endpoint do? RealtimeRawPointsByGeometry gives you raw, real-time point data for the polygon of your choosing. Once you send a request, you’ll continue to receive data until you stop the stream or it times out and reconnects.
00:18
This endpoint is great for giving real-time, raw data packets to your own model and tools. Just keep in mind the data is not road-matched or trip-stitched as we're passing it to you as soon as we get it from the vehicle. Now let's look at how to set up a request in the Road Intelligence docs. Before we start, make sure you're authenticated.
00:35
If not, complete the Authenticate endpoint. You can learn how in our Intro to APIs video. To get started, first, select RealtimeRawPointsByGeometry from the left-hand menu. On the Docs tab, you'll see what information the API needs from you and what you will receive in its response. Next, we'll switch to the Try It tab to build your request. To structure your request, first, you'll need to put in the WKT you want data for. Then choose your streaming environment. You have the choice between Prod or Dev.
01:03
The Prod environment uses a single stream. Meaning if multiple people in your organisation are requesting the same data, you will compete and only one person will get the data packet. The advantage of this is that if the connection breaks, Compass knows the last sent packet, making it easier for us to help you get reconnected. We suggest only using this environment when you are streaming data on behalf of the whole organisation.
01:26
On the other hand, the Dev environment establishes a completely new stream of data each time. So this means if you send this request and someone else in the same workspace does too, you'll both receive all the data. However, because each request makes a new connection each time, we can't help if you lose your connection.
01:43
Ultimately, what is important to remember whichever environment you choose, the data is the same. For the purposes of this video, we'll choose Dev. We also need to choose your maxStalenessMinutes. Essentially, this is how long you're happy to wait for us to pass the real-time data to you. This value needs to be at least 1 and can exceed 180.
02:02
For our streaming APIs, you can change the throttle. This allows you to slow down or increase the stream speed. For now, I'll leave it as is. Now, click Start. Just keep in mind it may take a few minutes. Then you'll see the processed data packets streaming in. You'll have the packet count on the right hand side here, and by clicking the Stop button you can stop the stream.
02:34
Within each packet there is: the ingest time, so when in seconds the packet was ingested by us; the fuel or charge, odometer, make and model, where it's available: the trip ID, this is only sometimes given by the provider; gyroscopic information; acceleration information; position information, so the bearing, speed, latitude and longitude of the point, this is raw since we haven't had time to road-match the point. You'll also receive the vehicle type, transport type, timestamp, vehicle ID. You may also see a field called tag. This is any extra metadata we get from the provider.
03:08
As you look at each of your data packets, you might notice that some fields might be missing or empty. Fields will only be filled if the data is available for that point.
03:17
Looking at this data in the docs can be overwhelming, so most people stream it straight into their models via our SDK files. So let's take a look.
03:25
When you go to our GitHub, you'll see that as a repository you need to install. 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 completely authenticate that endpoint. In our GitHub, we'll open the Python folder and scroll down to the RealtimeRawPointsByGeometry here.
03:43
If you have a look, you can see that this section is similar to the API docs. So when you copy this code you can change these fields like we did in the API docs. Just keep in mind that when you set up a stream through our SDK files we’ll automatically close and reopen this stream every 5 minutes.
03:59
And that's it. In this lesson, we learned what the RealtimeRawPointsByGeometry 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.
We'd love to hear what you think. Leave your details below if you'd like to be contacted.