POIs

Dieses Dokument beschreibt die REST-Schnittstellen für POIs. Dieses Dokument ist Teil der Dokumentation der REST-API-Schnittstellen der MD Content-API.

Inhaltsverzeichnis

Suchanfragen für POIs

Allgemeine Suche nach POI

Der grundlegende Pfad zum Abfragen von Daten einer allgemeinen Suche ist:

 http://api.123poi.com/data/poi/projection/all/?parameter=value
    

Das Ergebnis enthält immer alle Informationen zu einem POI. Diese bestehen in der Hauptsache aus dem Base-POI und den Contributions. Contributions sind sprach- und Userspezifisch abgelegt. Das bedeutet, dass ein User in einer Sprache nur eine Contribution pro POI anlegen kann. Er kann aber in jeder möglichen Sprache eine Contribution anlegen.

Über die Struktur des Ausgabeformates sehen Sie bitte im Abschnitt Ausgabeformate nach.

Man erhält als Ergebnis eine Liste von zuletzt geänderten POI.

Beispiel:

 GET http://api.123poi.com/data/poi/api/all/?loc=Berlin
    

Ergebnis ist eine Liste von POI, deren Ortsname Berlin enthält. Genaue Treffer werden an den Anfang sortiert.

Beispiel:

 GET http://api.123poi.com/data/poi/api/all/?search=Nachts+im+Museum
    

Ergebnis ist eine Liste von POI, die in oben angegebenen Feldern eines POI mit den Begriffen Nachts,im,Museum einen Treffer ergeben.

Beispiel:

 GET http://api.123poi.com/data/poi/api/all/?tag=Restaurant
    

Ergebnis ist eine Liste von POI, die den Tag Restaurant haben.

Beispiel:

 GET http://api.123poi.com/data/poi/api/all/?book=12
    

Ergebnis ist eine Liste von POI, die dem Reiseführer mit der BuchId 12 enthalten sind.

Natürlich lassen sich obige Parameterwerte auch kombinieren, was das Ergebnis auf eine kleinere Ergebnismenge und damit eine höhere Relevanz einschränken kann.

Beispiel:

 GET http://api.123poi.com/data/poi/api/all/?tag=Museum&search=Bode&loc=Berlin
    

Das Ergebnis ist eine Liste von POI, auf die die angebenen Kriterien zutreffen. POI, die alle drei Kriterien erfüllen werden nach vorn sortiert.

Suche in den POI eines Users

Der grundlegende Pfad zum Abfragen von Daten einer Userbezogenen Suche ist:

http://api.123poi.com/data/poi/projection/user/UserID/?parameter=value
    

Das Ergebnis enthält immer alle Informationen zu einem POI.
Diese bestehen in der Hauptsache aus dem Base-POI und den Contributions des Users.
Da Contributions sind sprach- und userspezifisch abgelegt sind, werden hiermit also die Contributions anderer User ausgeblendet.
Die Daten des BasePOI stehen zur Verfügung, da es sein kann, dass die Contribution eines Users z.B. keine Adress- oder Geodaten enthält.

Über die Struktur des Ausgabeformates sehen Sie bitte im Abschnitt Ausgabeformate nach.

Man erhält als Ergebnis eine Liste von zuletzt geänderten POI.

Beispiel:

GET http://api.123poi.com/data/poi/api/user/10/?loc=Berlin
    

Ergebnis ist eine Liste von POI, deren Ortsname Berlin enthält. Genaue Treffer werden an den Anfang sortiert.

Beispiel:

GET http://api.123poi.com/data/poi/api/user/10/?search=Nachts+im+Museum
    

Ergebnis ist eine Liste von POI, die in oben angegebenen Feldern eines POI mit den Begriffen Nachts,im,Museum einen Treffer ergeben.

Beispiel:

 GET http://api.123poi.com/data/poi/api/user/10/?tag=Restaurant
    

Ergebnis ist eine Liste von POI, die den Tag Restaurant haben.

Natürlich lassen sich obige Parameterwerte auch kombinieren, was das Ergebnis auf eine kleinere Ergebnismenge und damit eine höhere Relevanz einschränken kann.

Beispiel:

 GET http://api.123poi.com/data/poi/api/user/10/?tag=Museum&search=Bode&loc=Berlin
    

Das Ergebnis ist eine Liste von POI eines Users, auf die die angebenen Kriterien zutreffen. POI, die alle drei Kriterien erfüllen werden nach vorn sortiert.

Suchen in einer BoundingBox

@|since: v1.0-alpha2

Für Suchen in einer BoundingBox wird ein zusätzlicher Parameter angegeben, siehe Abschnitt Parameterwerte.

``

Suchen in einem Corridor

@|since: v5.0.5

Für Suchen in einem Corridor, muss ein POST Request durchgeführt werden und der Corridor muss in Form eines LineStrings oder MultiLineStrings und eine Distanz in Meter im Body mitgegeben werden.

Optional lässt dich die Suche zusätzlich mit einer BoundingBox einschränken. Als Formate werden JSON und XML unterstützt.

Beispiel-JSON mit LineString:

