DE:Xapi

From OpenStreetMap Wiki
Jump to navigation Jump to search
Xapi - Other languages
Logo.png
Diese Seite handelt von historischen Inhalten der Geschichte von OpenStreetMap. Es geht dabei nicht um Gegenwärtiges, sondern um frühere Konzepte, Probleme oder Ideen.


Warning
 XAPI wird nicht mehr empfohlen, da keine der ursprünglichen nativen Installationen mehr verfügbar ist.
Alte XAPI-Anwendungen können die XAPI-Kompatibilitätsebene noch immer nutzen, neue Projekte sollten stattdessen Overpass QL bzw. Overpass API verwenden.

Die OSM Extended API (auch xapi) ist eine API, die Lesezugriffe auf die OSM-Datenbank erlaubt. Sie basiert auf einer modifizierten Version der Standard-API und bietet erweiterte Such- und Abfragemöglichkeiten. Neben den üblichen Kartenabfragen lassen sich OSM-Daten z.B. nach Schlüsselwerten selektieren.

Die verwendete Datenbank ist ein Spiegel [1] der zentralen OSM-Datenbank. Normalerweise sind Änderungen in der Hauptdatenbank nach 10 Minuten auch auf den Spiegel übertragen.

Je nach Tageszeit muss auf Grund der Vielzahl der Zugriffe mit sehr hohen Antwortzeiten und gelegentlich kurzen Ausfällen gerechnet werden.

Osmxapi benutzt eine REST-Style-Schnittstelle mit X-path.

Alle Antworten haben grundsätzlich das gleiche Format wie das Standard-Protokoll, können aber erweiterte Namensräume besitzen. Die Suche nach Schlüsseln verwendet eine X-path-ähliche Syntax zum Spezifizieren der Suchbegriffe.

Server

Der xapi-Service wird von mehreren verschiedenen Servern angeboten. Jeder dieser Server kann entweder direkt oder über informationfreeway, der die Anfrage an einen geeigneten Server weiterleitet, angesprochen werden. Auf der englischen Seite sind die Servernamen je nach Verfügbarkeit eingefärbt.

Kartenabfrage

Die Kartenabfrage funktioniert genauso wie die Kartenabfrage auf der Haupt-API und liefert:

  • alle Punkte, die sich im gegebenen umgebenden Rechteck (englisch bounding box) befinden und alle Relationen, die mindestens einen der Punkte enthalten
  • alle Linien, die mindestens einen der Punkte innerhalb des umgebenden Rechtecks enthalten und alle Relationen, die diese Linien referenzieren; zusätzlich alle Punkte außerhalb des umgebenden Rechtecks, die durch eine Linie referenziert werden.
GET /api/0.6/map?bbox=links,unten,rechts,oben

mit:

  • links ist die geografische Länge der westlichen Begrenzung des umgebenden Rechtecks.
  • unten ist die geografische Breite der südlichen Begrenzung des umgebenden Rechtecks.
  • rechts ist die geografische Länge der östlichen Begrenzung des umgebenden Rechtecks.
  • oben ist die geografische Breite der nördlichen Begrenzung des umgebenden Rechtecks.

Beispiel

http://www.informationfreeway.org/api/0.6/map?bbox=11.54,48.14,11.543,48.145

