Gathering data

Available data

The Telraam API provides information on road segments and sensors locations, or parameters, but most importantly, it offers traffic data. Every hour, each sensor sends information on traffic counts, for each transportation mode and road direction, along with a confidence metric. In addition to traffic counts, estimated car speed and a car speed histogram are also available. Further details on the data will be provided in this vignette.

Load included dataset

Included dataset is lazily loaded with the telraamStats package. If you have already called library(telraamStats), the dataset is already attached and you can call it directly :

head(traffic)

Otherwise, if you don’t want to load the entire package, you can also access this dataset by using telraamStats::traffic.

1. Obtain a Telraam token

To work with data from one sensor - or more -, you must first create a Telraam (free) account to obtain an API token. The API token serves as a unique identifier for accessing the Telraam API service, which is used in this package. You can generate it in your personal dashboard on the Telraam website. For more information about the Telraam API, refer to the Telraam Q&A website.

2. Specify your token in configuration

It is strongly recommended not to directly embed your token in the code, especially if the code is shared or versioned using a system like Git.

You have two options to specify your own Telraam token :

1. Edit your .Renviron file. .Renviron is useful for defining sensitive information or R environment variables: it contains a list of environment variables to set. An easy way to edit this file and add your Telraam token is by using the usethis package. Run the following command (either once or every time you change your API Token) : .Renviron file will open in RStudio and you can add a new line in the form token='YourTelraamAPIToken'.

if (!require("usethis")) install.packages("usethis") #if you haven't installed 'usethis' already
usethis::edit_r_environ()

2. If you are not comfortable with the previous step, you can use an built-in function of the telraamStats package. However, keep in mind that you will need to run this function every time you want to retrieve your data:

set_telraam_token(token = 'YourTelraamAPIToken')

If you want to verify that your token is correctly set, you can use the following command :

get_telraam_token()

3. Specify road segment IDs in configuration file

Each road segment has a unique ID, which can be found in the Telraam location URL. For instance, here is the URL for one of Châteaubourg’s segments https://telraam.net/home/location/9000005665, and its ID is located in the last part of the URL (9000005665). Once you have gathered the IDs for all your segments, you can specify them by editing the inst\config.yml file.

This file can be created using the create_config() function. Once executed, you find a config.yml file in the inst\ folder of your work directory.

create_config(create_directory = TRUE)

The file already contains the following template, which you can modify (directly in the yml file) to add your own segments, adhering to the format of the template, that is, segment name (without quotes), followed by a colon, then the segment number within quotes : segmentName: '9000000000'.

default:
  url: https://telraam-api.net/v1
  segments:
    segment-01: '9000000000'
    segment-02: '9000000000'

You can specify as many segments as you want and personalize the segment’s names.

default:
  url: https://telraam-api.net/v1
  segments:
    MyFirstSegment: '9000000000'
    My-second-segment: '9000000000'
    My_3rd_segment: '9000000000'

If you don’t want to create a folder in your project directory, another option is to use a temporary folder and specify your segments names and IDs directly through the create_config() function, but you will have to re-run this command at each session.

list_of_segments = list("Burel"= "9000002156", "Vitre" = "9000001844")
create_config(segments = list_of_segments, create_directory = FALSE)

4. Get data for your road segments

Once you have specified the names and IDs of your road segments, you can use the retrieve_sensor() function to gather data from this segment from the Telraam API. This function takes, as arguments, the name of the segment, the first and the last day of the period of interest. You must use the same names as specified in the configuration files and dates must be of the date type.

retrieve_sensor(segment_name = "segment-01", 
                start_date = as.Date('2023-09-01'), 
                end_date = as.Date('2023-09-30'))

If you want to store the data, you can directly use write_update_data(), which performs the same task but also writes or updates the sensor data in a temporary folder or in the data/ directory in .Rdata format. The arguments are the same as those of the previous function:

write_update_data(segment_name = "segment-01",
                  start_date = as.Date('2023-09-01'),
                  end_date = as.Date('2023-09-30'),
                  create_directory = FALSE) #TRUE if you want to save the data in a permanent folder

To retrieve data you have already stored, you can use import_sensor(). This function imports data associated with a given list of sensor names from .RData files contained in the data/ directory. Here, you should also use the same names as specified in the configuration files. All available periods will be imported.

import_sensor(list_sensor = c("segment-01","segment-02"))