{"geometry": {
       "type":"LineString",
       "coordinates":[[9.18299,48.77582],[9.1854,48.78191],[9.17963,48.78457],...,[13.40495,52.52001]]},
       "distance":2000,
       "boundingBox":{
       "northwest":{"lat":52.6,"lon":9.1},
       "southeast":{"lat":48.7,"lon":13.5}
       }
    }
    

Beispiel-XML mit LineString:

Beispiel-JSON mit MultiLineString:

Beispiel-XML mit MultiLineString:

Suchen in einem Polygon

@|since: v5.0.5

Für Suchen in einem Polygon, muss ein POST Request durchgeführt werden und das Polygon muss im Body mitgegeben werden. Es werden zur Zeit keine Löcher unterstützt.

Optional lässt dich die Suche zusätzlich mit einer BoundingBox einschränken. Als Formate werden JSON und XML unterstützt.

Beispiel-JSON:

{
     "geometry":{
        "type":"Polygon",
        "coordinates":[
          [[9.1305,48.793],[9.1267,48.7941],[9.1038,48.8039],...,[9.1305,48.793]]
        ]
      },
      "boundingBox":{
         "northwest":{"lat":52.6,"lon":9.1},
        "southeast":{"lat":48.7,"lon":13.5}
      }
    }
    

Beispiel-XML:

Umkreissuche

@|since: v1.0-alpha4

Für Umkreissuche wird ein zusätzlicher Parameter angegeben, siehe Abschnitt Parameterwerte.

Featured POIs bei der Suche voranstellen

Um bei einer allgemeinen Suchanfrage die FeaturedPOIs voranzustellen, muss der Parameter "sort" mit dem Wert "frel" angegeben werden.

Beispiele:

 GET http://api.123poi.com/data/poi/api/all/?sort=frel
    

 GET http://api.123poi.com/data/poi/api/all/?sort=frel&search=Museum
    

Suche in Featured POIs

@|since: v1.0-alpha3

Featured POI sind POI mit einem besonderen Stellenwert. Sie werden nur für Lizenznehmer ausgeliefert, die an einem unserer Partnerprogramme teilnehmen. Im Allgemeinen lassen sich featured POI genauso abfragen, wie in der allgemeinen Suche mit der Besonderheit, dass auf dem featured Path per default eine begrenzte Anzahl von POI(10) ausgeliefert wird, die allesamt gefeatured sind. Die Reihenfolge der Ausgabe ist unbestimmt, weshalb ein Blättern in der Ergbnismenge nicht sinnvoll ist.

GET http://api.123poi.com/data/poi/api/featured
    

Bei der Suche nach Featured POIs auf dem "featured path" ist die zufällige Sortierung Voreinstellung.

Beispiel:

 GET http://api.123poi.com/data/poi/api/featured?itemsperpage=3
    

Beispiel:

GET http://api.123poi.com/data/poi/api/featured?sort=rel&search=Hotel&loc=Stuttgart&itemsperpage=3&startindex=16
    

In diesem Beispiel werden alle Feature POI zurückgeliefert, die ein Hotel in Stuttgart sind. Zusätzlich werden max 3 POI pro Anfrage ausgegeben und in diesem konkreten Fall ab index 16, was bei einem Blättern der Seite 6 entspricht.

Vorschläge für Suchanfragen

Es gibt eine eigene Schnittstelle, um Vorschläge für Suchanfragen zu bekommen. Diese Schnittstelle kann über AJAX vom Browser verwendet werden, um bei der Eingabe von Suchbegriffen im Hintergrund bereits mit den eingegebenen Fragmenten Suchanfragen zu stellen. Das Resultat kann im Browser dann als Auswahlliste angegeben werden.

Es gibt sechs unterschiedliche Schnittstellen für allgemeine Vorschläge, Tags, Location, Kategorien, Destinationen und POI-Titel. Bei den allgemeinen Vorschlägen werden die Titel, die Tags und die Kategorien durchsucht, bei den Vorschlägen für Tags werden nur die Tags durchsucht, bei den Vorschlägen für Locations werden Städte, Bundesländer, Länder, Kontinente und touristische Regionen durchsucht. Bei den Vorschlägen für Kategorien werden nur die Kategorien durchsucht. Bei den Vorschlägen für Destinationen werden die Namen der Destination durchsucht, wobei auch die Namen der übergeordneten Destinationen einbezogen werden.

Die Suche nach Tags lässt sich über den lang Parameter auf eine gewünschte Sprache einschränken. Die Suche nach Titeln und nach Locations wird zusätzlich automatisch auf Sichtbarkeit eingeschränkt. Daher können die Vorschläge für Titel und für Locations je nach Nutzer abweichen.

Die allgemeinen Vorschläge und die Vorschläge für Locations können über eine angegebene Boundingbox eingeschränkt werden. Es werden dann nur Titel von POIs bzw. Locations zurückgeliefert, die innerhalb der Boundingbox liegen.

Die Suche nach POI-Titeln lässt sich auf Destinationen (alle POIs der Destination) einschränken, alternativ wird auch die Einschränkung auf BoundingBox oder Umkreis unterstützt.

