This lesson has notes and guides only.
00:00
In this video, we're going to walkthrough how to use the ProcessedPointByGeometryFileExport in our API docs. So what exactly does this endpoint do? Put simply ProcessedPointByGeometryFileExport gives you road-matched and trip-stitched data for paths or polygon of your choosing.
00:19
This data is returned as a downloadable link, which you can choose to be a CSV, PARQUET, JSON, or ARVO file type. This endpoint is the unary version of the ProcessedPointByGeometry streaming endpoint, which we'll cover in a future video. ProcessedPointByGeometryFileExport is helpful when you're working with large areas or time ranges, and you want to analyse the data in your own tools.
00:41
Now let's look at how to format a request using the Road Intelligence Docs. Before we start, make sure you are authenticated. If you've done this, you'll see a green tick in the top right. If not, complete the Authenticate endpoint. You can learn how in our Intro to APIs video.
00:57
To get started, first, select ProcessedPointByGeometryFileExport on 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 submit a request.
01:12
Now let's walk through how to structure your request. First, you'll need to put in the WKT linestring or polygon you want information about here. You can export WKT's from the Road Intelligence platform.
First, you need to select the path or area you want to export. Turn on Advanced View under the Profile Icon in the top right corner. You'll see the Export As WKT button appear at the bottom of the Area Selection panel. Click this and we'll see a pop up say that the file has been copied to your clipboard.
To extract a WKT file for polygon, you will need to change to the Origin Destination tool. Then draw an area, and click Export As WKT. Now you can paste this.
02:08
Then use start date and end date to define the date and time range you want to extract the data for. You'll need to specify your date by their numerical value. So if I want to extract data for March I'll need to put the number 3.
02:27
You can filter data by specific hours of the day, for example 9 and 15 if you only want to see data for 9 am and 3 pm. So if you want all hours, leave it blank.
02:39
You can also filter by day of the week and exclude specific dates from your request. These dates need to be added individually and not as a range. If you don't want to have any exclusions, you can delete these.
02:56
Next, you can filter data to receive only near misses or road roughness data. If you don't want to filter, simply delete these.
03:10
You can also limit how much data you want to receive or when we last received it. Remove these fields to get everything.
03:23
Similar to days of week, you can filter the data for specific vehicle types or just include all vehicle types.
03:32
Lastly, choose how you want to receive the data. Choose between PARQUET, CSV, JSON, or ARVO depending on your needs.
03:40
Now that we filled out the fields, click Send. Just keep in mind large queries may take a few seconds to process, so if the links don't show up straightaway, give it a moment.
03:58
When the request is successful, you'll see a list of download links or cURLs in the response. You might get one or multiple links depending on the size of your data. These links are valid for only seven days. You can download each file type by copying the cURLs and pasting them into your browser address bar. Depending on your selected format, the data will open in different programs.
04:20
Looking at the CSV we've just downloaded, let's quickly run through what information you'll receive.
04:26
The Point ID, Trip ID and Vehicle ID. These are globally unique identifiers. For each point, you'll also get the timestamp, including the date and time in Coordinated Universal Time. You'll see the vehicle type and transport type.
04:40
So whether it might be a car or bus or if it is a public or private vehicle, in some cases the vehicle type may be unspecified. Then you'll receive the speed and bearing of the point. You also get the X, Y, and Z acceleration data. Z is how a car moves up and down. Y means side to side or turning, and X is acceleration and braking.
05:02
On the other hand, gyroscopic data - roll, pitch, and yaw - is rotationally based. Note that some of these fields will be blank, as not all points have this data.
05:12
You'll also receive the raw latitude and longitude, as well as the road-matched latitude and longitude of the point.
05:18
Quality indicates road roughness. Not all regions have road roughness data. If this is the case, the value will be zero.
05:25
For some points you will receive the make and model.
05:31
All points will have an OSM ID. This is the unique ID of where the point is on the Open Source Map.
05:37
You will also receive near miss information if the point is a near miss.
05:42
And that's it! In this lesson, we learnt what the ProcessedPointByGeomteryFileExport is, how to set up your request, and download your data. If you want to use this endpoint via our SDK files, check out our GitHub link 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.