Verbinden met een API met Python [Tutorial in requests package]

Met een API kun je gemakkelijk en gestructureerd data ontvangen en versturen. In veel data science vraagstukken heb je een voordeel als je weet hoe je met APIs kunt werken. Verbinden met een API in Python is daarom een essentiële vaardigheid voor iedere data scientist.

We behandelen de volgende onderwerpen:

• Wat is een API?
• Wat is het requests package?
• Welke soorten requests zijn er?
• Wat zijn status codes en welke zijn er?
• Wat is JSON en hoe werk ik hiermee?

Wat is een API?

API is een afkorting voor Application Programming Interface. Zoals je wellicht al begrijpt uit de naam biedt een API een interface om data uit te wisselen voor een bepaalde applicatie. Je kunt door middel van bijvoorbeeld Python code data ontvangen en versturen op een gestandaardiseerde, gestructureerde, en snelle manier.

Veelal gebruik je APIs om d.m.v. een GET request data te verkrijgen. Onderstaande afbeelding laat zien hoe je via een API zowel data als een response code terugkrijgt. Later meer over zowel de response data als response code.

APIs zijn bijvoorbeeld handig omdat:

• Als data snel wijzigt blijven jouw analyses steeds actuele informatie gebruiken
• Je kunt veel sneller en gestructureerder werken
• Veel organisaties maken gebruik van APIs van andere organisaties en betalen daar voor. Zo kan Uber bijvoorbeeld gebruik maken van de Google Maps API om ritten te plannen. Hierdoor kun je makkelijker innovatieve/ complexe diensten opzetten.

Je kunt vanuit verschillende programmeertalen werken met APIs. Vaak installeert de programmeur een package voor de betreffende taal die het werken met APIs gemakkelijker maakt. Binnen Python gebruik je over het algemeen het requests package.

Wat is het requests package en hoe verbind ik met een API?

Het requests package is het meestgebruikte package binnen Python om HTTP requests uit te voeren (zoals bovenstaande 'GET' request). Je hebt het package dus nodig als je data via een API wilt ophalen of versturen.

Omdat requests geen standaard onderdeel is van Python zul je het eerst moeten installeren. Dit doe je door onderstaand commando in de command line terminal van jouw keuze in te geven:

python -m pip install requests

Als je Conda gebruikt dan kun je onderstaand commando gebruiken:

conda install requests

In onderstaand voorbeeld zie je hoe we na installatie het package requests importeren en deze openbare dataset van het CBS ophalen met een 'GET' request. Het betreft een dataset waarin de gegevens over de levensverwachting van Nederlanders zijn bijgehouden. De response data tonen we in tekstformaat en limiteren de output tot de eerste duizend tekens.

import requests

response = requests.get('https://opendata.cbs.nl/ODataApi/OData/71950ned/TypedDataSet')

response.text[:1000]

'{\r\n  "odata.metadata":"https://opendata.cbs.nl/ODataApi/OData/71950ned/$metadata#Cbs.OData.WebAPI.TypedDataSet","value":[\r\n    {\r\n      "ID":0,"Geslacht":"T001038","LeeftijdOp31December":"10010","Marges":"MW00000","Perioden":"1981JJ00","Levensverwachting_1":null,"LVInAlsGoedErvarenGezondheid_2":null,"LVZonderMatigeEnErnstigeBeperking_3":null,"LVZonderErnstigeBeperkingen_4":null,"LVZonderLichteMatigeErnstigeBep_5":null,"LVZonderChronischeZiektes_6":null,"LVZonderChrZiekExclHogeBloeddruk_7":null,"LVInGoedeGeestelijkeGezondheid_8":null,"LVZonderGALIBeperkingen_9":null,"LVZonderErnstigeGALIBeperkingen_10":null\r\n    },{\r\n      "ID":1,"Geslacht":"T001038","LeeftijdOp31December":"10010","Marges":"MW00000","Perioden":"1982JJ00","Levensverwachting_1":null,"LVInAlsGoedErvarenGezondheid_2":null,"LVZonderMatigeEnErnstigeBeperking_3":null,"LVZonderErnstigeBeperkingen_4":null,"LVZonderLichteMatigeErnstigeBep_5":null,"LVZonderChronischeZiektes_6":null,"LVZonderChrZiekExclHogeBloeddruk_7":null,"LVInGo'

Hier vind je de documentatie van het requests package

Welke soorten requests zijn er als je met een API verbindt?

Met het requests package kun je in jouw Python scripts HTTP requests opnemen. Zo kun je bijvoorbeeld:

• Met een GET requests informatie opvragen via een API. Omdat het een HTTP request is en het internet ook op deze manier werkt kun je de inhoud van vrijwel iedere webpagina op deze manier opvragen. Soms dwingt een API je om data in batches op te vragen.
• Met een POST request kun je gegevens naar een server toe sturen. Zo kun je wijzigingen maken in een database en dit wordt niet altijd toegestaan.
• Met een PUT request kun je bestaande informatie wijzigen. Zo kun je bijvoorbeeld je voorraad automatisch bijwerken als er producten via een bepaald saleskanaal zijn verkocht.
• Met een DELETE request verwijder je gegevens.

