DE:Taginfo/API
Taginfo verfügt über eine API, mit der du auf verschiedene Weise auf den Inhalt der Taginfo-Datenbanken zugreifen kannst. Die API wird intern für die Web-Benutzeroberfläche verwendet und kann auch von jedem verwendet werden, der Taginfo-Daten in seine Websites oder Anwendungen integrieren möchte.
Die API ist für die Nutzung durch die OpenStreetMap-Gemeinschaft bestimmt. Verwende sie nicht für andere Dienste. Wenn du unsicher bist, frage auf der Mailingliste (siehe unten).
Verwende immer einen sinnvollen User-Agent-Header(?) mit genügend Informationen, damit wir dich im Falle eines Problems kontaktieren können.
Der Server, auf dem die taginfo-API läuft, verfügt nicht über unbegrenzte Ressourcen. Bitte nutze die API verantwortungsvoll. Stelle keine riesigen Anfragen, um die gesamte Datenbank oder große Teile davon abzurufen, sondern verwende stattdessen die database downloads. Wenn du die API verwendest und feststellst, dass sie langsam ist, nutzt du sie wahrscheinlich übermäßig.
Wenn du die Taginfo-API verwendest, solltet du der taginfo-dev Mailingliste beitreten. Dort werden Aktualisierungen der API bekannt gegeben, und dort kannst du auch deine Fragen stellen.
Paginierung
Viele API-Aufrufe geben ihre Daten „seitenweise“ zurück. Das bedeutet, dass Sie beispielsweise mit einer Anfrage die ersten 20 Ergebnisse abrufen können, dann die nächsten 20 und so weiter. Sie können festlegen, wie viele Ergebnisse Sie erhalten möchten und welche „Seite“ Sie abrufen, oder Sie können einfach alle Ergebnisse auf einmal abrufen.
Wenn Sie eine Paginierung wünschen, fügen Sie die Parameter page und rp (Ergebnisse pro Seite) zur URL hinzu. Die erste Seite hat die Nummer 1. Die URL sieht dann folgendermaßen aus:
https://taginfo.openstreetmap.org/api/VERSION/some/thing?rp=20&page=1&foo=bar
Das Ergebnis des API-Aufrufs sieht folgendermaßen aus:
{
"total": 587, // die Gesamtanzahl der Ergebnisse
"page": 7, // die Seitenzahl (entspricht der in der Anfrage angegebenen Zahl)
"rp": 20, // die Anzahl der Ergebnisse pro Seite (entspricht der in der Anfrage angegebenen Zahl)
"url": "https://taginfo.openstreetmap.org/api..." // die vollständige URL, mit der dieses Ergebnis abgerufen wurde
"data": [...] // die Daten
}
Das data-Array enthält die tatsächlichen Ergebnisse, von Eintrag rp * (page-1) bis rp * page - 1.
Falls Sie keine Paginierung wünschen, lassen Sie die Parameter page und rp weg. In diesem Fall sind diese Felder im Ergebnis 0.
Sortierung
Viele API-Aufrufe unterstützen die Sortierung der Ergebnisse. Um eine andere Sortierung als die Standard-Sortierung zu erhalten, können Sie die Parameter sortname und sortorder zur URL hinzufügen. Jeder API-Aufruf hat unterschiedliche Optionen für sortname. Die Sortierreihenfolge kann entweder asc für aufsteigend oder desc für absteigend sein.
Filter
Einige API-Aufrufe verfügen über einen speziellen filter-Parameter, mit dem Sie die Ergebnisse filtern können. Sie können mehrere Filter wie folgt verwenden: filter=FILTER1,FILTER2.
Weitere Informationen zu den verfügbaren Filtern finden Sie in der API-Dokumentation und den dort beschriebenen "Filter"-Optionen.
Beispielcode
Das einfache tapi-Tool (https://github.com/joto/taginfo/blob/master/examples/tapi) kann verwendet werden, um API-Anfragen zu erstellen und könnte Ihnen beim Entwickeln Ihres eigenen API-Zugangscodes helfen.
API-Aufrufe
Generell gibt es für jede Tabelle in der Web-Benutzeroberfläche einen API-Aufruf (das liegt daran, dass diese Tabellen aus den API-Aufrufen befüllt werden). Manchmal geben die API-Aufrufe mehr Datenfelder zurück, als in der Benutzeroberfläche angezeigt werden.
Eine Liste der API-Aufrufe finden Sie unter https://taginfo.openstreetmap.org/taginfo/apidoc.
XSS-Probleme
Bitte beachten Sie, dass OSM-Tag-Schlüssel und -Werte beliebige gültige UTF-8-Zeichen enthalten können, ebenso wie Wiki-Seiten. Wenn Sie die Taginfo-API verwenden, besteht immer die Möglichkeit, dass sie Daten mit Sonderzeichen zurückgibt. Stellen Sie sicher, dass Ihre Anwendung diese Zeichen korrekt verarbeitet.
Schön formatiertes JSON
Sie können den Parameter format=json_pretty hinzufügen, um die JSON-Ausgabe schön formatiert mit Leerzeichen und Zeilenumbrüchen zu erhalten. Der Standard ist, das JSON so kompakt wie möglich zu packen.
CSV
Einige API-Aufrufe können auch CSV generieren. Verwenden Sie format=csv, um dies zu aktivieren.
CORS und JSONP
Taginfo unterstützt Cross-Origin Resource Sharing (CORS), indem der Header Access-Control-Allow-Origin: * auf allen API-Aufruf-Ergebnissen gesetzt wird. Dies ist die bevorzugte Methode, um die Taginfo-API von anderen Webseiten aus zu nutzen.
Taginfo unterstützt auch die ältere JSONP-Technik. Sie können den Parameter callback zu jedem API-Aufruf hinzufügen, der JSON zurückgibt, und es wird das Ergebnis innerhalb eines Funktionsaufrufs des callback-Parameters zurückgegeben.
Beispiel: ...&callback=foo
wird foo(...ein JSON...) zurückgeben.
Die Verwendung von JSONP ist veraltet und wird in Zukunft entfernt.