Back to Home

Folder

Dieses Dokument beschreibt die Operationen auf Folder.

Inhaltsverzeichnis

Anlegen eines Folders

User Story Ein User kann einen Folder anlegen / ändern / löschen / abrufen (Teil 1: anlegen)
HTTP POST
URL http://api.123poi.com/data/poi/api/user/$userId/folder/

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, Anregungen findet man unter dem Thema RESTFul Webservices testen. Es gibt verschiedene Folder Typen:

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

Normaler Folder

POST http://api.123poi.com/data/poi/api/user/6/folder/
     
     <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:user="http://api.123poi.com/user/">
       <title type='text'>Normaler Folder</title>
       <content type='application/atom+xml'>
         <poi:folder>
           <poi:type>folder</poi:type>
           <data:visibility>PUBLIC</data:visibility>
           <data:language>de</data:language>
           <poi:title>Normaler Folder</poi:title>
           <poi:externalId>falk-favorite</poi:externalId>
          </poi:folder>
       </content>
     </entry>

Speichern einer Suche

Folgende Suchfelder können aktuell unter <poi:searchParams> angegeben werden:

Zudem sollte die Sprache für die Ausgabe gewählt werden:

Die gewünschte Sortierung kann auch gespeichert werden:

Boundingbox-Suche:

POST http://api.123poi.com/data/poi/api/user/6/folder/
     
    <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:user="http://api.123poi.com/user/">
       <title type='text'>Gespeicherte Suche</title>
       <content type='application/atom+xml'>
         <poi:folder>
           <poi:parentFolderId>1</poi:parentFolderId>
           <poi:type>search</poi:type>
           <data:visibility>PUBLIC</data:visibility>
           <data:language>de</data:language>
           <poi:title>Gespeicherte Suche nach Stadt</poi:title>
           <poi:searchParams>
             <data:search>Restaurant</data:search>
             <falkgeo:boundingBox>
               <falkgeo:northwest>
                 <falkgeo:lat>48.8979</falkgeo:lat>
                 <falkgeo:lon>2.273</falkgeo:lon>
               </falkgeo:northwest>
               <falkgeo:southeast>
                 <falkgeo:lat>48.8182</falkgeo:lat>
                 <falkgeo:lon>2.413</falkgeo:lon>
               </falkgeo:southeast>
             </falkgeo:boundingBox>
             <data:loc>Paris</data:loc>
           </poi:searchParams>
           <poi:externalId>falk-favorite</poi:externalId>
          </poi:folder>
       </content>
     </entry>

Umkreis-Suche:

 POST http://api.123poi.com/data/poi/api/user/6/folder/
     
     <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:user="http://api.123poi.com/user/">
         <content type='application/atom+xml'>
             <poi:folder>
                 <poi:type>search</poi:type>
                 <data:visibility>PUBLIC</data:visibility>
                 <data:language>de</data:language>   <!-- Dieses Tag macht aktuell (24.10.2012) Probleme und führt dazu, dass kein Titel gespeichert wird!) -->
                 <poi:title>Gespeicherte Umkreissuche</poi:title>
                 <poi:searchParams>
                     <data:perimeterSearch>
                         <falkgeo:center>
                             <falkgeo:lat>37.335118</falkgeo:lat>
                             <falkgeo:lon>-122.032435</falkgeo:lon>
                         </falkgeo:center>
                         <falkgeo:distance>15000</falkgeo:distance>
                     </data:perimeterSearch>
                 </poi:searchParams>
             </poi:folder>
         </content>
     </entry>

Suche nach Kategorie und Channel:

POST http://api.123poi.com/data/poi/api/user/6/folder/
     
     <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:user="http://api.123poi.com/user/">
       <title type='text'>Gespeicherte Suche</title>
       <content type='application/atom+xml'>
         <poi:folder>
           <poi:parentFolderId>1</poi:parentFolderId>
           <poi:type>search</poi:type>
           <data:visibility>PUBLIC</data:visibility>
           <data:language>de</data:language>
           <poi:title>Gespeicherte Suche nach Stadt</poi:title>
           <poi:searchParams>
              <data:channel>1</data:channel>
              <data:channel>3</data:channel>
              <data:cat>2203</data:cat>
              <data:cat>2204</data:cat>
           </poi:searchParams>
           <poi:externalId>falk-favorite</poi:externalId>
          </poi:folder>
       </content>
     </entry>

