In ymansiaux/xtradata: Interrogation des Webservices Xtradata

knitr::opts_chunk$set(echo = TRUE)

Xtradata Bordeaux Métropole

Cette documentation concerne la version 0.4.0 du package.

Ce package propose d'interroger les webservices xtradata de Bordeaux Métropole.

En l'état seuls les services features et aggregate peuvent être interrogés via ce package.

Davantage d'informations sur ces webservices sont disponibles ici : webservices xtradata BM

L'utilisation des services (et par conséquent du package) nécessite de posséder une clé d'accès. Demande de clé

Pour toute question concernant ce package : [e-mail]

Installation du package

Pour l'installation du package les dépendances remotes et git2r sont requises.

Veuillez noter que les dépendances suivantes seront également installées : assertthat, curl, geojsonsf, glue, jsonlite, magrittr, purrr, utils.

devtools::install_git( 
  url = https://gitlab.com/bordeaux-metropole-public/r-modules/xtradata.git,
  ref = "master",
  force = TRUE,
  credentials = git2r::cred_user_pass("xtradatauser", "S4ExAmyXxhAxx6Hh_ouT")
)

library(xtradata)

Utilisation du package

Webservice features

Ce webservice renvoie les données d'une couche. Pour obtenir davantage d'infos, consulter la documentation de la fonction xtradata_requete_features ou la page dédiée de ce webservice infos features.

Appel minimal

Les 2 paramètres requis sont le paramètre key (la clé d'accès) et le paramètre typename (la couche de données à récupérer). Les exemples fournis ensuite concernent la couche PC_CAPTE_P, qui décrit les données temps réél des capteurs auto.

Pour davantage d'informations sur les attributs présents dans une couche donnée, le dictionnaire dicopub est une ressource indispensable.

key <- Sys.getenv("XTRADATA_KEY")

# Couche des capteurs de trafic auto
typename <- "PC_CAPTE_P"
# key <- "VOTRE_CLE_OPEN_DATA"

requete <- xtradata_requete_features(key = key, typename = typename)

head(requete)

Si le résultat de la requête contient une composante géographique, l'objet renvoyé sera de classe "sf", dans le cas contraire l'objet sera un data.frame.

Parametre filter

Le paramètre filter peut être fourni de 2 façons, soit sous forme d'une liste R, soit sous format d'une chaine de caractères avec un filtre écrit au format JSON (pratique pour faire des copier-coller depuis le service swagger)

filter_list <- list(
  "type" = "BOUCLE",
  "mdate" = list(
    "$gt" = "2020-01-01T08:00:00"
  )
)


filterJSON <- '{
"type": "BOUCLE",
"mdate": {
  "$gt": "2020-01-01T08:00:00"
 }
}'

# 2 façons d'utiliser le paramètre filter
res1 <- xtradata_requete_features(
  typename = typename, key = key,
  filter = filter_list
)

res2 <- xtradata_requete_features(
  typename = typename, key = key,
  filter = filterJSON
)

# on vérifie que les résultats sont identiques
all.equal(res1, res2)

Les filtres sur un même champ doivent être combinés avec les opérateurs "$and", "$or", "$not"

filterJSON_combined <- '{
 "$and": [
  { "gid": {"$gte": "1"} },
  { "gid": {"$lte": "5"} }
 ]
 }'

filter_list_combined <- list(
  "$and" = list(
    list("gid" = list(
      "$gte" = "1"
    )),

    list("gid" = list(
      "$lte" = "5"
    ))
  ))

res1 <- xtradata_requete_features(
  typename = typename, key = key,
  filter = filterJSON_combined
)

res2 <- xtradata_requete_features(
  typename = typename, key = key,
  filter = filter_list_combined
)

# on vérifie que les résultats sont identiques
all.equal(res1, res2)

Il est possible de fournir un tableau de données dans l'argument filter

filter_and_list <- list(
  "gid" = list("$in" = c(50:55))
)

filter_and_JSON <- '{
 "gid": {
  "$in": [
    50,51,52,53,54,55
  ]
 }}'

res1 <- xtradata_requete_features(
  typename = typename, key = key,
  filter = filter_and_list
)

res2 <- xtradata_requete_features(
  typename = typename, key = key,
  filter = filter_and_JSON
)