Die Einschränkung auf Destination erfolgt über den Parameter "dest". Aus Performancegründen wird nicht über das Polygon gesucht, sondern über die BoundingBox der Destination. Die Ausgabe erfolgt als JSON.

  {     "values": [       {         "poiId": 116791683,         "title": "Burg Berwartstein",         "category": {           "id": 16,           "name": "Essen & Trinken"         },         "coordinates": {           "lat": 49.10857,           "lon": 7.86364         },         "location": "Erlenbach bei Dahn",         "highlight": "Burg Berwartstein, Essen & Trinken, Erlenbach bei Dahn",         "highlightTerms": [           "Burg Berwartstein",           "Essen & Trinken",           "Erlenbach bei Dahn"         ],         "extendedTitle": "Burg Berwartstein, Essen & Trinken, Erlenbach bei Dahn"       },       {         "poiId": 115006669,         "title": "Burg Berwartstein",         "category": {           "id": 13,           "name": "Sehenswertes"         },         "coordinates": {           "lat": 49.10856,           "lon": 7.86364         },         "location": "Erlenbach",         "highlight": "Burg Berwartstein, Sehenswertes, Erlenbach",         "highlightTerms": [           "Burg Berwartstein",           "Sehenswertes",           "Erlenbach"         ],         "extendedTitle": "Burg Berwartstein, Sehenswertes, Erlenbach"       }     ]   }
    

Alle Kategorien ermitteln

Über den folgenden Pfad können alle Kategorien abgefragt werden:

 http://api.123poi.com/data/poi/api/category/all?lang=de
    

Die Kategorieliste kann als ATOM-Feed oder im JSON-Format ausgegeben werden. Neben dem Namen der Kategorien werden auch die IDs sowie ggf. die ID der Oberkategorie ausgegeben.

Beispielhafter Auszug aus der Kategorieliste:

<feed>
      ...
      <data:category>
        <data:id>17</data:id>
        <data:name>Einkaufen & Shoppen</data:name>
      </data:category>
      ...
      <data:category>
        <data:id>1001</data:id>
        <data:parentId>10</data:parentId>
        <data:name>Vertragsschulen</data:name>
      </data:category>
      ...
    </feed>
    

Einzelne Kategorie mit Unterkategorien ermitteln

Es kann eine einzelne Kategorie anhand seiner ID abgefragt werden, welche dann zusammen mit seinen Unterkategorien zurückgegeben wird.

Alle verwendeten Ländercodes ermitteln (nicht verfügbar)

Es kann eine Liste mit allen Ländercodes abgefragt werden, welche von POIs verwendet werden. Diese Funktionalität ist aktuell nicht verfügbar.

Operationen auf POI-Daten (CRUD)

Anlegen eines POI

Die Daten, die angelegt werden sollen müssen im entsprechenden XML-Format angegeben und im Request Body mitgegeben werden. Dafür verwendet man ein entprechendes Tool.

Als Content Type wird application/atom+xml verwendet. Die Daten werden als neuer Eintrag <entry/> gepostet, Beispiel für ein XML:

 POST http://api.123poi.com/data/poi/api/poi
     
     <entry xmlns="http://www.w3.org/2005/Atom" xmlns:poi="http://api.123poi.com/poi/" xmlns:media="http://search.yahoo.com/mrss/" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/">
       <id/>
       <title type="text">summ</title>
       <summary type="text"/>
       <updated>2010-05-26 17.04</updated>
       <published/>
       <content type="application/atom+xml">
       <poi:poi xmlns:poi="http://api.123poi.com/poi/" xmlns:falkgeo="http://api.123poi.com/geo/" xmlns:data="http://api.123poi.com/data/" xmlns:falkmedia="http://api.123poi.com/media/" xmlns:user="http://api.123poi.com/user/">
           <poi:publishedDate>1274886299296</poi:publishedDate>
             <poi:poidata>
               <poi:type>Contribution</poi:type>
               <poi:title>Gottlieb Daimler Stadion</poi:title>
               <data:language>de</data:language>
               <falkgeo:coordinates>
                 <falkgeo:lat>48.791599</falkgeo:lat>
                 <falkgeo:lon>9.229890</falkgeo:lon>
               </falkgeo:coordinates>
               <data:address>
                 <data:country>Deutschland</data:country>
                 <data:isoCountryCode>DE</data:isoCountryCode>
                 <data:zip>70173</data:zip>
                 <data:location>Stuttgart</data:location>
                 <data:subLocation/>
                 <data:street/>
                 <data:number>1</data:number>
               </data:address>
               <data:contact>
                 <data:phone/>
                 <data:fax/>
                 <data:web>http://www.gottlieb-daimler-stadion.de</data:web>
                 <data:email>info@gottlieb-daimler-stadion.de</data:email>
               </data:contact>
               <poi:tags>
                 <poi:tag>
                   <poi:value>Stadion</poi:value>
                 </poi:tag>
               </poi:tags>
             <poi:description>Statdion in Stuttgart</poi:description>
           </poi:poidata>
           <data:category>
             <data:id>20</data:id>
           </data:category>
         </poi:poi>
       </content>
     </entry>
    

Eine vollständige Beschreibung des Formates findet sich in der Dokumentation des POI API XML-Schema.

Das Ergebnis dieses Requests teilt die URL mit, unter der der neue POI erreichbar ist.

Ändern eines POI

Ein User kann einen POI auf zwei verschiedene Arten ändern.

1. er fügt einem POI eine Contribution hinzu
2. er ändert eine von ihm angelegte Contribution