POI Liste

Beim Anlegen einer POI-Liste ist es möglich die POI-Referenzen zu setzen.

 POST http://api.123poi.com/data/poi/api/user/6/folder/
     
     <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:user="http://api.123poi.com/user/">
       <title type='text'>Manuelle Lieblingsliste</title>
       <content type='application/atom+xml'>
         <poi:folder>
           <poi:parentFolderId>1</poi:parentFolderId>
           <poi:type>list</poi:type>
           <data:visibility>PUBLIC</data:visibility>
           <poi:pois>
              <poi:poi>
                 <poi:poiId>120459027</poi:poiId>
              </poi:poi>
              <poi:poi>
                 <poi:poiId>120459024</poi:poiId>
              </poi:poi>
           </poi:pois>
           <data:language>de</data:language>
           <poi:title>Manuelle Liste</poi:title>
           <poi:shortDescription>Kurzbeschreibung</poi:shortDescription>
           <poi:externalId>falk-favorite</poi:externalId>
         </poi:folder>
       </content>
     </entry>

POI Tour

Note: @deprecated Dieser Typ wird in zukünftigen Versionen der Falk POI API entfernt. Stattdessen wird dringend empfohlen, das TourFolder Objekt der Touren zu verwenden, siehe dazu die Schnittstellen Touren.

**
**

POST http://api.123poi.com/data/poi/api/user/6/folder/
     
     <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:user="http://api.123poi.com/user/">
       <title type='text'>Manuelle Lieblingsliste</title>
       <content type='application/atom+xml'>
         <poi:folder>
           <poi:parentFolderId>1</poi:parentFolderId>
           <poi:type>tour</poi:type>
           <data:visibility>PUBLIC</data:visibility>
           <data:language>de</data:language>
           <poi:title>Manuelle Liste</poi:title>
           <poi:shortDescription>Kurzbeschreibung</poi:shortDescription>
           <poi:externalId>falk-favorite</poi:externalId>
           <poi:duration>120</poi:duration>
         </poi:folder>
       </content>
     </entry>

Die Dauer wird in Minuten angegeben.

Bookmark

POST http://api.123poi.com/data/poi/api/user/6/folder/
     
     <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:user="http://api.123poi.com/user/">
       <title type='text'>Manuelle Lieblingsliste</title>
       <content type='application/atom+xml'>
         <poi:folder>
           <poi:type>bookmark</poi:type>
           <data:visibility>PUBLIC</data:visibility>
           <data:language>de</data:language>
           <poi:title>Manuelle Liste</poi:title>
           <poi:bookmarkPoiListId>3</poi:bookmarkPoiListId>
           <poi:externalId>falk-favorite</poi:externalId>
         </poi:folder>
       </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 Folder erreichbar ist.

Ändern eines Folders

Alle POIs eines Folders ändern

User Story Ein User kann einen Folder anlegen / ändern / löschen / abrufen (Teil 2: ändern)
HTTP PUT
URL http://api.123poi.com/data/poi/api/user/UserId/folder/FolderId

Für diese Operation wird ein HTTP-PUT Request verwendet, der Pfad dieser Operation verweist auf den Folder mit seiner ID.

PUT http://api.123poi.com/data/poi/api/user/6/folder/123456
     
     <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:user="http://api.123poi.com/user/">
       <title type='text'>Gespeicherte Suche</title>
       <content type='application/atom+xml'>
         <poi:folder>
           <poi:parentFolderId>1</poi:parentFolderId>
           <poi:type>search</poi:type>
           <data:visibility>PUBLIC</data:visibility>
           <data:language>de</data:language>
           <poi:title>Geänderte Suche nach Stadt</poi:title>
           <poi:searchParams>
             <data:loc>London</data:loc>
           </poi:searchParams>
          </poi:folder>
       </content>
     </entry>

Bei POI-Listen kann, mit einem Update der POI-Referenzen, die Reihenfolge der POIs geändert werden. Sollen POI-Referenzen geändert werden, müssen alle POIs, die in der Liste enthalten sein sollen, in der gewollten Reihenfolge angegeben werden.

