10_api_exercises.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Hier kommen weitere hilfreiche Infos zum Umgang mit APIs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## URL Encoding\n",
    "Manchmal möchte man Zeichen in URLs unterbringen, die problematisch sein können - entweder, weil sie schon ihre eigene Bedeutung in URLs zugeordnet haben, wie zum Beispiel `/`, `?`, weil sie nicht im ASCII-Zeichensatz enthalten sind, oder weil sie aus anderen Gründen unzulässig sind (z. B. Leerzeichen). Dazu gehören auch immer Umlaute.\n",
    "\n",
    "Um diese Zeichen trotzdem übertragen zu können, wird in der Regel das sogenannte Prozent-Encoding verwendet. Die `requests`-Bibliothek macht das in der Regel automatisch für dich, Pandas jedoch nicht. Wenn du auf einen solchen Fehler triffst, kannst du die Funktion Quote verwenden. Die übersetzt Strings, die man ihr gibt in Prozent-Encoding."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import requests"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from urllib.parse import quote\n",
    "\n",
    "quote('KÖLN')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Den übersetzten String kannst du dann rauskopieren und in der URL verwenden. \n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Übung"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Wenn du dein Verständnis prüfen willst, versuche doch mal, den aktuellen Wasserstand eines anderen Flusses von der API abzurufen."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Übung"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Wenn du eine Herausvorderung suchst, kannst du versuchen, eine Zeitreihe einer Station deiner Wahl mit Pandas abzurufen und zu plotten: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Parameter mit Requests\n",
    "Wenn man mit APIs arbeitet, will man oft verschieden Kombinationen von Parametern ausprobieren oder vielleicht sogar programmatisch die Werte der Parameter zuweisen können. Um das einfacher zu machen, hier ein kleiner Trick:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import requests\n",
    "\n",
    "# Parameter können vorher als 'dict' angelegt werden\n",
    "parameters = {\n",
    "    'foo': 'bar',\n",
    "    'flavor': 'vanilla',\n",
    "}\n",
    "\n",
    "# httpbin.org ist ein Test-Service für Web-Anfragen\n",
    "# Er antwortet mit Informationen über die Anfrage, z. B. die URL\n",
    "response = requests.get('https://httpbin.org/get', params=parameters).json()\n",
    "print('Resultierende URL:', response['url'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Wir sehen: Parameter werden korrekt mit `?` und `&` an die URL angehängt."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Übung"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Du kannst auch mal eine der folgenden APIs zu erkunden: https://github.com/public-apis/public-apis"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Datenstrukturen in Python"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Nicht immer können oder wollen wir Pandas nutzen, um mit unseren Daten zu arbeiten. Hier wollen wir ein paar Möglichkeiten kennenlernen, um mit Datenstrukturen wie `dict` und `list` in Python umzugehen. Wenn du eine JSON-API erforschen willst, kann dir diese Sektion dabei helfen.\n",
    "\n",
    "Listen und Dictionaries sind die beiden häufigsten Wege, mehrere Werte in einer Sammlung zusammenzufassen. Daher gibt es auch viele Möglichkeiten, sie zu verarbeiten und auf die Werte, die sich darin befinden, zuzugreifen. Genau so kann man neue Listen und Dictionaries auf vielen Wegen erzeugen und mit Werten befüllen. Wir wollen uns hier aber hauptsächlich auf das Auslesen konzentrieren.\n",
    "\n",
    "Beginnen wir mit ein paar Dingen, die wir mit Listen tun können:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "words = [\n",
    "    \"eine\",\n",
    "    \"liste\",\n",
    "    \"fantastischer\",\n",
    "    \"wörtern\",\n",
    "    \"zum\",\n",
    "    \"testen\"\n",
    "]\n",
    "\n",
    "numbers = [\n",
    "    3,\n",
    "    -14,\n",
    "    800,\n",
    "    44,\n",
    "]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Die 'len'-Funktion gibt die Größe von Sammlungen wie list und dict zurück\n",
    "print(\"Anzahl der Wörter:\", len(words))\n",
    "\n",
    "# Übrigens: Auch die Länge von Strings können wir damit herausfinden\n",
    "print(\"Länge des Worts 'Wort':\", len(\"Wort\"))\n",
    "\n",
    "# Um einen bestimmten Eintrag aus einer Liste abzurufen, werden wie bei dict eckige Klammern benutzt\n",
    "# Computer fangen immer bei 0 an zu zählen!\n",
    "print(\"Das erste Wort:\", words[0])\n",
    "\n",
    "# Wir können auch anders herum\n",
    "print(\"Das letzte Wort:\", words[-1])\n",
    "\n",
    "# Mit 'sum' können wir eine Liste von Zahlen summieren\n",
    "print(\"Summe der Zahlen:\", sum(numbers))\n",
    "\n",
    "# Was ist die kleinste/größte Zahl? 'min' und 'max' geben Auskunft\n",
    "print(\"Kleinste Zahl:\", min(numbers))\n",
    "\n",
    "# Pro-Tip: Wir können 'min' und 'max' auch eine Funktion geben, die es für die Kalkulation benutzen soll\n",
    "# Die Funktion wird auf jeden Wert in der Liste angewandt und das Ergebnis für den Vergleich benutzt\n",
    "print(\"Letztes Wort nach Alphabet sortiert:\", max(words))\n",
    "print(\"Längstes Wort:\", max(words, key=len))\n",
    "\n",
    "# Das gleiche funktioniert übrigens auch mit 'sorted', was zum sortieren von Listen genutzt wird\n",
    "print(sorted(words))\n",
    "print(sorted(words, key=len))\n",
    "\n",
    "# Wir können auch unsere eigenen Funktionen übergeben\n",
    "\n",
    "def distance_from_10(number):\n",
    "    return abs(10 - number)  # 'abs' berechnet den Betrag einer Zahl\n",
    "\n",
    "print(\"Zahl am nächsten zu 10:\", min(numbers, key=distance_from_10))\n",
    "\n",
    "# Spiele gerne ein bisschen mit diesen Funktionen herum. Du kannst dir eigene Listen anlegen."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Puh. Das ist schon ziemlich kompliziert... Wenn du nicht alles im Detail verstanden hast, ist das nicht so schlimm. \n",
    "\n",
    "Wichtig ist: \n",
    "- Wir können diese Funktionen nutzen, um aus Listen Informationen zu ziehen\n",
    "- Wir können Funktionen als Parameter an diese (und andere) Funktionen übergeben, um deren Verhalten zu modifizieren\n",
    "\n",
    "Bevor wir mehr daraus machen, sollten wir uns noch ein bisschen mit der Navigation durch verschachtelte Strukturen bekannt machen.\n",
    "\n",
    "Betrachten wir die Station in Bonn mal etwas genauer. Die API-Dokumentation sagt, dass wir einige Informationen zu der Station mit abrufen können, wenn wir entsprechende Parameter mit angeben:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import requests\n",
    "import json\n",
    "\n",
    "url = 'https://www.pegelonline.wsv.de/webservices/rest-api/v2/stations/BONN.json'\n",
    "\n",
    "parameters = {\n",
    "    'includeTimeseries': 'true',\n",
    "    'includeCurrentMeasurement': 'true',\n",
    "}\n",
    "\n",
    "bonn = requests.get(url, params=parameters).json()\n",
    "\n",
    "# Kleiner Trick, um die Ausgabe von komplexen dicts etwas lesbarer zu machen\n",
    "print(json.dumps(bonn, indent=4, ensure_ascii=False))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Angenommen uns interessiert der aktuelle Wasserstand. Wie kommen wir da überhaupt ran?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "timeseries = bonn['timeseries']  # Zugriff auf das 'bonn'-dict Anhand des Schlüssels\n",
    "water_level = timeseries[0]  # 'timeseries' ist eine Liste, daher rufen wir Werte per Index ab\n",
    "current_measurement = water_level['currentMeasurement']  # Der erste Eintrag aus der timeseries ist wieder ein dict\n",
    "value = current_measurement['value']  # Und schließlich haben wir den Wert, den wir suchen\n",
    "\n",
    "print(\"Wasserstand:\", value)\n",
    "\n",
    "# Das ganze geht auch in einer Zeile\n",
    "print(\"Wasserstand:\", bonn['timeseries'][0]['currentMeasurement']['value'])\n",
    "\n",
    "# Übung: Finde die Abflussrate und Null-Stand auf ähnlichem Wege heraus"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Übung"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Wir haben jetzt bereits die Werkzeuge in der Hand, um die Rhein-Station mit dem höchsten und niedrigsten aktuell gemessenen Wasserstand herauszufinden!\n",
    "\n",
    "Der Abruf https://www.pegelonline.wsv.de/webservices/rest-api/v2/stations.json?waters=RHEIN&includeTimeseries=true&includeCurrentMeasurement=true enhält eine Liste aller Stationen im Format des letzten Beispiels."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Tapfer, dass du bis hierhin durchgehalten hast.\n",
    "\n",
    "Als Zugabe kannst du dir noch angucken, wie du mit Python eine interaktive Choroplethen-Karte baust\n",
    "\n",
    "**[ >> Folium Notebook](08_map_datenguide_folium.ipynb)**"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.6.9 64-bit",
   "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"
  },
  "vscode": {
   "interpreter": {
    "hash": "31f2aee4e71d21fbe5cf8b01ff0e069b9275f58929596ceb00d14d90e3e16cd6"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}