Beide Operation benutzen für diese Operation einen HTTP-PUT Request, der Pfad dieser Operation verweist auf den POI mit seiner ID.

Beispiel

 PUT http://api.123poi.com/data/poi/api/poi/6587945/
     
     <entry xmlns="http://www.w3.org/2005/Atom" xmlns:poi="http://api.123poi.com/poi/" xmlns:falkgeo="http://api.123poi.com/geo/"
       xmlns:data="http://api.123poi.com/data/" xmlns:falkmedia="http://api.123poi.com/media/" xmlns:user="http://api.123poi.com/user/">
       <title type="text">Zeitgeschichtliches Forum Leipzig</title>
       <content type="application/atom+xml">
         <poi:poi>
           <poi:poidata>
             <poi:title>Zeitgeschichtliches Forum Leipzig</poi:title>
             <data:language>de</data:language>
     
             <data:contact>
               <data:phone>(03 41) 22 20-0</data:phone>
               <data:web>http://www.hdg.de/leipzig/</data:web>
               <data:email>zfl@hdg.de</data:email>
             </data:contact>
     
             <poi:tags>
               <poi:tag>
                 <poi:value>Museum</poi:value>
               </poi:tag>
             </poi:tags>
     
           </poi:poidata>
         </poi:poi>
       </content>
     </entry>
    

Das dabei verwendete Eingabedatenformat entspricht dem eines POST Requestes. Es müssen nicht alle Daten erneut mitgesendet werden, es werden bei einem PUT-Request nur die Daten geändert, die auch mitgesendet werden. Eine Ausnahme dieser Regel sind Listen, wie zum Beispiel Tags - da ist nötig, die Tags, die beibehalten werden sollen, erneut mitzusenden.

Im obigen Beispiel würden gegen über dem Anlegen des POI noch fon, web und E-Mail hinzugefügt, bei den Tags würde das Tag 'Museum' hinzugefügt und das zuvor angebene Tag 'Museen' entfernt.

Löschen eines POI

Prinzipiell ist es so, dass ein User seinen Beitrag zu einem POI löschen kann. Ist er aber derjenige, der diesen POI angelegt hat und gibt es keine anderen Referenzen auf diesen POI, dann wird auch der Base-POI gelöscht. Das ist das "Tante Erna Prinzip", womit es Usern möglich gemacht wird, Daten aus der POI API wieder zu entfernen.

Beispiel für das Löschen des POI (bzw. der Contribution):

DELETE http://api.123poi.com/data/poi/api/poi/6587945/
    

Abfragen eines POI

Je nach Sichtbarkeit des POIs kann ein Gast, ein Freund oder nur der Eigentümer den POI abfragen.

Beispiel für das Abfragen des POI (bzw. der Contribution):

 GET http://api.123poi.com/data/poi/api/poi/6587945/
    

Abfragen mehrerer POIs

Die Reihenfolge der POIs entspricht der Reihenfolge der übergebenen IDs. Ist ein angeforderter POI nicht vorhanden, dann kommt es zu entsprechenden Lücken. Wird kein POI gefunden, dann wird eine leere Liste zurückgegeben.

Beispiel für das Abfragen von POIs:

Abfragen von möglichen Dubletten

Bevor der POI gespeichert wird, kann ein Dublettencheck ausgeführt werden, der mögliche Dubletten zurückliefert. Das Kriterium für eine Übereinstimmung wird über die Minimalanforderung festgelegt.

Als Content werden die Daten des Pois, welcher angelegt oder upgedated werden soll, mitgeliefert. Anhand dieser Daten wird der Dublettencheck durchgeführt. Als Ergebnis werden die Poi Ids der möglichen Dubletten zurückgeliefert.

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:exif="http://api.123poi.com/exif/" xmlns:poi="http://api.123poi.com/poi/" 
           xmlns:media="http://search.yahoo.com/mrss/" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/">
       <openSearch:totalResults>1</openSearch:totalResults>
       <openSearch:startIndex>0</openSearch:startIndex>
       <openSearch:itemsPerPage>10</openSearch:itemsPerPage>
       <openSearch:Query role="request" poi:access="VISIBLE"/>
       <updated>2010-10-07T10:40:36.406Z</updated>
       <link href="http://api.123poi.com/data/poi/api/check/poi" rel="self"/>
       <title type="text">Dublettencheck</title>
       <subtitle type="text"/>
       <id>http://api.123poi.com/data/poi/api/check/poi</id>
       <author>
         <name>Falk POI API</name>
       </author>
       <entry>
         <title type="text">Possible duplicate to 1</title>
         <link href="http://api.123poi.com/data/poi/api/poi/1" rel="alternate"/>
         <id>http://api.123poi.com/data/poi/api/poi/1</id>
         <summary type="text">Id: 1</summary>
         <content type="application/xml">
           <poi:duplicateIdentifier>
             <poi:contributorId>6</poi:contributorId>
             <poi:poiId>1</poi:poiId>
             <poi:matchingLevel>MINIMUM_MATCHING</poi:matchingLevel>
           </poi:duplicateIdentifier>
         </content>
       </entry>
     </feed>
    

Search Hints