<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:user="http://api.123poi.com/user/">
      <title type='text'>Manuelle Lieblingsliste</title>
      <content type='application/atom+xml'>
        <poi:folder>
          <poi:parentFolderId>1</poi:parentFolderId>
          <poi:type>tour</poi:type>
          <data:visibility>PUBLIC</data:visibility>
          <poi:pois>
             <poi:poi>
                <poi:poiId>120459027</poi:poiId>
             </poi:poi>
             <poi:poi>
               <poi:poiId>120459024</poi:poiId>
             </poi:poi>
          </poi:pois>
          <data:language>de</data:language>
          <poi:title>Manuelle Liste</poi:title>
          <poi:shortDescription>Kurzbeschreibung</poi:shortDescription>
          <poi:externalId>falk-favorite</poi:externalId>
          <poi:duration>120</poi:duration>
        </poi:folder>
      </content>
    </entry>

Hinzufügen/Löschen einzelner POIs zu eine Folder

Zum Hinzufügen und Löschen von POIs zu/aus einem Folder(type=LIST) werden die POIs über ihre ID angegeben, die hinzugefügt bzw. gelöscht werden sollen. Beim Hinzufügen von POIs, bleiben POIs die bereits der Liste hinzugefügt worden sind erhalten.

PUT http://api.123poi.com/data/poi/api/user/6/folder/4/add
    PUT http://api.123poi.com/data/poi/api/user/6/folder/4/remove
    
<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:user="http://api.123poi.com/user/">
       <title type='text'>Hinzufügen von POIs</title>
       <content type='application/atom+xml'>
         <poi:folder >
           <poi:id>4</poi:id>
           <poi:type>list</poi:type>
           <data:visibility>PUBLIC</data:visibility>
           <poi:title>POI Liste mit Pois</poi:title>
           <poi:pois>
             <poi:poi>
               <poi:poiId>4001104140</poi:poiId>
             </poi:poi>
             <poi:poi>
               <poi:poiId>400110414031</poi:poiId>
             </poi:poi>
           </poi:pois>
         </poi:folder>
       </content>
     </entry>

Löschen

Löschen eines Folders

User Story Ein User kann einen Folder anlegen / ändern / löschen / abrufen (Teil 3: löschen)
HTTP DELETE
URL http://api.123poi.com/data/poi/api/user/UserId/folder/FolderId

Folder können vom Besitzer des Folders gelöscht werden. Wird ein Parent Folder gelöscht werden alle enthaltenen Folder ebenfalls gelöscht.

 DELETE http://api.123poi.com/data/poi/api/user/6/folder/1

Löschen eines Folders nach Sprache

User Story Ein User kann einen Folder anlegen / ändern / löschen / abrufen (Teil 3: löschen)
HTTP DELETE
URL http://api.123poi.com/data/poi/api/user/UserId/folder/FolderId?lang=${language}

Folder können vom Besitzer des Folders nach Sprache gelöscht werden. Wird ein Parent Folder gelöscht werden alle enthaltenen Folder ebenfalls gelöscht.

 DELETE http://api.123poi.com/data/poi/api/user/6/folder/1?lang=de

Folder abfragen

Abfragen der POIs eines Folder

User Story Ein User kann einen Folder anlegen / ändern / löschen / abrufen (Teil 4: abfragen)
HTTP GET
URL http://api.123poi.com/data/poi/api/user/UserId/folder/FolderId
http://api.123poi.com/data/poi/api/folder/FolderId

Die POIs eines Folders können je nach Sichtbarkeit von Gästen, authentifizierten Usern und dem Besitzer abgefragt werden.

 GET http://api.123poi.com/data/poi/api/user/6/folder/1

Die POIs eines Folders können nach Sprache des Folders abgefragt werden.

GET http://api.123poi.com/data/poi/api/user/6/folder/1?lang=de

Die POIs eines Folders können auch ohne User-Id direkt abgefragt werden.

GET http://api.123poi.com/data/poi/api/folder/1

Abfragen der POIs eines Folder über die externalID