In bovenstaand voorbeeld hebben we gezien hoe we een GET request kunnen gebruiken om data via de CBS API op te halen.

Wat zijn status codes en welke zijn er?

Als je een request stuurt naar een webserver dan wordt er altijd een status code teruggegeven (zie eerdere afbeelding). Als je met Python verbindt met een API gebeurt dit dus ook. De status code vertelt je de reactie van de server op jouw requests. Voorbeelden zijn:

• 200: alles is goed gegaan en het resultaat is opgehaald;
• 400: je hebt een verkeerd request ingestuurd en de server heeft niets opgehaald;
• 401: je hebt geen toegang tot de data die je hebt opgevraagd.

Er zijn veel verschillende status codes die je hier kunt vinden in een overzicht.

Kort gezegd hoop je altijd direct op een status code die begint met een 2 omdat dat succes betekent. Als je code start met een 4 of een 5 dan is er meestal nog wat werk aan de winkel. Een response heeft ook het attribute "response.ok" dat True of False retourneert. Dit is ook een snelle manier om te kijken of de response juist is opgehaald.

Als je een status code terugkrijgt die je niet kent maakt dat niet uit. Door een status code in Google in te geven kom je er makkelijk achter wat er fout gaat.

print(response.status_code)

200

Wat is JSON en hoe werk ik hiermee?

JSON is een programmeertaal en staat voor JavaScript Object Notation. Bijna alle APIs en dus applicaties praten in JSON taal met elkaar zodat ze elkaar makkelijk verstaan. Het is binnen Python gemakkelijk om met JSON te werken omdat Python standaard een ingebouwde JSON module heeft om met deze taal om te gaan.

import json
json.loads(response.text)

Via bovenstaande code kun je de GET response in overzichtelijk en leesbaar JSON format verkrijgen.

Voor data analyses is het echter veelal handig om de data in een DataFrame te verkrijgen. In onderstaand voorbeeld zie je hoe je de data kunt omzetten naar een DataFrame in Pandas. We maken in onderstaand voorbeeld tevens gebruik van de methode .json() waardoor de response in één keer naar JSON omgezet wordt.

import pandas as pd

data = response.json()
df_life_expect = pd.DataFrame.from_dict(data['value'])

df_life_expect

En als je eenmaal de data in een DataFrame hebt dan kun je er natuurlijk van alles mee. Zoals in dit geval bijvoorbeeld het plotten van de levensverwachting over tijd voor mannen en vrouwen in Nederland.

In [5]:

import requests
import pandas as pd
from matplotlib import pyplot as plt
%matplotlib inline

response = requests.get('https://opendata.cbs.nl/ODataApi/OData/71950ned/TypedDataSet')
data = response.json()

df = pd.DataFrame.from_dict(data['value'])
df['Year'] = df['Perioden'].str[:4]
df = df[df['LeeftijdOp31December']=='10010']

BACKGROUNDCOLOR = '#F9F9F9'
GENDERS = {
    'Male': '3000   ',
    'Female': '4000   '
}

fig, ax = plt.subplots(figsize=(15,6))
for gender, gender_id in GENDERS.items():
    df_life_expect_gender = df[df['Geslacht'] == gender_id]
    df_life_expect_gender.plot(kind='line', x='Year', y='Levensverwachting_1', ax=ax, label=gender);

ax.set_xlabel('Year');
ax.set_ylabel('Age');
ax.set_title('Historical Life Expectancy by Gender');
ax.grid(axis='both');

ax.set_facecolor(BACKGROUNDCOLOR);
for spine in ax.spines:
    ax.spines[spine].set_color(BACKGROUNDCOLOR);

Conclusie over verbinden met APIs in Python

Het is met Python mogelijk om te verbinden met APIs. Dit doe je met het requests package. Als je een request stuurt naar een server dan krijg je altijd een status code terug en als het request goed is gegaan ook response data.

Deze response data is meestal in JSON formaat. Je kunt binnen Python met JSON overweg met de ingebouwde JSON module, maar je kunt de data ook omzetten naar een DataFrame zodat je de gegevens gemakkelijk kunt analyseren.

Wil je nog veel meer leren over met mogelijkheden met Python voor Data Science? Schrijf je dan in voor onze Python cursus voor data science, onze machine learning training, of voor onze data science opleiding en leer met vertrouwen te programmeren en analyseren in Python. Nadat je een van onze trainingen hebt gevolgd kun je zelfstandig verder aan de slag. Je kunt ook altijd even contact opnemen als je een vraag hebt.

Download één van onze opleidingsbrochures voor meer informatie