User mit entsprechender Berechtigung können einen POI um searchHints und locationHints erweitern. Dort können beliebige Begriffe hinterlegt werden, welche helfen sollen, den POI besser zu finden. Dies wird hauptsächlich für Featured POIs verwendet. Wird bei einem POI in Bernhausen z.B. unter locationHints der Wert "Stuttgart" eingetragen, so wird er auch bei einer Location-Suche für Stuttgart gefunden.

Beispiel

PUT http://api.123poi.com/data/poi/api/poi/6587945/
    
    <entry xmlns="http://www.w3.org/2005/Atom" xmlns:poi="http://api.123poi.com/poi/" xmlns:data="http://api.123poi.com/data/" xmlns:user="http://api.123poi.com/user/">
      <title type="text">Zeitgeschichtliches Forum Leipzig</title>
      <content type="application/atom+xml">
        <poi:poi>
          <poi:searchHints>Osterfeuer Grillen</poi:searchHints>
          <poi:locationHints>Stuttgart</poi:locationHints>
        </poi:poi>
      </content>
    </entry>
    

POI als geschlossen melden

Ein angemeldeter Benutzer kann einen POI als geschlossen melden. Die Anzahl der Meldungen kann über das "closedCount" Feld beim POI eingesehen werden. Die Meldungen haben aber keinen Einfluss auf die Sichtbarkeit oder die Reihenfolge in Ergebnislisten.

Ein privilegierter Benutzer kann über dieselbe Schnittstelle einen POI schließen. Geschlossene POIs werden bei Suchen nicht mehr berücksichtigt, es sei denn der anfragende Benutzer hat eine Contribution an dem geschlossenen POI. Auch lassen sich geschlossene POIs weiterhin direkt abfragen. Geschlossene POIs werden in diesen Fällen über das "closed" Feld markiert. Das Feld ist Teil der Default-Granulierung.

Damit ein Portal unterscheiden kann, ob ein POI jetzt geschlossen wurde oder nur als geschlossen markiert wurde, wird im Erfolgsfall XML bzw. JSON mit einem Statuscode zurückgegeben.

Beim Statuscode 1 wurde der POI nur als geschlossen markiert:

Beim Statuscode 2 wurde der POI geschlossen:

Operationen auf Bewertungsdaten-Daten (CRUD)

Anlegen einer Bewertung

Die Daten, die angelegt werden sollen müssen im entsprechenden XML-Format angegeben und im Request Body mitgegeben werden. Das Anlegen einer Bewertung erfolgt über ein Update des POIs. Dabei muss lediglich der Wert der Bewertung mitgegeben werden.

Die Daten werden als neuer Eintrag <entry/> gepostet, Beispiel für ein XML:

PUT http://api.123poi.com/data/poi/api/poi/6587945/
    

 <entry xmlns='http://www.w3.org/2005/Atom' xmlns:poi="http://api.123poi.com/poi/" xmlns:falkgeo="http://api.123poi.com/geo/" 
            xmlns:data="http://api.123poi.com/data/" xmlns:falkmedia="http://api.123poi.com/media/" 
            xmlns:user="http://api.123poi.com/user/">
       <title type='text'>Bewertung anlegen</title>
       <content type='application/atom+xml'>
         <poi:poi>
           <poi:vote>
             <poi:value>10</poi:value>
           </poi:vote>
         </poi:poi>
       </content>
     </entry>
    

Ändern einer Bewertung

Analog zum Anlegen einer Bewertung wird beim Ändern einer Bewertung ein Update auf den POI gemacht. Eine Bewertung sollte zwischen 20 (entspricht ein Stern) und 100 (entspricht 5 Sterne) liegen.

PUT http://api.123poi.com/data/poi/api/poi/6587945/
    

 <entry xmlns='http://www.w3.org/2005/Atom' xmlns:poi="http://api.123poi.com/poi/" xmlns:falkgeo="http://api.123poi.com/geo/" 
            xmlns:data="http://api.123poi.com/data/" xmlns:falkmedia="http://api.123poi.com/media/" 
            xmlns:user="http://api.123poi.com/user/">
       <title type='text'>Bewertung anlegen</title>
       <content type='application/atom+xml'>
         <poi:poi>
           <poi:vote>
             <poi:value>80</poi:value>
           </poi:vote>
         </poi:poi>
       </content>
     </entry>
    

Löschen einer Bewertung

Analog zum Anlegen einer Bewertung wird beim Ändern einer Bwertung ein Update auf den POI gemacht.

 PUT http://api.123poi.com/data/poi/api/poi/6587945/
    

<entry xmlns='http://www.w3.org/2005/Atom' xmlns:poi="http://api.123poi.com/poi/" xmlns:falkgeo="http://api.123poi.com/geo/" 
            xmlns:data="http://api.123poi.com/data/" xmlns:falkmedia="http://api.123poi.com/media/" 
            xmlns:user="http://api.123poi.com/user/">
       <title type='text'>Bewertung anlegen</title>
       <content type='application/atom+xml'>
         <poi:poi>
           <poi:vote>
             <poi:value></poi:value>
           </poi:vote>
         </poi:poi>
       </content>
     </entry>
    

Operationen auf externen POI Kritiken (CRUD)

Anlegen/Ändern von Kritiken

Die Daten, die angelegt werden sollen müssen im entsprechenden XML-Format angegeben und im Request Body mitgegeben werden. Dafür verwendet man ein entprechendes Tool.