( http://xapi.openstreetmap.org/api/0.6/map?bbox=11.54,48.14,11.543,48.145 )

Kommentar

  • Im Gegensatz zur Haupt-API, die nur Anfragen bis 0.25 Quadrat-Grad (z.B. ein Quadrat mit einer Seitenlänge von einem halben Grad) erlaubt, bearbeitet xapi Anfragen bis zu einer Größe von 100 Quadrat-Grad.
  • Diese Abfrage ist identisch zu der folgenden Abfrage nach Schlüsseln:
/api/0.6/*[bbox=links,unten,rechts,oben]

Abfrage von Attributen

Osmxapi verarbeitet Anfragen für alle drei Arten von Elementen: Punkte, Linien und Relationen.

Punkte

Eine Punkte-Abfrage liefert ein XML-Dokument, das Punkte zusammen mit den dazugehörigen Attributen enthält. Die URL für eine Punkt-Abfrage hat folgende Form: 

 http://www.informationfreeway.org/api/0.6/node[...]

Dies liefert eine Standard-OSM-API-Antwort, welche die Punkte und ihre Attribute enthält. Beispiel: 

 <?xml version='1.0' standalone='no'?>
 <osm version='0.6' generator='osmxapi: OSM Extended API' 
  xmlns:osmxapi='http://www.informationfreeway.org/osmxapi/0.6'
  osmxapi:uri='/api/0.6/node[amenity=hospital]'
  osmxapi:planetDate='200803150826' 
  osmxapi:copyright='2008 OpenStreetMap contributors' 
  osmxapi:instance='zappy2'>
   <node id='672180' lat='48.2111685091189' lon='16.3035366605548' timestamp='2006-09-11T16:28:25+01:00'>
     <tag  k='amenity' v='hospital'/>
     <tag  k='name' v='Wilhelminenspital'/>
   </node>
   <node id='3596186' lat='53.4633699598014' lon='-2.22667910006381' timestamp='2007-06-21T17:10:58+01:00'>
     <tag  k='amenity' v='hospital'/>
     <tag  k='name' v='Manchester Royal Infirmary'/>
   </node>
   ...
 </osm>

Linien

Für die Abfrage von Linien hat die URL folgende Form: 

 http://www.informationfreeway.org/api/0.6/way[...]

Dies liefert wieder ein XML-Dokument, das die Linien enthält, die auf die Suchbegriffe zutreffen. Für jede passende Linie werden außerdem alle referenzierten Punkte geliefert. Eine Antwort könnte beispielsweise so aussehen: 

 <?xml version='1.0' standalone='no'?>
 <osm version='0.6' generator='osmxapi: OSM Extended API' 
  xmlns:osmxapi='http://www.informationfreeway.org/osmxapi/0.6'
  osmxapi:uri='/api/0.6/way[landuse=residential]'
  osmxapi:planetDate='200803150826' 
  osmxapi:copyright='2008 OpenStreetMap contributors' 
  osmxapi:instance='zappy2'>
   <node id='218963' lat='52.5611324692581' lon='-1.79024812573334' timestamp='2006-03-22T16:47:48+00:00'>
   </node>
   <node id='331193' lat='53.7091237972264' lon='-1.50282510180841' timestamp='2007-03-31T00:09:22+01:00'>
     <tag  k='highway' v='traffic_signals'/>
     <tag  k='source' v='Yahoo'/>
   </node>
   ... 
   <way id='4958218' timestamp='2007-07-25T01:55:35+01:00'>
     <nd ref='218963'/>
     <nd ref='331193'/>
     ...
     <tag  k='landuse' v='residential'/>
     <tag  k='source' v='landsat'/>
   </way>
 </osm>

Relationen

Für Relationen sieht die URL so aus: 

 http://www.informationfreeway.org/api/0.6/relation[...]

Das gelieferte XML-Dokument enthält die Relationen, die auf die Suchbegriffe passen. Für jede Relation werden zusätzlich alle referenzierten Punkte und Linien geliefert. Beispiel: 

 <?xml version='1.0' standalone='no'?>
 <osm version='0.6' generator='osmxapi: OSM Extended API' 
  xmlns:osmxapi='http://www.informationfreeway.org/osmxapi/0.6'
  osmxapi:uri='/api/0.6/way[landuse=residential]'
  osmxapi:planetDate='200803150826' 
  osmxapi:copyright='2008 OpenStreetMap contributors' 
  osmxapi:instance='zappy2'>
   <node ...
   <way ...
   <relation id='2670' timestamp='2007-10-25T03:05:34Z'>
     <member type='way' ref='3992472' role=/>
     <member type='way' ref='3992524' role=/>
     <member type='way' ref='4253050' role=/>
     <member type='way' ref='4253053' role=/>
     <member type='way' ref='4266813' role=/>
     <member type='way' ref='10285106' role=/>
     <tag k='name' v='Fonnereau Way'/>
     <tag k='network' v='Ipswich footpaths'/>
     <tag k='type' v='route'/>
   </relation>    
 </osm>

Beliebige Elemente

Möchte man nicht nach Elementen (Punkte, Linien, Relationen) selektieren, sondern in einem Aufruf gleich alle Elemente für bestimmte Suchbegriffe erhalten, so ist folgende URL zu verwenden: 

 http://www.informationfreeway.org/api/0.6/*[...]

Dies liefert wieder ein XML-Dokument, das alle Punkte, Linien und Relationen enthält, die zu den Suchbegriffen passen. Wie auch bei der selektierten Abfrage werden hier für alle passenden Linien die referenzierten Punkte und für alle Relationen die dazugehörigen Punkte und Linien (von diesen natürlich auch die Punkte) geliefert. Beispiel: 

 <?xml version='1.0' standalone='no'?>
 <osm version='0.6' generator='osmxapi: OSM Extended API' 
  xmlns:osmxapi='http://www.informationfreeway.org/osmxapi/0.6'
  osmxapi:uri='/api/0.6/*[amenity=hotel]'
  osmxapi:planetDate='200803150826' 
  osmxapi:copyright='2008 OpenStreetMap contributors' 
  osmxapi:instance='zappy2'>
   <node id='218963' lat='52.5611324692581' lon='-1.79024812573334' timestamp='2006-03-22T16:47:48+00:00'>
   </node>
   <node id='331193' lat='53.7091237972264' lon='-1.50282510180841' timestamp='2007-03-31T00:09:22+01:00'>
     <tag k='amenity' v='hotel'/>
   </node>
   ... 
   <way id='4958218' timestamp='2007-07-25T01:55:35+01:00'>
     <nd ref='218963'/>
     <nd ref='331193'/>
     ...
     <tag k='amenity' v='hotel'/>
     <tag k='building' v='hotel'/>
   </way>
   <relation id='123456' timestamp='2007-10-25T03:05:34Z'>
     <member type='node' ref='331193' role=/>
     <member type='node' ref='331194' role=/>
     ...
     <tag k='amenity' v='hotel'/>
     <tag k='operator' v='Premier Inns'/>
     <tag k='type' v='operators'/>
   </relation>    
 </osm>

Suchbegriffe

An jede API-Anfrage können Prädikate angehängt werden um festzulegen, welche Elemente selektiert werden sollen. Beispielsweise selektiert [amenity=hospital] alle Elemente, bei denen der Schlüssel amenity den Wert hospital besitzt. Die komplette URL für eine solche Abfrage wäre dann: 

 http://www.informationfreeway.org/api/0.6/node[amenity=hospital]

Es ist auch möglich, mehrere solcher Prädikate anzuhängen, wobei jedes weitere angehängte Prädikat das Ergebnis weiter einschränkt. Momentan ist dies begrenzt auf ein Schlüssel-Prädikat und ein "umgebendes Rechteck"-Prädikat (engl. bounding box predikate). Beispiel: 

 http://www.informationfreeway.org/api/0.6/node[amenity=hospital][bbox=-6,50,2,61]

Diese Anfrage liefert alle Punkte mit amenity=hospital, die im angegebenen umgebenden Rechteck (bbox) liegen. Das in diesem Fall angegebene umgebende Rechteck umfasst ganz England, Wales und Schottland.

Attribut-Prädikate

Ein Prädikat hat die Form [key=value]. Beispiel: node[amenity=hospital] passt auf alle Punkte, die den Schlüssel amenity mit dem Wert hospital besitzen, d.h. <tag k="amenity" v="hospital"/>.

Für Schlüssel und Wert können auch Platzhalter verwendet werden:

  • way[construction=*]
  • node[*=gate]
  • node[*=*] Nicht empfohlen, liefert GByte-weise Daten.

Um verschiedene Werte eines Schlüssels gleichzeitig zu selektieren (also die Vereinigungsmenge aus mehreren Einzelanfragen zu bilden), kann der Vereinigungsoperator benutzt werden. Um beispielsweise alle größeren Straßen zu selektieren:

  • way[highway=motorway|motorway_link|trunk|primary]

Der Vereinigungsoperator funktioniert auch bei Schlüsseln:

  • node[amenity|leisure=golf_course]

Hinweis: Die URL muss in UTF-8 kodiert und URLEncoded sein, falls Nicht-ASCII-Zeichen verwendet werden. Firefox (Version 2.0.0.11 und höher) benutzt als Standard immer noch ISO-8859-1-Kodierung. [2]

BBox-Prädikate

Eine andere Form des Prädikats ist die Verwendung des bbox-Pseudo-Schlüssels. Ein Prädikat der Form [bbox=links,unten,rechts,oben] definiert ein Rechteck, das die Größe des Ergebnisses beschränkt. Nur Elemente, die teilweise innerhalb dieses Rechtecks liegen, sind im Ergebnisdokument enthalten.

Im Gegensatz zur Standard-OSM-API besteht bei xapi keine Größenbegrenzung für das umgebende Rechteck, wenn es zusammen mit einem Attribut-Prädikat verwendet wird. Ohne Attribut-Prädikat ist es auf 100 Quadrat-Grad beschränkt.

Das umgebende Rechteck, das angenommen wird, wenn keines spezifiziert wurde, umfasst die gesamte Erde.

Attribute

Hauptsächlich sind Anfragen an xapi solche, die eine Schlüssel-Wert-Kombination selektieren. Zusätzlich zu den üblichen Schlüsseln speichert xapi eine Reihe nützlicher Pseudo-Schlüssel. Diese befinden sich alle im osm: Namensraum um Konflikte zu vermeiden.

  • osm:user - wenn bei einem Element das Attribut user gesetzt ist, wird dies im Pseudo-Schlüssel osm:user gespeichert.
  • osm:users - enthält eine Liste aller Benutzer, die an diesem Element Änderungen vorgenommen haben (Änderungen vor der Version 0.6 API können nicht berücksichtigt werden)
  • osm:timestamp

Benutzung

Die xapi-URLs können prinzipiell in jedem Browser benutzt werden. Einfache Abfragen können aber mehrere MByte Daten produzieren, die manche Browser in die Knie zwingen. Deshalb ist es empfehlenswert, Werkzeuge wie wget oder curl zu benutzen, um den Datenstrom direkt in eine Datei zu leiten. Beispiel: Folgende Anfrage speichert alle Krankenhäuser in der Datei data.osm: 

 $ wget http://www.informationfreeway.org/api/0.6/node[amenity=hospital] -O data.osm

Achtung: curl kann Weiterleitungen nicht automatisch behandeln. Deshalb muss hier ein Server direkt angesprochen werden. Außerdem muss die Option -g angegeben werden, andernfalls würde [...] als Teil der Kommandozeile angesehen. 

 $ curl -g http://www.informationfreeway.org/api/0.6/node[amenity=hospital] -o data.osm

Statistik

Statistik über den Inhalt der xapi-Datenbank: http://osmxapi.hypercube.telascience.org/total.xml. Diese wird täglich aktualtisiert.

RSS Feed

Mit dem xapi-RSS-feed können Änderungen an Elementen, die auf der persönlichen Beobachtungsliste (engl. watchlist) stehen, überwacht werden.

Jedes Element, das mit watch:deineBenutzerId=1 (oder yes oder true) gekennzeichnet ist, wird von xapi überwacht. Jede Änderung an diesem Element - Löschung eingeschlossen - wird im RSS-feed angezeigt. Überwachte Punkte können zu Kategorien gruppiert werden, indem der Wert das Attributs watch auf einen Kategorienamen gesetzt wird. Z.B. watch:80n=churches fügt ein Element der Kategorie churches hinzu.

Um ein Element wieder von der Beobachtungsliste zu entfernen, genügt es, die Kennzeichnung/das Attribut vom entsprechenden Element zu löschen.

Um seine eigene Beobachtungsliste zu abonnieren, ist folgende URL zu benutzen: 

 http://www.informationfreeway.org/api/0.6/watch/yourUserId

Beispiel: 

 http://www.informationfreeway.org/api/0.6/watch/80n

Um eine bestimmte Kategorie zu abonnieren, muss an diese URL der Name dieser Kategorie angehängt werden. Beispiel: 

 http://www.informationfreeway.org/api/0.6/watch/80n/churches

Anmerkungen:

  • Jeder kann deine Beobachtungsliste abonnieren. Du kannst jede Beobachtungsliste eines anderen abonnieren.
  • Momentan ist die Überwachung nur für Punkte möglich.
  • Diese Funktion ist noch experimentell, d.h. es kann noch deutliche Änderungen geben.
  • Das Hinzufügen oder Entfernen eines Attributs watch eines anderen Benutzers bewirkt nichts. Das Attribut watch eines anderen Benutzers kann zwar bearbeitet werden, aber dadurch kann das Element nicht von der Beobachtungsliste des anderen Benutzers entfernt oder hinzugefügt werden. Jeder Benutzer kann nur seine eigene Beobachtungsliste kontrollieren.

Einschränkungen

  • Created_by tags. Diese Attribute sind im Allgemeinen uninteressant und werden deshalb aus Performanzgründen unterdrückt.
  • Prädikate. Momentan ist jede Anfrage auf ein Attribut-Prädikat und ein umgebendes Rechteck beschränkt. Irgendwann werden komplexere Suchanfragen implementiert. Die Angabe mehrerer umgebender Rechtecke wäre hervorragend für Anwendungen wie GpsMid - für einzelne Regionen wurde ein Datendownload über xapi in Osm2GpsMid implementiert, was sehr hilfreich ist.
  • Syntax der Anfrage. Der Aufbau der Anfrage ist nicht formal definiert und wird auch nicht von einem entsprechenden Parser verarbeitet. Anfragen, die nicht dem obigen Schema entsprechen, können unvorhersagbare Ergebnisse produzieren.
  • user. Die diff-Dateien enthalten Benutzerinformationen, die Datei planet.osm aber nicht. Wenn das user-Attribut vorhanden ist, ist es auch in der Antwort enthalten. Eine Liste aller Benutzer, die ein Element bearbeitet haben, wird erstellt und ist in osmxapi:users enthalten. Diese Listen enthalten alle Änderungen seit die Datenbank das letzte Mal (12. März 2008) aus einer kompletten planet.osm resynchronisiert wurde.

Siehe auch

Retrieved from "https://wiki.openstreetmap.org/w/index.php?title=DE:Xapi&oldid=2756039"