Mit dem odsAutomationR kann direkt aus R heraus auf die Automation API von Opendatasoft zugegriffen werden. Voraussetzung dafür ist, dass die API freigeschalten ist. Die ausführliche Dokumentation der API schnittstelle findet sich hier.
Die Dvelopement Version des Packages kann wie folgt installiert und genutzt werden:
devtools::install_github("ogdtg/odsAutomationR")
library(odsAutomationR)Um Zugang zum jeweiligen ODS Portal zu bekommen und die Funktionalitäten der API nutzen zu können, muss zuerst api_type,domain, path und key initialisiert werden. Dazu können die entsprechnenden set Funktionen verwendet werden.
setKey("XXXXXXXXXXXXX") # API Key mit den entsprechenden berechtigungen
setDomain("data.tg.ch") # Domain der Datenplattform
setApiType("automation/v1.0") # Falls neue Versionen der API ersheinen, kann hier z.b. automation/v1.1 gesetzt werden
setPath("path/to/data_catalog.csv") # OPTIONAL: Ort, an dem Metadaten Katalog lokal gespeichert werden soll bei get_dataset_info
Um zu verhindern, dass diese Variablen jedes mal aufs neue gesetzt werden müssen, können diese mit usethis::edit_r_environ() ins globale R environment eingetragen werden. Nach dem ausführen der Funktion öffnet sich ebenjenes und man kann die Variablen in folgendem Schema eintragen:
ODS_DOMAIN=data.tg.ch
ODS_APITYPE=automation/v1.0
ODS_KEY=XXXXXXXXXXXXXX
ODS_PATH=path/to/data_catalog.csv
Um auf diese Variablen zugreifen zu können, muss R einmal neu gestartet werden. Danach werden die set Funktionen nur benötigt, wenn eine Änderung gewünscht ist.
Ein API Key kann direkt über die create_key Funktion erstellt werden. Hier können auch Keys erstellt werden, die nur benutzerdefinierte Berechtigungen besitzen. Dies kann nützlich sein, wenn man zum Beispiel einer Person aus einem Amt Zugang zur API geben möchte, ohne dieser direkt alle Berechtigungen zu erteilen.
Gibt man keine benutzerdefinierte Liste für das Argument permissions an, werden per default alle Berechtigungen erteilt.
EDIT: Opendatasoft erlaubt mittlerweile auch das Erstellen von API-Keys mit entsprechenden Berechtigungen im Webinterface. Dazu einfach oben rechts auf die Schaltfläche mit dem Benutzernamen klicken. Es öffnen sich die Kontoeinstellungen. Unter API-Keys können benutzerdeifinierte Keys mit entsprechenden Berechtigungen erstellt werden.
key <- create_key(
key_name="Name des Keys",
username="[email protected]",
password = "xxxxxxxxx",
domain = "data.tg.ch",
permissions = list(
"edit_dataset",
"publish_dataset"
)
)
Mit der Funktion get_dataset_info wird der aktuelle Metdata Katalog heruntergeladen. Dieser beinhaltet die Metadaten aller Datensätze, die sich derzeit auf dem Datenportal befinden. Hierzu zählen auch unveröffentlichte Datensätze sowie Datenkataloge. Die Funktion erzeugt automatisch eine Environment Variable metadata_catalog, die die Daten erhält. Die Funktion wird von mehreren anderen Funktionen verwendet, um sicher zugehen, dass der Katalog immer auf dem neuesten Stand ist. Ausserdem wird der Katalog jedes mal auf dem Lokalen Pfad, der bei path angegeben ist gespeichert.
Der Parameter path ist standardmässig auf einen lokalen Order des Kantons gesetzt, kann aber geändert werden.
get_dataset_info(path=path)
## creates variable "metadata_catalog" and saves it under path Mit der get_catalog können Metadaten von veröffentlichten Datensätzen bezogen werden. Veröffentlicht heisst in diesem Falle nicht, dass die Datensätze für alle User sichtbar und zugänglich sind, sondern lediglich, dass der "Veröffentlichen" Prozess ausgeführt wurde.
Ohne Argumente liefert die Funktion dataset_id, dataset_uid sowie title. Über das Argument variables können weitere Metadaten-Variablen in einem Vektor spezifiziert werden. Gibt man ausserdem die entsprechende dataset_uid mit, erhält man die Daten nur für den spezifizierten Datensatz.
Im Vergleich zur get_dataset_info Funktion ist diese Funktion wesentlich schneller und einfacher anpassbar, liefert allerdings keine Daten von unveröffentlichten Datensätzen. Die Funktion verwendet ausserdem nicht die Automation API sondern die Explore API.
# Alle Datensätze ohne weitere Variablen
get_catalog()
# Standardvariablen aller Datensätze plus publisher und keyword
get_catalog(variables = c("publisher","keyword"))
# Standardvariablen für da_xxxx plus publisher und keyword
get_catalog(dataset_uid = "da_xxxx",variables = c("publisher","keyword"))
Die (Metadaten-) Struktur eines Datensatzes auf ODS folgt immer dem gleichen JSON-Aufbau:
{
"dataset_id": "counties-united-states-of-america",
"is_restricted": true,
"metadata": {
"default": {},
"visualization": { },
"internal": {},
"custom_template_name": {}
},
"default_security": {
"is_data_visible": true,
"visible_fields": [],
"filter_query": "year!=2022",
"api_calls_quota": {}
}
}
Im metadata Teil entspricht jedes untergeordnete Element einem Metadaten Template. Das Template default enthält zum Beispiel folgende Metadaten:
"default": {
"title": {
"value": "Counties - United States of America",
"remote_value": "Counties - United States of America",
"override_remote_value": false
},
"description": {},
"keyword": {},
"modified": {},
"modified_updates_on_metadata_change": {},
"modified_updates_on_data_change": {},
"geographic_reference": {},
"geographic_reference_auto": {},
"language": {},
"timezone": {},
"publisher": {},
"references": {},
"attributions": {}Jedes Metadatenelement enthält dabei immer die Werte value, remote_value und override_remote_value. In der Regel ist für die Bearbeitung der Metadaten nur value relevant. Mehr Informationen hier.
Dieser JSON Aufbau liegt jedem die Metadaten betreffenden POST- und GET-Request zu Grunde.
Um die Metadaten eines einzelnen Datensatzes zu erhalten, kann die get_metadata Funktion verwendet werden. Die Funktion gibt die Möglichkeit die Metadaten als data.frame oder als list ausgeben zu lassen. Um eine nach der oben beschriebenen JSON-Struktur formatierte Liste der Metadaten zu erhalten, setzt man as_list=TRUE.Bei as_list=FALSE erhält man einen data.frame mit den Metadaten.
metas_list <- get_metadata(dataset_uid = "da_xxxxx", as_list=TRUE)
metas_df <- get_metadata(dataset_uid = "da_xxxxx", as_list=FALSE)
Um Datensätze zu erstellen und sie direkt mit den Metadaten aus dem Excel Schema zu befüllen kann die wrapper-Funktion add_metadata_from_scheme verwendet werden. Hierzu muss lediglich der Pfad zum ausgefüllten Schema als filepath angeggeben werden. Die Funktion gibt die dataset_uid des neu erstellten Datensatzes zurück
dataset_uid <- add_metadata_from_scheme(filepath="path/to/schema.xlsx")
Wenn zum Beispiel ein Datensatz basierend auf einem anderen Datensatz erstellt werden soll (minimale Veränderungen wie z.B. Titelanpassung), kann die create_dataset_from_df Funktion verwendet werden.
Der Parameter metadata_df entspricht von der Struktur dem Ergebnis von get_metadata("da_xxxxx",as_list = FALSE). Der Parameter id_part bezeichnet den Schlüssel Departement-Amt wie er auf data.tg.ch verwendet wird (z.B. "sk-stat"). Die laufende Nummer wird dann automatisch ergänzt.
# Metadaten herunterladen
metadata_df <- get_metadata("da_xxxxx",as_list = FALSE)
# Titel anpassen
metadata_df$value[which(metadata_df$name=="title")] <- "Neuer Titel"
# Neuen Datensatz erstellen
create_dataset_from_df(metadata_df = metadata_df, id_part = "sk-stat")Um bei einem bestehenden Datensatz einen einzelnen Metadaten-Eintrag zu ändern kann die set_metadata Funktion verwendet werden. Dazu benötigt man den Metadaten-Template-Namen template, den Namen des Metadaten-EIntrags meta_name sowie den einzutragenden Wert meta_value. Der Paramter meta_value muss ausserdem im richtigen Format angegeben werden (Liste oder einzelner Wert).
Es empfiehlt sich zuerst die get_metadata Funktion zu verwenden, um template und meta_name zu ermitteln.
# Titel ändern
set_metadata(
dataset_uid = "da_xxxxx",
template = "default",
meta_name = "title",
meta_value = "Neuer Titel"
)
# Zuschreibungen ändern
set_metadata(
dataset_uid = "da_xxxxx",
template = "default",
meta_name = "attributions",
meta_value = list("Zuschreibung1", "Zuschreibung2")
)
Bevor Daten zu einem Datensatz hinzugefügt werden können muss ein Datensatz über die Metadaten erstellt worden sein.
Bevor Daten hochgeladen werden sollte sichergestellt werden, dass diese in der richtigen Spezifikation abgespeichert sind.
Es empfiehlt sich Daten in R einzulesen und mit der write_ogd2 Funktion abzuspeichern. Neben dem datensatz und dem csv Pfad sollten dafür die Parameter na="" und fileEncoding="UTF-8 angegeben werden.
na="":NAwerden als leere Strings abgespeichert. nur so kann ODS diese verarbeitenfileEncoding = "UTF-8": Alle Files sollten im UTF-8 encoding abgespeichert werden.
df <- data.frame(a = runif(200), b = runif(200))
write_ogd2(data = df,
file = "path/to/file.csv",
na = "",
fileEncoding = "UTF-8")
Mit der update_resource() Funktion können sowohl bestehende Daten aktualisert oder aber neue Daten aufegschaltet werden.
Wenn keine resource_uid als Parameter mitgegeben wird, checkt die Funktion ob eine Resource für den Datensatz vorhanden ist. Wenn ja, wird diese aktualisiert, wenn nein wird eine neue Resource erstellt. Sollten mehrere CSV Ressourcen zu einem Datensatz gehören, dann wird die aktuellste aktualisiert (Fall sollte i.d.R. nicht auftreten)
Wird eine resource_uid mitgegeben, dann wird diese explizite Resource aktualisiert. Die resource_uid kann über get_dataset_resource() ermittelt werden.
Der Parameter encoding entspricht dem Encoding der hochzuladenden CSV resource (i.d.R. UTF-8).
update_resource(dataset_uid = "da_xxxxx",
filepath = "path/to/file.csv",
encoding = "UTF-8")
Zum Löschen von Resourcen kann die delete_resource() Funktion verwendet werden. Wenn keine resource_uid als Parameter mitgegeben wird, checkt die Funktion, ob eine Resource für den Datensatz vorhanden ist. Wenn ja, wird diese gelöscht. Sollten mehrere CSV Ressourcen zu einem Datensatz gehören, dann wird die aktuellste gelöscht (Fall sollte i.d.R. nicht auftreten).
delete_resource(dataset_uid = "da_xxxxx")
Zum Herunterladen von Resourcen kann die download_resource() Funktion verwendet werden. Wenn keine resource_uid als Parameter mitgegeben wird, checkt die Funktion, ob eine Resource für den Datensatz vorhanden ist. Wenn ja, wird diese heruntergeladen. Sollten mehrere CSV Ressourcen zu einem Datensatz gehören, dann wird die aktuellste heruntergeladen (Fall sollte i.d.R. nicht auftreten).
download_resource(dataset_uid = "da_xxxxx")
Die Variablen selbst heissen auf ODS Felder (fields). Ihnen kann eine Beschreibung, ein Datentyp eine EInehit usw. zugeordnet werden.
Sofern ein ausgefülltes Excel Schema voliegt, können die Felder mit der edit_fields Funktion bearbeitet werden. Hierbei werden Beschreibungen, Datentypen und (Zeit-) Einheiten zu den entsprechenden Variablen hinzugefügt. Ausserdem werden alle Felder sortierbar gemacht.
dataset_uid <- edit_fields(dataset_uid = "da_xxxxx",filepath="path/to/schema.xlsx")
Mögliche Einheiten sind text, int, double, geo_point_2d, geo_shape, date, datetime oder file.
add_description(dataset_uid = "da_xxxx",
field = "feld_name",
unit = "double")add_description(dataset_uid = "da_xxxx",
field = "feld_name",
description = "Beschreibung der Variable")
timeserie kann entweder year, month und daysein, wenn Datentyp date ist oder hour und minute wenn Datentyp datetime ist.
add_timeserie_precision(dataset_uid = "da_xxxxx", field = "field_name", timeserie = "day")
unit kann zum Beispiel CHF sein.
add_unit(dataset_uid = "da_xxxxx", field = "field_name", unit = "CHF")
Numerische Felder sind automatisch sortierbar.
make_field_sortable(dataset_uid = "da_xxxxx", field = "field_name")
publish_dataset("da_xxxxx")unpublish_dataset("da_xxxxx")Wenn der Parameter ask nicht explizit gleich FALSE gesetzt wird, fordert die Funktion den User auf die Löschung in der Konsole zu bestätigen. Wenn ask=FALSE wird die Löschung direkt durchgeführt.
delete_dataset("da_xxxxx", ask = FALSE)Mit change_visibility() kann bestimmt werden ob der Datensatz öffentlich sichtbar ist oder nur für eingeloggte User.
# Nur eingeloggte User
change_visibility("da_xxxxx", restrict = TRUE)
# Öffentlich sichtbar
change_visibility("da_xxxxx", restrict = FALSE)Gibt TRUE zurück, wenn Datensatz existiert.
check_dataset_exist("da_xxxxx")Datensatz wird kopiert und ein neuer Datensatz wird erstellt
#Dataset_UID des zu kopierenden Datensatz
copy_dataset("da_xxxxx")Als Anhang kann jede Art von File, unabhängig vom Filetyp verwendet werden.
get_dataset_attachments(dataset_uid = "da_xxxxx")# Einzelnes File als Anhang aufschalten
add_attachments(dataset_uid = "da_xxxxx", files = "path/to/file")
# Alle Files aus einem Ordner als Anhang aufschalten
add_attachments(dataset_uid = "da_xxxxx", directory = "path/to/directory")
# Bestehende Anhänge löschen und neue Anhänge aufschalten
update_attachments(dataset_uid = "da_xxxxx", directory = "path/to/directory")
# Anhänge löschen
delete_attachments(dataset_uid = "da_xxxxx")
Bevor ein neuer Datensatz erstellt werden kann, muss eine passende Kennung erzeugt werden. Diese setzt sich im Kanton Thurgau wie folgt zusmamen: departement-amt-laufende Numemer (z.B. sk-stat-1). ODS erlaubt es eine Kennung für mehrere Datensätze anzulegen, da intern automatisch eine eindeutige dataset_uid zugewiesen wird. Daher muss darauf geachtet werden, dass die Kennungen eindeutig sind, um Verwirrungen zu vermeiden. Die create_new_dataset_id gewährleistet eindeutige Kennungen, indem sie einer gegebenen Teilkennung die korrekte laufende Nummer zuweist.
dataset_id <- create_new_dataset_id(part_id = "sk-stat")
## returns "sk-stat-116" Wenn Datensätze zu einem früheren Zeitpunkt zurückgesetzt werden sollen, kann dies über die Datensatz Historie ermöglicht werden.
# Die letzten 20 Datensatzänderungen abfragen (mehr derzeit nicht möglich)
get_dataset_changes(dataset_uid = "da_xxxxx")
# Die letzte Änderung des Datensatz abfragen
get_latest_changes(dataset_uid = "da_xxxxx")Um die change_uid zu erhalten, können die im vorhergegangenen Funktionen verwendet werden
restore_change(dataset_uid = "da_xxxxx", change_uid = "ch_xxxxx")