Die Daten werden als neuer Eintrag <entry/> gepostet, Beispiel für ein XML:

POST http://api.123poi.com/data/poi/api/poi/6587945/critique/
    

 <entry xmlns='http://www.w3.org/2005/Atom' xmlns:critique="http://api.123poi.com/critique/" xmlns:data="http://api.123poi.com/data/" xmlns:user="http://api.123poi.com/user/">
       <content type='application/atom+xml'>
         <critique:critiquePartnerSummary>
           <critique:summaryUrl>http://www.restaurant-kritik.de/183</critique:summaryUrl>
           <critique:averageScore>3.3</critique:averageScore>
           <critique:numberOfReviews>3</critique:numberOfReviews>
           <critique:partner>
             <user:id>17</user:id>
           </critique:partner>
           <critique:critiques>
             <critique:critique>
               <critique:externalId>187405</critique:externalId>
               <critique:externalServiceId>restaurantkritik_187405</critique:externalServiceId>
               <critique:score>4.0</critique:score>
               <critique:title>Hard Rock Café Berlin</critique:title> 
               <critique:comment>Das "Hard Rock Caf&eacute;" in Berlin ...</critique:comment>
               <critique:url>http://www.restaurant-kritik.de/bewertungen/187405</critique:url>
               <critique:creationDate>1336482056000</critique:creationDate>
               <critique:language>de</critique:language>
             </critique:critique>
           </critique:critiques>
         </critique:critiquePartnerSummary>
       </content>
     </entry>
    

Eine vollständige Beschreibung des Formates findet sich in der Dokumentation des  POI API XML-Schema.

Das Ergebnis dieses Requests teilt die URL mit, unter der der neue Kommentar erreichbar ist.

Abfragen von Kritiken

Es können alle Kritiken eines POIs abgefragt werden. Zusätzlich kann nach Partner (Parameter 'partnerId') und Sprache (Parameter 'lang') gefiltert werden.

Operationen auf Besuchstyp "ich war schon da" oder "hier möchte ich noch hin"

Anlegen einer Besuchstyps für POIs

Die Daten, die angelegt werden sollen müssen im entsprechenden XML-Format angegeben und im Request Body mitgegeben werden. Dafür verwendet man ein entprechendes Tool.

Als Content Type wird application/atom+xml verwendet. Die Daten werden als neuer Eintrag <entry/> gepostet, Beispiel für ein XML:

 POST http://api.123poi.com/data/poi/api/poi/6587945/visited
     
      <entry xmlns='http://www.w3.org/2005/Atom' xmlns:poi="http://api.123poi.com/poi/" xmlns:falkgeo="http://api.123poi.com/geo/" 
           xmlns:data="http://api.123poi.com/data/" xmlns:falkmedia="http://api.123poi.com/media/" 
           xmlns:user="http://api.123poi.com/user/">
      <title type='text'>Bewertung anlegen</title>
      <content type='application/atom+xml'>
        <poi:poi>
            <poi:visitedType>WOULD_LIKE_TO_VISIT</poi:visitedType>
        </poi:poi>
      </content>
    </entry>
    

Ändern eines Besuchstyps für POIs

Beispiel:

 PUT http://api.123poi.com/data/poi/api/poi/6587945/visited
     
      <entry xmlns='http://www.w3.org/2005/Atom' xmlns:poi="http://api.123poi.com/poi/" xmlns:falkgeo="http://api.123poi.com/geo/" 
           xmlns:data="http://api.123poi.com/data/" xmlns:falkmedia="http://api.123poi.com/media/" 
           xmlns:user="http://api.123poi.com/user/">
      <title type='text'>Bewertung anlegen</title>
      <content type='application/atom+xml'>
        <poi:poi>
            <poi:visitedType>ALREADY_BEEN_THERE</poi:visitedType>
        </poi:poi>
      </content>
    </entry>
    

Abfragen welcher User den POI schon besucht hat bzw. noch hin möchte

Anlegen eines Besuchstyps für Destinationen

Die Daten, die angelegt werden sollen müssen im entsprechenden XML-Format angegeben und im Request Body mitgegeben werden. Dafür verwendet man ein entprechendes Tool.

Als Content Type wird application/atom+xml verwendet. Die Daten werden als neuer Eintrag <entry/> gepostet, Beispiel für ein XML:

 POST http://api.123poi.com/data/destination/api/destination/4/visited
     
    <entry xmlns='http://www.w3.org/2005/Atom' xmlns:poi="http://api.123poi.com/poi/" xmlns:falkgeo="http://api.123poi.com/geo/" 
           xmlns:data="http://api.123poi.com/data/" xmlns:falkmedia="http://api.123poi.com/media/" xmlns:user="http://api.123poi.com/user/" xmlns:destination="http://api.123poi.com/destination/">
      <title type='text'>Bewertung anlegen</title>
      <content type='application/atom+xml'>
        <destination:destination>
            <destination:visitedType>WOULD_LIKE_TO_VISIT</destination:visitedType>
        </destination:destination>
      </content>
    </entry>
    

Ändern eines Besuchstyps für Destinationen