User Story Als Lizenznehmer möchte ich die Favoriten-Liste des Users einfach erkennen können, diese soll über eine einheitliche Kennung angelegt und abgefragt werden können.
HTTP GET
URL http://api.123poi.com/data/poi/api/user/UserId/folder/external/ExternalId

Folder mit spezieller Bedeuting von seiten des Portals können über Benutzer-ID und externe ID eindeutig identifiert werden.

GET http://api.123poi.com/data/poi/api/user/6/folder/external/falk-favorite

Abfragen der Folder eines Benutzers

User Story   Ein User kann die Folder eines Benutzers abfragen
HTTP GET
URL http://api.123poi.com/data/poi/api/user/UserID/?filter=folder

Die POIs eines Folders können je nach Sichtbarkeit von Gästen, authentifizierten Usern und dem Besitzer abgefragt werden.

 GET http://api.123poi.com/data/poi/api/user/6/?filter=folder

Folder abfragen, der einen bestimmten POI enthält

User Story Ein User kann die POI in welchen Folders abfragen.
HTTP GET
URL http://api.123poi.com/data/poi/api/poi/12345/?filter=folder

Relationen für Folder

Anlegen die Verknüpfung zwischen Destination und Folder

POST http://api.123poi.com/data/poi/api/user/6/folder/
     
     <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:user="http://api.123poi.com/user/" xmlns:destination="http://api.123poi.com/destination/">
       <title type='text'>Manuelle Lieblingsliste</title>
       <content type='application/atom+xml'>
         <poi:folder>
           <poi:parentFolderId>1</poi:parentFolderId>
           <poi:type>tour</poi:type>
           <data:visibility>PUBLIC</data:visibility>
           <poi:title>Manuelle Liste</poi:title>
           <poi:shortDescription>Kurzbeschreibung</poi:shortDescription>
           <poi:externalId>falk-favorite</poi:externalId>
           <poi:duration>120</poi:duration>
            <destination:destinations>
            <destination:destination>
               <destination:destinationId>302</destination:destinationId>
             </destination:destination>
             <destination:destination>
               <destination:destinationId>404</destination:destinationId>
             </destination:destination>
           </destination:destinations>
         </poi:folder>
       </content>
     </entry>

Ändern die Verknüpfung zwischen Destination und Folder

Für diese Operation wird ein HTTP-PUT Request verwendet, der Pfad dieser Operation verweist auf den Folder mit seiner ID.

 PUT http://api.123poi.com/data/poi/api/user/6/folder/123456
     
     <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:user="http://api.123poi.com/user/" xmlns:destination="http://api.123poi.com/destination/">
       <title type='text'>Gespeicherte Suche</title>
       <content type='application/atom+xml'>
         <poi:folder>
           <poi:parentFolderId>1</poi:parentFolderId>
           <poi:type>tour</poi:type>
           <data:visibility>PUBLIC</data:visibility>
           <poi:title>Geänderte Suche nach Stadt</poi:title>
           <poi:shortDescription>Kurzbeschreibung</poi:shortDescription>
           <poi:externalId>falk-favorite</poi:externalId>
           <poi:duration>120</poi:duration>
            <destination:destinations>
            <destination:destination>
               <destination:destinationId>302</destination:destinationId>
             </destination:destination>
           </destination:destinations>
         </poi:folder>
       </content>
     </entry>

Löschen die Verknüpfung zwischen Destination und Folder

Für diese Operation wird ein HTTP-PUT Request verwendet, der Pfad dieser Operation verweist auf den Folder mit seiner ID.

PUT http://api.123poi.com/data/poi/api/user/6/folder/123456
     
     <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:user="http://api.123poi.com/user/" xmlns:destination="http://api.123poi.com/destination/">
       <title type='text'>Gespeicherte Suche</title>
       <content type='application/atom+xml'>
         <poi:folder>
           <poi:parentFolderId>1</poi:parentFolderId>
           <poi:type>tour</poi:type>
           <data:visibility>PUBLIC</data:visibility>
           <poi:title>Geänderte Suche nach Stadt</poi:title>
           <poi:shortDescription>Kurzbeschreibung</poi:shortDescription>
           <poi:externalId>falk-favorite</poi:externalId>
           <poi:duration>120</poi:duration>
            <destination:destinations>
           </destination:destinations>
         </poi:folder>
       </content>
     </entry>