07_api.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# APIs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**API** steht für **Application Programming Interface**, auf Deutsch wörlich **\"Anwendungs­programmier­schnittstelle\"**.\n",
    "\n",
    "APIs im Allgemeinen finden sich in so ziemlich jeder Ecke der Software-Entwicklung, denn sie sind nötig, damit verschiedene Programme und Systeme miteinander verbunden werden und kommunizieren können.\n",
    "\n",
    "Für uns interessant sind aber hauptsächlich Web-APIs, also Anwendungsschnittstellen, die über das Internet genutzt werden. Speziell interessieren uns hier jene APIs, die auf Anfrage bestimmte Daten in Formaten wie CSV oder JSON kommunizieren.\n",
    "\n",
    "Für diese Übung wollen wir den Rhein-Pegel über eine API abrufen. Die API zu dieser Übung ist [hier](https://www.pegelonline.wsv.de/webservice/guideRestapi) dokumentiert. Da diese API die Daten im JSON-Format herausgibt, solltest du die Übung zum Thema JSON bereits gemacht haben.\n",
    "\n",
    "Der erste Schritt für uns ist, die Liste der Stationen im Rhein abzurufen. Dafür können wir die folgende URL benutzen:\n",
    "\n",
    "https://www.pegelonline.wsv.de/webservices/rest-api/v2/stations.json?waters=RHEIN\n",
    "\n",
    "Wir können die URL in drei Komponenten unterteilen, um sie ein bisschen besser zu verstehen.\n",
    "\n",
    "- `https://www.pegelonline.wsv.de/webservices/rest-api/v2/`\n",
    "  - Dies ist die **Basis-URL** aller Anfragen an diese API. Wir können verschiedene **Endpunkte** anhängen, um verschiedene Arten von Daten abzurufen.\n",
    "- `stations.json`\n",
    "  - Dies ist der sogenannte **Endpunkt**. Damit spezifieren wir, welche Kategorie von Daten wir abrufen wollen. In diesem Fall ist er sehr kurz, aber das muss nicht immer der Fall sein.\n",
    "- `?waters=RHEIN`\n",
    "  - Dieser Teil ist die Parameterliste. Hier übergeben wir nur ein Parameter, `waters`, mit dem Wert `RHEIN`. Wir teilen der API also mit, dass wir nur an Stationen in bestimmten Gewässern interessiert sind. Grundsätzlich gibt es kein Limit für die Anzahl von Parametern die an eine API übergeben werden können.  Gleichzeitig ist dieser Teil aber auch optional. Gibt es mehrere Parameter, so werden sie in der Regel mit einem `&` voneinander getrennt.\n",
    "\n",
    "Die Trennung von Endpunkt und Parametern ist nicht immer so eindeutig wie hier, aber es ist prinzipiell hilfreich, eine URL für eine API-Anfrage auf diese Bestandteile zu untersuchen, um den Abruf besser zu verstehen.\n",
    "\n",
    "Rufe die URL nun zunächst in deinem Browser auf. Du solltest eine Menge JSON auf deinem Bildschirm sehen. Das kann erstmal etwas überfordernd sein. Vielleicht erinnerst du dich daran, dass wir in der JSON-Übung eine ganz ähnliche Datenstruktur direkt in Pandas importieren konnten. Versuchen wir das hier doch auch mal, und gucken was passiert. Praktischerweise kann man einfach direkt die URL angeben und muss die Datei nicht extra vorher herunterladen - das macht es etwas einfacher für uns."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "df = pd.read_json('https://www.pegelonline.wsv.de/webservices/rest-api/v2/stations.json?waters=RHEIN')\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Wir können sehen, dass der Datenimport bis auf die `water`-Spalte ziemlich gut funktioniert hat. Glücklicherweise haben wir das Gewässer bereits beim Abruf spezifiziert, sodass wir uns darüber keine Sorgen machen müssen. \n",
    "\n",
    "Aus dieser Stationsliste können wir aber noch keinen Wasserstand auslesen. Dafür müssen wir auf die Daten einer bestimmten Station zugreifen. Es gibt eine Station in Köln, rufen wir doch für diese mal den aktuellen Wasserstand ab. Die Dokumentation erklärt uns, dass wir dafür eine URL wie die folgende nutzen können:\n",
    "\n",
    "https://www.pegelonline.wsv.de/webservices/rest-api/v2/stations/KÖLN/W/currentmeasurement.json\n",
    "\n",
    "Schau dir die Daten wieder zuerst in deinem Browser an.\n",
    "\n",
    "Wie du siehst, findet sich hier nur ein einzelnes Objekt, statt wie zuvor eine Liste von Objekten. Das ist einfacher zu lesen und verstehen, aber können wir das in Pandas einlesen?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "pd.read_json('https://www.pegelonline.wsv.de/webservices/rest-api/v2/stations/BONN/W/currentmeasurement.json')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Uff. Pandas gibt uns eine Fehlermeldung. Aber irgendwie wäre ein Dataframe ja auch gar nicht so richtig praktisch, um mit diesem Datensatz weiter zu arbeiten. Eine Tabelle mit nur einer Zeile? Dabei hat Python doch bereits einen Datentyp, der genau diese Form hat, nämlich das `dict`. Wir erinnern uns an `json.load` aus der JSON-Übung.\n",
    "\n",
    "Leider müssen wir uns jetzt um das Herunterladen der Daten selber kümmern. Dafür können wir zum Beispiel das populäre Paket `requests` nutzen."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import requests\n",
    "\n",
    "response = requests.get('https://www.pegelonline.wsv.de/webservices/rest-api/v2/stations/KÖLN/W/currentmeasurement.json')\n",
    "\n",
    "water_level = response.json()  # requests kann uns sogar direkt das JSON parsen!\n",
    "water_level"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Wenn Du noch eine Übung dazu machen möchtest, geht es hier lang:\n",
    "    \n",
    "**[>> 07b_api_exercises.ipynb](07b_api_exercises.ipynb)**"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}