# on vérifie que les résultats sont identiques
all.equal(res1, res2)

Paramètre attributes

# 2 façons d'utiliser le paramètre attributes
attributes <- list("cdate", "mdate")
attributesArray <- '["cdate", "mdate"]'

filter_list <- list(
  "type" = "BOUCLE",
  "mdate" = list(
    "$gt" = "2020-01-01T08:00:00"
  )
)

res1 <- xtradata_requete_features(
  typename = "PC_CAPTE_P", key = key,
  filter = filter_list, attributes = attributes
)

res2 <- xtradata_requete_features(
  typename = "PC_CAPTE_P", key = key,
  filter = filter_list, attributes = attributesArray
)

# on vérifie que les résultats sont identiques
all.equal(res1, res2)

Paramètre backintime

Ce paramètre permet d'accéder aux données de la couche sélectionnée à une date donnée.

Utilisation de l'argument backintime avec une date ou un datetime

filter_list <- list(
  "type" = "BOUCLE",
  "mdate" = list(
    "$gt" = "2020-01-01T08:00:00"
  )
)

res1 <- xtradata_requete_features(
  typename = typename, key = key,
  filter = filter_list,
  backintime = "2021-06-01T10:00:00"
)

tail(res1$mdate)

res2 <- xtradata_requete_features(
  typename = typename, key = key,
  filter = filter_list,
  backintime = "2021-06-05"
)

tail(res2$mdate)

Utilisation de l'argument backintime avec une macro relative à la date / heure actuelle

res1 <- xtradata_requete_features(
  typename = typename, key = key,
  filter = filter_list,
  backintime = "-30min"
)

tail(res1$mdate)


res2 <- xtradata_requete_features(
  typename = typename, key = key,
  filter = filter_list,
  backintime = "-5hour"
)

tail(res2$mdate)

res3 <- xtradata_requete_features(
  typename = typename, key = key,
  filter = filter_list,
  backintime = "-7day"
)

tail(res3$mdate)


res4 <- xtradata_requete_features(
  typename = typename, key = key,
  filter = filter_list,
  backintime = "-1month"
)

tail(res4$mdate)

Paramètre orderby

# 2 façons d'utiliser le paramètre orderby
orderby <- list("mdate", "gid")
orderbyArray <- '["mdate", "gid"]'

res1 <- xtradata_requete_features(
  typename = typename, key = key,
  filter = filter_list,
  orderby = orderby
)

res2 <- xtradata_requete_features(
  typename = typename, key = key,
  filter = filter_list,
  orderby = orderbyArray
)

all.equal(res1, res2)

Webservice aggregate

Ce webservice renvoie une aggregation des objets historisés sur une période et un pas de temps donné. Pour obtenir davantage d'infos, consulter la documentation de la fonction xtradata_requete_aggregate ou la page dédiée de ce webservice infos aggregate.

Appel minimal

Les 3 paramètres requis sont le paramètre key (la clé d'accès), le paramètre typename (la couche de données à récupérer) et le paramètre rangeStart (le début de la période d'observation). Les exemples fournis ensuite concernent la couche ST_PARK_P, qui décrit les données temps réél des parkings hors voirie.

Pour davantage d'informations sur les attributs présents dans une couche donnée, le dictionnaire dicopub est une ressource indispensable.

# Couche des capteurs de trafic auto
typename <- "ST_PARK_P"
# key <- "VOTRE_CLE_OPEN_DATA"

requete <- xtradata_requete_aggregate(key = key, typename = typename, rangeStart = Sys.Date()-1)

head(requete)

Parametre filter

Le paramètre filter peut être fourni de 2 façons, soit sous forme d'une liste R, soit sous format d'une chaine de caractères avec un filtre écrit au format JSON (pratique pour faire des copier-coller depuis le service swagger

filter_list <- list(
  "ident" = "CUBPK88",
  "etat" = "LIBRE",
  "libres" = list(
    "$gt" = 145
  )
)

filterJSON <- '{
"ident": "CUBPK88",
"etat" : "LIBRE",
"libres": {
 "$gt": 145
}
}'

date_deb <- "2021-06-01"
date_fin <- "2021-06-05"


