DE:Overpass API
Servers status · Versions · Development · Technical design · Installation · XAPI compatibility layer · Public transport sketch lines · Anwendungen · Source code and issuesOverpass turbo · Wizard · Overpass turbo shortcuts · MapCSS stylesheets · Export to GeoJSON · mehr (Deutsch) · Development · Source code and issues · Web siteOverpass Ultra · Examples · Overpass Ultra extensions · MapLibre stylesheets · URL Params · mehr (Deutsch) · Source code and issues · Web site
| Overpass API | |
|---|---|
 | |
| Autor: | drolbr/Overpass-API/graphs/contributors GitHub |
| Webseite: | overpass-api.de |
| Quellcode: | drolbr/Overpass-API GitHub |
|
Datenbank-Engine zur selektiven Abfrage von Daten aus der OSM-Hauptdatenbank | |
Bitte hilf, diese Seite ins Deutsche zu übersetzen. Wenn jeder, der hier liest und auf der englischen Seite weiter liest, nur einen Absatz übersetzt, dann ist diese Seite bald fertig. Danke!
Es fehlen noch folgende Kapitel: (Stand: Weihnachten 2018)
- Overpass_API#Public_Overpass_API_instances
Overpass_API#Developers_/_System_AdministratorsOverpass_API#Resource_management_options_.28osm-script.29Overpass_API#Advanced_usage_examples- Overpass_API#Recurse examples
- Overpass_API#Around
- Overpass_API#Building_blocks
Overpass_API#Meta_data- Overpass_API#Public_transport_example
- Overpass_API#XAPI_Compatibility_Layer
- Overpass_API#Programs.2FScripts_around_Overpass
- Overpass_API#Talks.2C_Presentations.2C_Workshops
- Overpass_API#Books
Wenn Du ein Kapitel vollständig übersetzt hast, bitte hier oben durchstreichen, und wenn Du magst Deinen Namen dahinter schreiben.
Einführung
Die Overpass API (ehemals OSM3S) dient zum selektiven Download von Daten aus der Hauptdatenbank von OSM. Im Fachjargon spricht man von einer Read-Only API. Sie wird von Roland Olbricht (mail: roland.olbricht@gmx.de) entwickelt und betreut. Overpass API wurde auch mit dem Ziel geschrieben, deren Benutzung und auch die dieser Dokumentation möglichst niedrigschwellig zu erlauben. Daher freut sich Roland über jegliche Kommentare hierzu. Ferner bittet er darum, Links zu Anwendungen von Overpass zu übersenden, so dass er möglichen Optimierungsbedarf erkennen kann. Ein niedrigschwelliger Podcast zum Einstieg in Overpass API findet sich bei Radio OSM.
Während die Haupt- (Main-) API hauptsächlich auf das Herunter- und Hochladen beim Editieren der OSM Karte optimiert wurde, konzentriert sich Overpass API auf ein selektives Herunterladen gemäß Benutzerwunsch aus dem Angebot von mehreren Milliarden OSM-Objekten. Beispielsweise könnte Eltern von Kleinkindern nach allen Spielplätzen in Wuppertal oder eine Feuerwehr nach allen Hydranten im Ort suchen. Genauer kann man nach allem suchen, was man als Mapper bei OSM an Informationen hochladen kann, wie Keys, Tags, Objekttypen, und dabei mehrere kombinieren. Dabei wurde Wert darauf gelegt, dass die Abfragen ähnlich aussehen wie die beim Editieren eingetragenen Keys und Tags. Beispielsweise enthält die Abfrage nach Spielplätzen das dem Mapper bekannte "leisure=playground". Darüber hinaus lassen sich beispielsweise auch Umkreissuchen durchführen. Im Endziel sollte man mit kaum mehr als JOSM-Mapping-Kenntnissen in die Lage versetzt werden, auch eine solche Abfrage durchführen zu können. So steht denn auch für eine Abfrage aus JOSM heraus ein PlugIn zur Verfügung. Werden solche Abfragen aus Anwendungen heraus automatisiert gestellt, können damit beispielsweise Spezialkarten erzeugt sowie Navigationssysteme und Analysewerkzeuge gefüttert werden.
Eine dieser Anwendungen ist der Linienbandgenerator, den man aus ÖPNV-Fahrplänen kennt. Er extrahiert das Linienband per Overpass API direkt aus den OSM-Daten. Eine niedrigschwellige Bedienoberfläche findet sich hier. Schneller lässt sich beispielsweise das Band der Buslinie 625 im Verkehrsverbund VRR durch folgenden Aufruf in der Adresszeile des Browsers erzeugen:
- http://overpass-api.de/api/sketch-line?network=VRR&ref=625 in die Adresszeile des Browsers eingetippt und abgeschickt ergibt Klick hier.
Hier bekommt man einen ersten Eindruck davon, wie die Overpass API funktioniert: Sie sucht hier nach allen Objekten, die von den Mappern mit network=VRR sowie gleichzeitig (ausgedrückt durch &) mit ref=625 getaggt wurden - und findet nur eine Linie. Jeder JOSM-erfahrene Mapper kann nun im obigem Ausdruck die fett gedruckten Werte ersetzen und findet somit jede beliebige in OSM vorhandene Linie.
Overpass API besitzt eine eigene leistungsfähige Abfragesprache (query language) namens Overpass QL. Eine Einführung anhand von Beispielen findet sich hier: language guide; eine Referenz der vorhandenen Kommandos ist: language reference. Einige der Aufgaben, die Overpass API heute erledigt, wurden zuvor von XAPI bereitgestellt. Da Overpass API diese Abfragen mit höherer Geschwindigkeit erledigt und zudem stabiler läuft, übernimmt sie diese Aufgaben zunehmend. Damit auf XAPI beruhende Anwendungen nicht für Overpass API neu geschrieben werden müssen, bietet sie volle Kompatibilität. Das erlaubt eine leichte Umstellung durch einfaches Ändern der URL.
Overpass API eliminiert zudem ein Problem, das unter anderem auch in diesem Wiki existiert. Wenn ein OSM-Objekt durch die Angabe seiner ID hier verlinkt wird, dann funktioniert dieser Link nicht mehr, wenn das entsprechende Objekt eine neue ID bekommen hat. Dies geschieht beispielsweise, wenn es in OSM gelöscht und neu eingetragen wurde. Dazu kennt Overpass API das Konzept der permanenten Links. So kann man in diesem Wiki die Autobahn 555 aufrufen, ohne deren ID zu kennen bzw. zu nennen:
- Aufruf der Autobahn 555 mit der ID: {{Relation|23092}} ergibt die Darstellung: 23092
23092 - Aufruf der Autobahn 555 über Overpass API: {{DisplayRoute|network=BAB|ref=A 555}} ergibt die Darstellung: OSM
Overpass API wird derzeit auf zwei Servern im Internet außerhalb von osm.org angeboten. Zwei dieser Server werden von Roland selbst betreut:
- http://overpass.osm.rambler.ru/ mit query base address http://overpass.osm.rambler.ru/cgi/ (8 Kerne, 64 GB RAM).
- http://overpass-api.de/ mit query base address http://overpass-api.de/api/ (4 Kerne, 64 GB RAM). Dieser Server wird vom FOSSGIS e.V. betrieben – der Vertretung der deutschen OSM Community.
Jeder der beiden Server hat eine Tageskapazität von 1.000.000 Anfragen. Man kann davon ausgehen, dass bis zu 10.000 Anfragen oder das Äquivalent von 10 GB Download pro Tag und User andere Benutzer nicht einschränkt.
Der dritte Server wurde von der französischen OSM Community betrieben. Siehe Servers/overpass.openstreetmap.fr.
Anfragen (Queries) an Overpass API können in deren eigener Sprache oder in XML gestellt werden. Siehe hierzu die Beispiele weiter unten. (Anmerkung: Der verlinkte Teil wurde noch nicht übersetzt. Siehe daher in der englischen Version dieses Artikels.)
Man kann eine eigene Instanz von Overpass API installieren: Letzte stabile Version oder the git source code repository. Das Ganze ist unter Affero GPL v3 lizenziert. Mithilfe beim Source Code ist sehr willkommen.
Die Sammlung von Beispielen bietet Einsteigern Hilfe.
Eine Präsentation zu einem Vortrag im Sept. 2014 findet sich unter http://overpass-api.de/misc/overpass_bonn_2014.pdf
Community: wo bekomme ich Hilfe?
Es gibt einige Community-Webseiten, wo man Hilfe bekommt, wenn man Fragen zur Overpass API oder zu overpass turbo hat. Diese sind die empfohlenen Seiten für Anfänger- bis zu Expertenfragen. Oder allgemeiner formuliert: wenn die Antwort auf die Frage nützlich für die Allgemeinheit sein könnte.
| Seite | Sprache | häufog benutzes 'tag' für Fragen |
|---|---|---|
| Help OSM | Englisch | overpass, overpass-turbo |
| GIS StackExchange | Englisch | overpass-api |
| Stack Overflow | Englisch | overpass-api |
| OpenStreetMap Forum | mehrsprachig |
Entwickler/Systemadministratoren
Sie können Ihre eigene Instanz aus dem neuesten stabilen Release oder aus den Quellen (aktuelle Version) bei Github installieren. Die Overpass API ist unter der Affero GPL v3 lizensiert. Maintainer des Projektes ist Roland Olbricht (Email: Roland.olbricht [at] gmx.de)- Beiträge, Fehlermeldungen oder Pull-Requests des Quellcodes sind gerne gesehen.
Hier geht es zur Mailingliste für Entwickler.
Einschränkungen
Wie jeder andere Service hat auch die Overpass API Einschränkungen:
- Download großer Mengen von Daten
Da die Größe des Ergebnis einer Overpass-API-Abfrage erst dann bekannt ist, wenn der Download abgeschlossen ist, ist es nicht möglich, während des Downloads eine Dauer für diesen Download abzuschätzen. Auch benötigt die Overpass API länger dafür, die Daten zu generieren und zu downloaden, als man bräuchte, um einfach alle Daten der selben Region statisch zu downloaden. Daher ist es besser, ein Planet file herunterzuladen, wenn man Regionen in Ländergröße mit (fast) allen Daten haben will. Die Overpass API ist dagegen dann sehr nützlich, wenn man nur eine Auswahl von Daten einer bestimmten Region haben möchte.
- Abfrage nach "historischen" OSM-Daten
Die Overpass API bietet nicht die Möglichkeit, Abfragen mit changeset-Eigenschaften zu machen. Es gibt zwar einen Workaround, indem man Abfragen für Zeitpunkte bildet und die Unterschiede anzeigt. Diese Vorgehen kann aber sehr unübersichtlich werden. Auch kann die Overpass API nicht die komplette "Geschichte" eines Objekts abfragen. Die Overpass API kann lediglich den Zustand eines Objekts zu einem gegebenen Zeitpunkt abfragen.
Karten-Daten-Abfrage
Bevor die Syntax detailliert erklärt wird, wird hier der möglicherweise häufigste Anwendungsfall die Karten-Daten-Abfrage gezeigt. Eine Karten-Daten-Abfrage dient dazu, alle Daten (einschließlich der Meta-Daten) innerhalb einer Fläche (Bounding Box) zu erhalten. Die folgenden Beispiele sind auf ein Minimum reduziert. Die Links (die Icons), die diese Beispiele in ausführbarer Form enthalten, verwenden zusätzliche Parameter, u. a. um die Karte zu zentrieren, den Zoom-Level zu setzen und noch weitere.
| Overpass QL | Overpass XML |
|---|---|
 (node(51.249,7.148,51.251,7.152);<;);out meta;