Beispiel:

 PUT http://api.123poi.com/data/destination/api/destination/4/visited
     
      <entry xmlns='http://www.w3.org/2005/Atom' xmlns:poi="http://api.123poi.com/poi/" xmlns:falkgeo="http://api.123poi.com/geo/" 
           xmlns:data="http://api.123poi.com/data/" xmlns:falkmedia="http://api.123poi.com/media/" xmlns:user="http://api.123poi.com/user/" xmlns:destination="http://api.123poi.com/destination/">
      <title type='text'>Bewertung anlegen</title>
      <content type='application/atom+xml'>
        <destination:destination>
            <destination:visitedType>ALREADY_BEEN_THERE</destination:visitedType>
        </destination:destination>
      </content>
    </entry>
    

Abfragen welcher User die Destination schon besucht hat bzw. noch besuchen möchte

Abfragen welche POIs und Destinationen ein User bereits besucht hat bzw. noch besuchen möchte

Like It

LikeIt auf einer Contribution setzen

Einzelne Contributions sollen von Benutzern über ein "LikeIt" bewertet werden. Die Contribution wird über den User, die Sprache der Contribution und die PoiId identifiziert. Jeder Benutzer kann eine Contribution nur einmal bewerten. "LikeIt" ist portalübergreifend, d.h. wird eine Contribution auf einem Portal mit "LikeIt" versehen, so ist es auch auf anderen Portalen als "LikeIt" markiert. Beim Abrufen der Contribution wird mitgeliefert wieviele Benutzer diese mögen und ob der aktuell eingeloggte Benutzer sie mag.

Beim Abrufen des Pois stehen die LikeIt-Werte im PoiData-Element:

 <feed xmlns="http://www.w3.org/2005/Atom" xmlns:exif="http://api.123poi.com/exif/" xmlns:poi="http://api.123poi.com/poi/" 
           xmlns:media="http://search.yahoo.com/mrss/" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/">
       <updated>2010-10-29T13:18:09.916Z</updated>
       <link href="http://api.123poi.com/data/poi/api/user/6/poi/115000254" rel="self"/>
       <title type="text">Inhalte eines Benutzers zu einem bestimmten Poi</title>
       <subtitle type="text"/>
       <id>http://api.123poi.com/data/poi/api/user/6/poi/115000254</id>
       <author>
         <name>Falk POI API</name>
       </author>
       <entry>
         ...
         <content type="application/xml">
           <poi:poi xmlns:data="http://api.123poi.com/data/" xmlns:falkgeo="http://api.123poi.com/geo/" 
                    xmlns:falkmedia="http://api.123poi.com/media/" xmlns:user="http://api.123poi.com/user/">
           ...
             <poi:poidata>
               <poi:type>Contribution</poi:type>
               ...
               <data:language>de</data:language>
               ...
               <poi:likedCount>1</poi:likedCount>
               <poi:likes>true</poi:likes>
             </poi:poidata>
             ...
           </poi:poi>
         </content>
       </entry>
     </feed>
    

LikeIt von einer Contribution entfernen

Der angemeldete Benutzer kann sein "LikeIt" von einer Contribution wieder entfernen. Die Contribution wird über den User, die Sprache der Contribution und die PoiId identifiziert.

POIs mit "LikeIt" auf Contribution abfragen

Der angemeldete Benutzer kann alle POIs abfragen, bei deren Contribution er ein "LikeIt" gesetzt hat. Es gelten die normalen Sichtbarkeitsregeln gelten, d.h. wenn der User auf einem anderen Portal eine Contribution mit "LikeIt" versehen hat, dieser POI aber auf einem anderen Portal nicht sichtbar ist, so wird er in diesem Portal nicht angezeigt, wenn der User seine mit "LikeIt" versehenen Contributions abfragt. Blättern, sowie die Einschränkung auf zusätzliche Suchkriterien, wird unterstützt.

Öffnungszeiten

POIs können über Öffungszeiten verfügen.

{
      "entries": [
        {
          ...
          "openingHours": {
            "creationDate": 1544292262086,
            "creationDateFormatted": "2018-12-08 19:04:22 +0100",
            "lastUpdate": 1544292262086,
            "lastUpdateFormatted": "2018-12-08 19:04:22 +0100",
            "nextOpenNowChange": 1550476800000,
            "nextOpenNowChangeFormatted": "2019-02-18 09:00:00 +0100",
            "openNow": false,
            "periods": [
              {
                "close": {
                  "day": 1,
                  "time": "1330"
                },
                "open": {
                  "day": 1,
                  "time": "0900"
                }
              },
              {
                "close": {
                  "day": 3,
                  "time": "1330"
                },
                "open": {
                  "day": 3,
                  "time": "0900"
                }
              },
              {
                "close": {
                  "day": 5,
                  "time": "1330"
                },
                "open": {
                  "day": 5,
                  "time": "0900"
                }
              }
            ]
          },
          ...
        }
      ]
    }

Eine Periode ("periods") beschreibt immer einen Zeitraum zwischen Öffnen ("open") und Schließen ("close"). "day" beschreibt dabei den Wochentag in Form einer Zahl von 0 (Sonntag) bis 6 (Samstag). Der Dienstag wäre dabei eine 2. "time" beschreibt die Uhrzeit in Stunden und Minuten. "1330" steht für 13 Uhr 30 Minuten. "0900" steht für 9 Uhr. Der Tag bei "close" kann vom Tag bei "open" abweichen, z.B. der folgende Wochentag, wenn eine Bar von 19 Uhr bis 3 Uhr nachts geöffnet ist.

