Snelstartgids OData v4

Icoon computer

De OData API van het Centraal Bureau voor de Statistiek ontsluit de StatLine-datasets van het CBS in verschillende formaten die eenvoudig ingelezen kunnen worden in computerprogramma's. In deze snelstartgids wordt uitgelegd hoe de Wijken- en Buurtinfo uit 2017 (tabel 83765NED) ingeladen kan worden. Deze handleiding is bedoeld voor gebruikers van R of Python. Als voorkennis wordt verondersteld dat de gebruiker kan werken met functies en variabelen.

De codevoorbeelden kunnen eenvoudig naar het klembord worden gekopieerd door op de knop in het codeblok te klikken. De voorbeelden op deze pagina zijn ook gebundeld te vinden op GitHub.

De CBS OData API ontsluit data in JSON-formaat en om dit formaat te converteren naar een dataframe in R gebruiken we het package jsonlite. Voor het bewerken van de data gebruiken we tidyverse. Deze twee packages zijn te installeren met

install.packages("jsonlite")
install.packages("tidyverse")

In de onderstaande code wordt een functie get_odata gedefinieerd waarmee de data uit tabel 83765NED wordt opgehaald.

library(tidyverse)
library(jsonlite)

get_odata <- function(targetUrl) {
  data <- data.frame()
  
  while(!is.null(targetUrl)){
    response <- fromJSON(url(targetUrl))
    data <- bind_rows(data,response$value)
    targetUrl <- response[["@odata.nextLink"]]
  }
  return(data)
}

tableUrl <- "https://datasets.cbs.nl/odata/v1/CBS/83765NED"
targetUrl <- paste0(tableUrl,"/Observations")
data <- get_odata(targetUrl)
head(data)

Dit geeft het volgende resultaat:

  Id  Measure ValueAttribute    Value WijkenEnBuurten
1  0  T001036           None 17081507      NL00      
2  1     3000           None  8475102      NL00      
3  2     4000           None  8606405      NL00      
4  3    10680           None  2781768      NL00      
5  4    53050           None  2101648      NL00      
6  5    53310           None  4214276      NL00

Een antwoord van een data-verzoek bevat maximaal 100 000 cellen, dus om een grotere dataset te downloaden moeten er meerdere verzoeken aan de API worden gedaan. Wanneer een dataset automatisch wordt afgekapt na het maximale aantal cellen wordt de link naar het volgende deel van de dataset meegestuurd in de variabele @odata.nextLink. In de while-lus wordt het downloaden van 100 000 cellen herhaald door het volgen van @odata.nextLink tot alle informatie gedownload is.

De Measure-kolom bevat codes die horen bij gemeten variabelen en de kolom ValueAttribute geeft de status van een cijfer aan: wanneer een cijfer in een tabel mist wordt hier de reden beschreven. De kolom WijkenEnBuurten geeft de CBS-code voor een regio aan. 

In de volgende handleiding over metadata wordt uitgelegd hoe de codes bij Measure en WijkenEnBuurten gekoppeld kunnen worden aan omschrijvingen met codelijsten.

In de onderstaande code wordt een functie get_odata gedefinieerd waarmee de data uit tabel 83765NED wordt opgehaald. De CBS OData API ontsluit data in JSON-formaat, maar om databewerking eenvoudiger te maken converteren we dit naar een pandas-dataframe. 

import pandas as pd
import requests

def get_odata(target_url):
    data = pd.DataFrame()
    while target_url:
        r = requests.get(target_url).json()
        data = data.append(pd.DataFrame(r['value']))
        
        if '@odata.nextLink' in r:
            target_url = r['@odata.nextLink']
        else:
            target_url = None
            
    return data

table_url = "https://datasets.cbs.nl/odata/v1/CBS/83765NED"

target_url = table_url + "/Observations"
data = get_odata(target_url)
print(data.head())

Dit geeft het volgende resultaat:

     Id   Measure       Value ValueAttribute WijkenEnBuurten
0   0   T001036  17081507.0           None      NL00      
1   1      3000   8475102.0           None      NL00      
2   2      4000   8606405.0           None      NL00      
3   3     10680   2781768.0           None      NL00      
4   4     53050   2101648.0           None      NL00

Een antwoord van een data-verzoek bevat maximaal 100 000 cellen, dus om een grotere dataset te downloaden moeten er meerdere verzoeken aan de API worden gedaan. Wanneer een dataset automatisch wordt afgekapt na het maximale aantal cellen wordt de link naar het volgende deel van de dataset meegestuurd in de variabele @odata.nextLink. In de while-lus wordt het downloaden van 100 000 cellen herhaald door het volgen van @odata.nextLink tot alle informatie gedownload is.

De Measure-kolom bevat codes die horen bij gemeten variabelen en de kolom ValueAttribute geeft de status van een cijfer aan: wanneer een cijfer in een tabel mist wordt hier de reden beschreven. De kolom WijkenEnBuurten geeft de CBS-code voor een regio aan. 

In de volgende handleiding over metadata wordt uitgelegd hoe de codes bij Measure en WijkenEnBuurten gekoppeld kunnen worden aan omschrijvingen met codelijsten.