# 2 façons d'utiliser le paramètre filter
res1 <- xtradata_requete_aggregate(
  typename = typename, key = key,
  rangeStart = date_deb,
  rangeEnd = date_fin,
  rangeStep = "hour",
  filter = filter_list
)

res2 <- xtradata_requete_aggregate(
  typename = typename, key = key,
  rangeStart = date_deb,
  rangeEnd = date_fin,
  rangeStep = "hour",
  filter = filterJSON
)

# on vérifie que les résultats sont identiques
all.equal(res1, res2)

Parametre rangeFilter

Le paramètre rangeFilter peut également s'écrire de deux façons, de manière identique au paramètre filter

rangeFilter_list <- list(
  "hours" = 5:6,
  "days" = 1:7,
  "publicHolidays" = FALSE
)
rangeFilterJSON <- '{
  "hours": [
    5,6
  ],
  "days": [
    1,2,3,4,5,6,7
  ],
  "publicHolidays": false
}'


res1 <- xtradata_requete_aggregate(
  typename = typename, key = key,
  rangeStart = date_deb,
  rangeEnd = date_fin,
  rangeStep = "hour",
  filter = filter_list,
  rangeFilter = rangeFilter_list
)

res2 <- xtradata_requete_aggregate(
  typename = typename, key = key,
  rangeStart = date_deb,
  rangeEnd = date_fin,
  rangeStep = "hour",
  filter = filterJSON,
  rangeFilter = rangeFilterJSON
)

# on vérifie que les résultats sont identiques
all.equal(res1, res2)

Parametre attributes

Attributes sans précision d'opérateurs d'aggrégation

Dans ce cas les attributs numériques renverront la valeur moyenne et pour les autres types d'attributs, la première valeur sera retournée.

attributes_list <- list("gid", "libres")
attributesArray <- '["gid", "libres"]'

res1 <- xtradata_requete_aggregate(
  typename = typename, key = key,
  rangeStart = date_deb,
  rangeEnd = date_fin,
  rangeStep = "hour",
  attributes = attributes_list,
  filter = filter_list
)


res2 <- xtradata_requete_aggregate(
  typename = typename, key = key,
  rangeStart = date_deb,
  rangeEnd = date_fin,
  rangeStep = "hour",
  attributes = attributesArray,
  filter = filter_list
)

all.equal(res1, res2)

Attributes avec précision d'opérateurs d'aggrégation

L'ensemble des opérateurs autorisés sont détaillés dans la documentation du webservice aggregate.

attributes_key_value_list <- list("etat" = "first", "libres" = "max")
attributes_key_value_JSON <- '{"etat" : "first", "libres" : "max"}'

res1 <- xtradata_requete_aggregate(
  typename = typename, key = key,
  rangeStart = date_deb,
  rangeEnd = date_fin,
  rangeStep = "hour",
  attributes = attributes_key_value_list,
  filter = filter_list
)


res2 <- xtradata_requete_aggregate(
  typename = typename, key = key,
  rangeStart = date_deb,
  rangeEnd = date_fin,
  rangeStep = "hour",
  attributes = attributes_key_value_JSON,
  filter = filter_list
)

all.equal(res1, res2)

Les filtres sur un même champ doivent être combinés avec les opérateurs "$and", "$or", "$not" (voir les exemples fournis précédemment pour la fonction xtradata_requete_features).

Parametre group

Par défaut les opérations d'aggrégations sont réalisées en "group by time et gid", c'est à dire qu'on obtient au final autant d'objets unique par plage que d'id différents. Ce paramètre peut être modifié pour appliquer uniquement un "group by time".

res1 <- xtradata_requete_aggregate(
  typename = typename, key = key,
  rangeStart = date_deb,
  rangeEnd = date_fin,
  rangeStep = "hour",
  group = "time+gid",
  attributes = list("gid", "libres")
)


res2 <- xtradata_requete_aggregate(
  typename = typename, key = key,
  rangeStart = date_deb,
  rangeEnd = date_fin,
  rangeStep = "hour",
  group = "time",
  attributes = list("gid", "libres")
)

res1_grouped_by_time <- res1 %>%
  dplyr::group_by(time) %>%
  dplyr::summarise(libres = mean(libres, na.rm = TRUE))

all.equal(res1_grouped_by_time$libres, res2$libres)

ymansiaux/xtradata documentation built on July 21, 2022, 12:38 a.m.