|
<union>
<bbox-query s="51.249" w="7.148" n="51.251" e="7.152"/>
<recurse type="up"/>
</union>
<print mode="meta"/>
|
Um die Abfrage auszuführen, kann man sie in dieses Formular kopieren. Um die Daten auf einer Karte betrachten zu können, kann man Overpass Turbo benutzen.
Die Werte der Bounding Box werden folgendermaßen angegeben:
(51.249,7.148,51.251,7.152) kleinste geografische Breite (latitude), kleinste geografische Länge (longitude), größte geografische Breite (latitude), größte geografische Länge (longitude) (oder einfacher: Süden-Westen-Norden-Osten).
Ressourcenverwaltung (osm-script)
Das osm-script wird im Hintergrund hinzugefügt, wenn Du es nicht explizit angibst. Will man dagegen die Ressourcenverwaltung optimieren, sollte man das osm-script explizit angeben, indem man Werte für timeout und element-limit (bzw. maxsize in Overpass QL) festlegt.
| Overpass XML | Overpass QL |
|---|---|
<osm-script timeout="900" element-limit="1073741824">
<bbox-query s="51.15" w="7.0" n="51.35" e="7.3"/>
<print/>
</osm-script>
|
[timeout:900][maxsize:1073741824];
node(51.15,7.0,51.35,7.3);
out;
|
Diese Abfrage erweitert den Time-out von 3 Minuten auf 15 Minuten (900 Sekunden). Zusätzlich wird das Limit für den Speicherverbrauch auf 1 GiB (entspricht 1073741824 Byte) gesetzt.
Warnung: Wenn Du dieses Beispiel ausführst, werden mehr als 100 MiB an Daten abgerufen. Overpass warnt Dich, wenn Du die Abfrage direkt im Browser ausführst, um die Daten auf der Karte darzustellen. Es kann sein, dass dabei der Browser abstürzt. Für Abfragen, die solche großen Datenmengen liefern, sollten andere Tools benutzt werden.
Diese Ressourcenbegrenzungen können nicht auf beliebig hohe Werte gesetzt werden: Jede Overpass-API-Instanz kann sich weigern, sie über einen bestimmten Schwellenwert hinaus auszudehnen (abhängig von den Serverfunktionen oder der aktuellen Serverlast). Auch kann die Abfrage mit einer Fehlermeldung (und einem Nicht-OK-HTTP-Server-Fehlerstatus) fehlschlagen.
Anwendungsbeispiele für Fortgeschrittene
Die folgenden Beispiele stellen die zusätzlichen Befehle recurse und around vor. Sie sind nur in Kombination mit anderen Befehlen sinnvoll.
Auch hier können alle folgenden Beispiele getestet werden, indem die Snippets in dieses Abfragefeld kopiert werden.
Hinweis: Das Abschließen von Abfragen kann einige Minuten dauern. Wenn Timeouts verursacht werden, kann der Timeout-Zeitraum verlängert werden.
Recurse
Mit recurse werden alle Elemente abgefragt, die Mitglieder eines gemeinsamen, übergreifenden Elements sind. Es ist für Wege verfügbar, um alle verbundenen Knoten zu erhalten, für Relationen, um alle Mitgliedsknoten oder Mitgliedswege zu erhalten. Oder umgekehrt, um für einen Knoten, Weg oder eine Relation die Wege oder Relationen zu erhalten, denen das Element angehört. Der Elementtyp wird durch das Attribut type ausgewählt.
<query type="relation">
<has-kv k="ref" v="CE 65"/>
</query>
<recurse type="relation-backwards"/>
<print/>
Metadaten
Neben dem speziellen Druckmodus gibt es zwei Anweisungen, die für die Abfrage spezifischer Metadaten bestimmt sind, nämlich user und newer.
User
Man kann alle Daten auswählen, die von einem bestimmten User zuletzt bearbeitet wurden. Wählen Sie den Usernamen (z. B. "mein"):
<user name="Roland Olbricht"/>
<print mode="meta"/>
Oder man wählt eine Benutzer-ID aus:
<user uid="65282"/>
<print mode="meta"/>
Diese Anweisung kann auch innerhalb einer Abfrageanweisung verwendet werden. Sie schränkt dann das Ergebnis auf die Daten ein, die von dem angegebenen Benutzer zuletzt bearbeitet wurden:
<query type="node">
<user name="Roland Olbricht"/>
<has-kv k="highway" v="bus_stop"/>
<bbox-query s="51.2" n="51.35" w="7.05" e="7.3"/>
</query>
<print mode="meta"/>
Newer
Newer kann innerhalb einer Abfrageanweisung verwendet werden, aber nicht als eigenständige Anweisung. Newer schränkt die Ausgabe auf Elemente ein, die nach dem angegebenen Datum bearbeitet wurden. Das Datum muss im Format JJJJ-MM-TTTHH:MM:SSZ vorliegen. Sie bezieht sich, wie auch die Ergebnisse, immer auf die Zeitzone UTC.
<query type="node">
<newer than="2011-08-01T00:00:00Z"/>
<has-kv k="highway" v="bus_stop"/>
<bbox-query s="51.2" n="51.35" w="7.05" e="7.3"/>
</query>
<print mode="meta"/>
Wenn man alle Knoten, die neuer als ein bestimmtes Datum sind, aus einer Bbox abrufen möchte, kann man eine Abfrage mit einem Item-Substatement verwenden.
<bbox-query s="51.2" n="51.35" w="7.05" e="7.3"/>
<query type="node">
<item/>
<newer than="2011-08-01T00:00:00Z"/>
</query>
<print mode="meta"/>
Siehe https://wiki.openstreetmap.org/wiki/DE:Overpass_API/Beispielsammlung für Beispiele mit modernerer Syntax.