Das Feld "openNow" zeigt an, ob der POI aktuell geöffnet ist. Die Felder "nextOpenNowChange" und "nextOpenNowChangeFormatted" zeigen den Zeitpunkt der nächsten Öffnung oder Schließung an, je nachdem, ob der POI aktuell geschlossen oder geöffnet ist.

{
      "entries": [
        {
          ...
          "openingHours": {
            "creationDate": 1547490876871,
            "creationDateFormatted": "2019-01-14 19:34:36 +0100",
            "lastUpdate": 1547490876871,
            "lastUpdateFormatted": "2019-01-14 19:34:36 +0100",
            "open24h": true,
            "openNow": true,
            "periods": [
              {
                ...
              }
            ]
          },
          ...
        }
      ]
    }

Das Feld "open24h" zeigt an, dass der POI an allen Tagen in der Woche 24 Stunden geöffnet hat (24/7). Die angegebenen Perioden sind in diesem Fall nicht relevant.

Über den Anfrage-Parameter "datetime" können Datum und Uhrzeit für die Prüfung der Öffnungszeiten festgelegt werden, z.B. "2017-12-24T16:30:00". Wird der Parameter nicht angegeben, so wird das aktuelle Datum und Uhrzeit verwendet. Das Datumsformat für den Parameter lautet "yyyy-MM-dd'T'HH:mm:ss".

Über die Sortierung "opennow" (via Anfrage-Parameter "sort") können die POIs nach oben sortiert werden, die aktuell bzw. zum angegebenen Zeitpunkt geöffnet haben.

Nach Öffnungszeiten suchen

Über den Anfrage-Parameter "openwhen" kann nach POIs mit bestimmten Öffnungszeiten gesucht werden.

Hinweis: Eine Suche mit "openwhen=1" wird eine Bar, die am Sonntag von 19 Uhr bis 3 Uhr geöffnet hat nicht treffen, eine Suche mit "openwhen=1T0100" hingegen schon.

Info POIs

Info POIs sind POI, die häufigen Änderungen unterliegen, wie zum Beispiel Staumeldungen. Die gelieferten Daten entsprechen im wesentlichen der geo Projektion und enthalten wenige zusätzliche Information. Die Daten sind optimiert für die Anzeige von Objekten in einer Kartenapplikation, wie zum Beispiel der Falk Map API.

Info POIs stehen nur ausgewählten Nutzern der POI API zur Verfügung.

Abfragen der Info POIs nach Kategorien

Die Info POI darf nur nach Kategorien abgefragt werden.

Beispiel für das Abfragen des Info POI:

GET http://api.123poi.com/data/poi/info/all/?cat=1,2
    

Abfragen alle Kategorien von Info POIs

Beispiel für das Abfragen des Info Kategorien List:

Über den folgenden Pfad können alle Kategorien von Info Projection abgefragt werden:

Die Kategorieliste kann als ATOM-Feed oder im JSON-Format ausgegeben werden.

Abfragen eines Info POI nach ihrer Kategorie

Je nach Sichtbarkeit des Info POIs kann mann den POI abfragen.

Beispiel für das Abfragen des POI (bzw. der Contribution):

 GET http://api.123poi.com/data/poi/info/poi/505110034/
    

Verfügbarkeitsanfrage für Booking.com-Hotels

Eine Verfügbarkeitsanfrage wird durchgeführt, sobald der Parameter "rooms" oder "room1" mitgegeben wird. Wird der Parameter "rooms" verwendet, dann werden die Parameter "room1" bis "room30" ignoriert, falls sie ebenfalls angegeben werden. Über die Parameter "room1" bis "room30" ist es möglich, die gewünschte Zimmeraufteilung an Booking.com durchzureichen, jedoch wird diese nicht immer berücksichtigt. Die Werte für den Parameter "rooms" und "room1" bis "room30" sind eine Komma-separierte Liste. Erwachsene Personen werden mit "A" gekennzeichnet. Kinder werden mit ihrem Alter (0-17) angegeben. Zwei Erwachsene, ein 14-jähriges Kind und ein 10-jähriges Kind würden demnach den Wert "A,A,14,10" ergeben.

Die Parameter "checkin" und "checkout" sind optional. Fehlt "checkin", so wird der nächste Tag verwendet. Fehlt "checkout", so wird der übernächste Tag verwendet.

Zusätzliche Attribute bei Verfügbarkeitsanfrage

Bei der Verfügbarkeitsanfrage an Booking.com wird die Contribution um zusätzliche Anzeigeattribute erweitert.

Hervorragend

40

Unterstützte Sortierungen

Spezielle Suchparameter

Neben den normalen Suchen auf den Attributfeldern "hotelamenities" und "roomfacilities" (z.B. "attr=hotelamenities:spaWellnessCentre") unterstützt die Verfügbarkeitsanfrage über spezielle Suchparameter.

Normale Suchparameter

Diese normalen Suchparameter werden beim Booking.com-Import befüllt.

Beispiel für Verfügbarkeitsanfrage von Hotels in Stuttgart: