Back to Home

Media

Dieses Dokument beschreibt die REST-Schnittstellen der Falk POI API bezüglich Medien Objekten.

Inhaltsverzeichnis

Fotos

Ein identifizierter User kann mehrere Bilder zu einem POI hochladen. Es werden automatisch Thumbnails und ein Bild mit maximaler Größe (1024px) angelegt. Diese können über den Filter "photo" und den Parameter "thumbsize" abgefragt werden.

Abfragen der Fotos eines Pois

User Story Ein User kann die Fotos eines POIs abfragen. Optional kann die Suche zudem auf die Fotos eines einzelnen Users beschränkt werden.
HTTP GET
URL

http://api.123poi.com/data/poi/api/poi/16709/?filter=photo

http://api.123poi.com/data/poi/api/poi/16709/?filter=photo&user=13

Als Antwort auf diese Anfrage wird ein Media-RSS zurückgeliefert was als Entries die einzelnen Medienobjekte mit den Mediendetails enthält. Dies sieht zum Beispiel so aus:

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:poi="http://api.123poi.com/poi/" xmlns:exif="http://api.123poi.com/exif/"
          xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:media="http://search.yahoo.com/mrss/"
          xmlns:falkmedia="http://api.123poi.com/media/" xmlns:user="http://api.123poi.com/user" xmlns:falkgeo="http://api.123poi.com/geo/">
       <openSearch:totalResults>1</openSearch:totalResults>
       <openSearch:startIndex>0</openSearch:startIndex>
       <openSearch:itemsPerPage>10</openSearch:itemsPerPage>
       <openSearch:Query role="request" poi:access="VISIBLE" poi:lang="de"/>
       <updated>2010-07-29T12:49:47.460Z</updated>
       <link href="http://api.123poi.comdata/poi/api/poi/16709/?lang=de&filter=photo" rel="self"/>
       <title type="text">Anzeigen der Fotos eines Pois</title>
       <subtitle type="text"/>
       <id>http://api.123poi.com/data/poi/api/poi/16709/?lang=de&filter=photo</id>
       <author>
         <name>Falk POI API</name>
       </author>
       <entry>
         <id>http://api.123poi.com/data/poi/api/poi/16709/media/7357</id>
         <title type="text">1b7f_ddc</title>
         <summary type="text">http://pic.123poi.com/api/content/images/0/1w/hc/es/n/photo-979631.jpg%0Ddescription</summary>
         <author>
           <name>FED</name>
           <uri>http://api.123poi.com/data/poi/api/user/10</uri>
         </author>
         <link href="http://api.123poi.com/data/poi/api/media/7357" rel="alternate"/>
         <link href="http://api.123poi.com/data/poi/api/media/7357" rel="edit"/>
         <media:title>1b7f_ddc.jpg</media:title>
         <media:description/>
         <media:content url="http://pic.123poi.com/api/content/images/0/1w/hc/es/n/photo-979631.jpg" 
             xml:lang="all" type="image/jpeg" medium="photo" width="to be determined"/>
         <exif:tags/>
         <media:credit role="uploader">FED</media:credit>
         <falkgeo:coordinates>
               <falkgeo:lat>48.791599</falkgeo:lat>
               <falkgeo:lon>9.22989</falkgeo:lon>
         </falkgeo:coordinates>
         <falkmedia:visibility>PUBLIC</falkmedia:visibility>
         <falkmedia:mediaHolderId>42</falkmedia:mediaHolderId>
         <falkmedia:mediaHolderType>POI_MEDIA</falkmedia:mediaHolderType>
         <content type="image/jpeg">http://pic.123poi.com/api/content/images/0/1w/hc/es/n/photo-979631.jpg</content>
       </entry>
     </feed>

Das Media-RSS entspricht dem Standart von YAHOO (http://search.yahoo.com/mrss/). Das media:content-Tag enthält alle Informationen zum Bild. Das Attribut url enthält den Pfad zum Abrufen des Bildobjektes.

Abfragen der Fotos eines Users

User Story Ein User kann die Fotos eines Users abfragen
HTTP GET
URL http://api.123poi.com/data/poi/api/user/16709/?filter=photo

Als Antwort auf diese Anfrage entspricht im Aufbau der für Fotos eines POIs.

Abfragen der Fotos einer Destination

User Story Ein User kann die Fotos einer Destination abfragen. Optional kann die Suche zudem auf die Fotos eines einzelnen Users beschränkt werden.
HTTP GET
URL

http://api.123poi.com/data/destination/api/destination/123/?filter=photo

http://api.123poi.com/data/destination/api/destination/123/?filter=photo&user=13

Abfragen der Fotos einer Event Series

User Story Ein User kann die Fotos einer Event Series abfragen
HTTP GET
URL http://api.123poi.com/data/event/api/eventseries/${eventSeriesID/}?filter=photo

Abfragen der Fotos einer Event

User Story Ein User kann die Fotos einer Event abfragen
HTTP GET
URL http://api.123poi.com/data/event/api/event/${eventID/}?filter=photo

Abfragen eines einzelnen Medienobjektes

Die in der Liste gelieferten Medienobjekt können auch einzeln aufgerufen werden. Dazu wird die Id des Entries verwendet, welche den Pfad zum einzelnen Medienobjekt enthält.

User Story Ein User kann das Media-Objekt (Fotos,Video) eines POIs abfragen
HTTP GET
URL

http://api.123poi.com/data/poi/api/poi/16709/media/7357

http://api.123poi.com/data/poi/api/poi/{poi-id}/media/{media-id}

oder

User Story Ein User kann das Media-Objekt direkt abfragen
HTTP GET
URL

http://api.123poi.com/data/poi/api/media/7357

http://api.123poi.com/data/poi/api/media/{media-id}

Das zurückgelieferte XML entspricht dem der Liste der Fotos wie oben beschrieben.

Abfragen von Thumbnails

Will man nicht die maximale Größe des Bildes haben, sondern ein Thumbnail, so kann der Pfad zum Abrufen des Media-RSS um den Parameter "thumsize" erweitert werden. Dabei wird die Größe des Thumbnails sowie ob cropped (c) oder uncropped (u) angegeben: thumbsize=144c

Es kann prinzipiell jede gewünschte Größe angegeben werden, jedoch wird das Bild nicht größer skaliert als das zugrundeliegende Original-Bild. Die Größe der Original-Bilder ist nicht fest vorgegeben und kann stark abweichen.

Bei cropped (c) ist das Bild quadratisch, und die Ränder werden ggf. abgeschnitten. Dabei wird der mittlere Bildausschnitt gewählt, eine gewichtete Auswahl des besten Bildausschnitts findet nicht statt.

Bei uncropped (u) behält das Bild beim Skalieren sein ursprüngliches Seitenverhältnis bei. Die gewünschte Größe bezieht sich immer auf die längere Achse: Bei Hochkantbildern auf die Höhe, bei Querformatbilder auf die Breite.

User Story Ein User kann die Thumbnails eines Medienobjektes abfragen
HTTP GET
URL http://api.123poi.com/data/poi/api/poi/16709/media/7357?filter=photo&thumbsize=144u

oder

User Story Ein User kann die Thumbnails eines Medienobjektes abfragen
HTTP GET
URL http://api.123poi.com/data/poi/api/media/7357?filter=photo&thumbsize=144u

Es wird ein Media-RSS zurückgeliefert, welches im media:thumnail-Tag im Attribut url den Pfad zum Bild enthält, die Link-Element rel="image" wird die original Bild URL gesetzt werden.

 <feed xmlns="http://www.w3.org/2005/Atom" xmlns:poi="http://api.123poi.com/poi/" xmlns:exif="http://api.123poi.com/exif/"
          xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:media="http://search.yahoo.com/mrss/"
          xmlns:falkmedia="http://api.123poi.com/media/" xmlns:user="http://api.123poi.com/user" xmlns:falkgeo="http://api.123poi.com/geo/">
       <openSearch:totalResults>1</openSearch:totalResults>
       <openSearch:startIndex>0</openSearch:startIndex>
       <openSearch:itemsPerPage>10</openSearch:itemsPerPage>
       <openSearch:Query role="request" poi:access="VISIBLE"/>
       <updated>2010-07-30T10:58:04.660Z</updated>
       <link href="http://api.123poi.com" rel="self"/>
       <title type="text">Anzeigen der Fotos eines Pois</title>
       <subtitle type="text"/>
       <id>http://api.123poi.com</id>
       <author>
         <name>Falk POI API</name>
       </author>
       <entry>
         <id>http://api.123poi.com/data/poi/api/poi/16709/media/7357</id>
         <title type="text">c62_d5c.jpg</title>
         <summary type="text">http://pic.123poi.com/api/content//images/0/1w/hc/es/n/t144/c/photo-979631.jpg&#xd;
                   description</summary>
         <author>
           <name>FED</name>
           <uri>http://api.123poi.com/data/poi/api/user/10</uri>
         </author>
         <link href="http://api.123poi.com/data/poi/api/media/7357" rel="alternate"/>
         <link href="http://api.123poi.com/data/poi/api/media/7357" rel="edit"/>
         <link href="http://pic.123poi.com/api/content//images/0/1w/hc/es/n/photo-979631.jpg" rel="image"/>
         <media:title>c62_d5c.jpg</media:title>
         <media:description/>
         <media:thumbnail url="http://pic.123poi.com/api/content//images/0/1w/hc/es/n/t144/c/photo-979631.jpg" width="144"/>
         <exif:tags/>
         <media:credit role="uploader">FED</media:credit>
         <falkgeo:coordinates>
               <falkgeo:lat>48.791599</falkgeo:lat>
               <falkgeo:lon>9.22989</falkgeo:lon>
         </falkgeo:coordinates>
         <falkmedia:visibility>PUBLIC</falkmedia:visibility>
         <content type="image/jpeg">http://pic.123poi.com/api/content//images/0/1w/hc/es/n/t144/c/photo-979631.jpg</content>
       </entry>
     </feed>

Anlegen von Fotos

Fotos können direkt beim Anlegen eines POIs mitgegeben werden oder später zu einem POI angelegt werden. Dazu muss das XML, was die Fotos betrifft sowie die Fotos selbst in einem Multipart Content mitgeliefert werden. Das XML muss als Filename den exakten Dateinamen des mitgelieferten Bildes enthalten. Außerdem muss zwingend der Mediatyp photo gesetzt werden. Titel, Beschreibung und Sprache sind optional.

POI zusammen mit Foto(s) anlegen

User Story Ein User kann Bilder zusammen mit einem POI anlegen
HTTP POST
URL http://api.123poi.com/data/poi/api/poi/

Beispiel-XML:

<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/">
       <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/" xmlns:falkgeo="http://api.123poi.com/geo/">
               <falkmedia:media>
                   <falkmedia:type>photo</falkmedia:type>
                   <data:language>all</data:language>
                   <falkgeo:coordinates>
                          <falkgeo:lat>48.791599</falkgeo:lat>
                          <falkgeo:lon>9.229890</falkgeo:lon>
                   </falkgeo:coordinates>
                   <data:visibility>PUBLIC</data:visibility>
                   <falkmedia:title>Image 1</falkmedia:title>
                   <falkmedia:description>Das erste Bild</falkmedia:description>
                   <falkmedia:filename>image1.jpg</falkmedia:filename>
                   <falkmedia:copyright><a href="http://www.falk.de">Falk.de</a>Copyright</falkmedia:copyright>
                   <falkmedia:photographer>Photographer</falkmedia:photographer>
                   <falkmedia:photoAgency>Agency</falkmedia:photoAgency>
                   <falkmedia:tags>
                       <falkmedia:tag>
                            <data:language>de</data:language>
                            <poi:value>deutsch</poi:value>
                       </falkmedia:tag>
                       <falkmedia:tag>
                            <data:language>en</data:language>
                            <poi:value>english</poi:value>
                       </falkmedia:tag>
                   </falkmedia:tags>
                   <falkmedia:license>
                           <falkmedia:name>Attribution License</falkmedia:name>
                           <falkmedia:url>http://creativecommons.org/licenses/by/2.0/</falkmedia:url>
                   </falkmedia:license>          
               </falkmedia:media>
               <poi:poidata>
                   <poi:type>Contribution</poi:type>
                   <poi:title>Kunsthalle Weishaupt</poi:title>
                   <data:language>de</data:language>
                   <falkgeo:coordinates>
                       <falkgeo:lat>48.397598</falkgeo:lat>
                       <falkgeo:lon>9.99338</falkgeo:lon>
                   </falkgeo:coordinates>
                   <data:address>
                       <data:country>Deutschland</data:country>
                       <data:isoCountryCode>DE</data:isoCountryCode>
                       <data:zip>89073</data:zip>
                       <data:location>Ulm</data:location>
                       <data:subLocation>Mitte</data:subLocation>
                       <data:street>Hans-und-Sophie-Scholl-Platz</data:street>
                       <data:number>1</data:number>
                   </data:address>
                   <data:contact>
                       <data:phone>+49 (0)731 161 43 60</data:phone>
                       <data:fax>+49 (0)731 16 43 65</data:fax>
                       <data:web>http://www.kunsthalle-weishaupt.de</data:web>
                       <data:email>info@kunsthalle-weishaupt.de</data:email>
                   </data:contact>
                   <poi:tags>
                       <poi:tag>
                           <poi:value>Kunst</poi:value>
                       </poi:tag>
                   </poi:tags>
                   <poi:description>Die Kunsthalle wurde von 2005 bis 2007 im Zuge der Neugestaltung der 'Neuen Mitte' erbaut.</poi:description>
               </poi:poidata>
               <data:category>
                    <data:id>2302</data:id>
               </data:category>
           </poi:poi>
       </content>
     </entry>

Bilder hinzufügen zu einem POI

User Story Ein User kann Bilder zu einem POI anlegen
HTTP POST
URL http://api.123poi.com/data/poi/api/poi/4711/media/

Der Upload eines Fotos zu einen POI kann nur für authentifizierte User durchgeführt werden. Der POST Request muss dafür folgende HTTP-Header setzen:

  1. Content-Type: multipart/form-data; boundary="capitano"
  2. Content-length: binary length of data
  3. licensekey: [Request a licensekey]
  4. Authorization: FalkOAuth access_token=[consumerkey],[token],[token secret],HMAC-SHA1

Der BODY des HTTP-Requests folgt den Regeln eines HTTP-Multipart Requests. Für alle gängigen Programmiersprachen existieren Frameworks, die dem Entwickler die Erzeugung eines solchen Requests erleichtern. Beispielhaft könnte der wie folgt aussehen:

 --capitano 
     Content-Disposition: form-data; name="mytext" 
     Content-Type: text/plain 
     
     <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/">
       <content type="application/atom+xml">
         <falkmedia:media xmlns:data="http://api.123poi.com/data/" xmlns:falkmedia="http://api.123poi.com/media/" 
                      xmlns:user="http://api.123poi.com/user/" xmlns:falkgeo="http://api.123poi.com/geo/">
           <falkmedia:type>photo</falkmedia:type>
           <data:language>all</data:language>
           <falkgeo:coordinates>
                 <falkgeo:lat>48.791599</falkgeo:lat>
                 <falkgeo:lon>9.229890</falkgeo:lon>
           </falkgeo:coordinates>
           <data:visibility>PUBLIC</data:visibility>       
           <falkmedia:title>Mercedes Benz Museum</falkmedia:title>
           <falkmedia:description>Mercedes Benz Museum</falkmedia:description>
           <falkmedia:filename>SeiteReagiertnicht.png</falkmedia:filename>
           <falkmedia:photographer>Photographer</falkmedia:photographer>
           <falkmedia:photoAgency>Agency</falkmedia:photoAgency>
           <falkmedia:tags>
                <falkmedia:tag>
                      <data:language>de</data:language>
                      <poi:value>deutsch</poi:value>
                 </falkmedia:tag>
                 <falkmedia:tag>
                      <data:language>en</data:language>
                      <poi:value>english</poi:value>
                 </falkmedia:tag>
          </falkmedia:tags>
          <falkmedia:license>
                 <falkmedia:name>Attribution License</falkmedia:name>
                 <falkmedia:url>http://creativecommons.org/licenses/by/2.0/</falkmedia:url>
          </falkmedia:license>          
         </falkmedia:media>
       </content>
     </entry>
     --capitano 
     Content-Disposition: form-data; name="myfile"; filename="SeiteReagiertnicht.png" 
     Content-Type: image/png
     
     PNG �
     
     IHDR�Èá��{«Õ’�sRGB®Î�é�ýPLTE��;tz#�'5U 7VŠ# #:Y%�ˆ(�–&�-�¢(�œ+ 
     ... more binary data ...
     ��¾×Z"�H€„��H� ���H(P³�²D@^[½tíJ(ƪZZÍAÖÕV-�ÅXK«j�Hºdmmu��cU×®]B ½d-�s-™Í@R:�Š¹�Äÿ�_¢5òR�t$IEND®B`‚
     --capitano--

Zu beachten ist bei obigen Beispiel, dass im ersten Abschnitt der filename

<falkmedia:filename>SeiteReagiertnicht.png</falkmedia:filename>

mit den Angaben zum Bild übereinstimmen muss.

Content-Disposition: form-data; name="will-be-ignored"; filename="SeiteReagiertnicht.png"

Es kann pro Aufruf immer nur ein Bild angelegt werden. Die URL zum erzeugten Bild wird über den Location-Header zurückgegeben.

Bilder hinzufügen zu einer Destination

User Story Ein User kann Bilder zu einer Destination anlegen
HTTP POST
URL http://api.123poi.com/data/destination/api/destination/302/media/

Bilder hinzufügen zu einer Event Series

User Story  Ein User kann Bilder zu einer Event Series anlegen
HTTP POST
URL http://api.123poi.com/data/event/api/eventseries/${eventSeriesID}/media/

Bilder hinzufügen zu einer Event

User Story  Ein User kann Bilder zu einer Event anlegen
HTTP POST
URL http://api.123poi.com/data/event/api/event/${eventID}/media/

Ändern von Fotos

Soll zum Beispiel ein Bild aktualisiert werden oder der Titel oder die Beschreibung verändert werden, so kann ein Update auf ein Medienobjekt gemacht werden. Der Typ eines Medienobjektes kann dabei nicht geändert werden.

User Story Ein User kann die Details eines Medienobjektes ändern
HTTP PUT
URL http://api.123poi.com/data/poi/api/poi/5777/media/2659

oder

User Story Ein User kann die Details eines Medienobjektes ändern
HTTP PUT
URL http://api.123poi.com/data/poi/api/media/2659 
<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/">
       <content type="application/atom+xml">
         <falkmedia:media xmlns:data="http://api.123poi.com/data/" xmlns:falkmedia="http://api.123poi.com/media/" 
                      xmlns:user="http://api.123poi.com/user/" xmlns:falkgeo="http://api.123poi.com/geo/">
           <falkmedia:id>2659</falkmedia:id>
           <falkmedia:type>photo</falkmedia:type>
           <data:language>all</data:language>
           <falkgeo:coordinates>
                <falkgeo:lat>48.791599</falkgeo:lat>
                <falkgeo:lon>9.229890</falkgeo:lon>
           </falkgeo:coordinates>
           <data:visibility>PUBLIC</data:visibility>
           <falkmedia:title>Neuer Titel: Mercedes Benz Museum</falkmedia:title>
           <falkmedia:description>Neue Beschreibung: Mercedes Benz Museum</falkmedia:description>
           <falkmedia:filename>photo-neu.jpg</falkmedia:filename>
           <falkmedia:photographer>Photographer</falkmedia:photographer>
           <falkmedia:photoAgency>Agency</falkmedia:photoAgency>
           <falkmedia:tags>
              <falkmedia:tag>
                     <data:language>de</data:language>
                     <poi:value>deutsch</poi:value>
              </falkmedia:tag>
              <falkmedia:tag>
                     <data:language>en</data:language>
                     <poi:value>english</poi:value>
              </falkmedia:tag>
           </falkmedia:tags>
           <falkmedia:license>
               <falkmedia:name>Attribution License</falkmedia:name>
               <falkmedia:url>http://creativecommons.org/licenses/by/2.0/</falkmedia:url>
           </falkmedia:license>        
         </falkmedia:media>
       </content>
     </entry>
User Story Ein User kann die Details eines Medienobjektes für eine Destination ändern
HTTP PUT
URL http://api.123poi.com/data/destination/api/media/2659

Videos

Beim anlegen von Videos werden momentan folgende Video Provider akzeptiert:

Es kann im XML entweder der Embedded Code eines Videos oder die Browser-Url gesetzt werden.

Abfragen der Videos eines Pois

User Story Ein User kann die Videos eines POIs abfragen. Optional kann die Suche zudem auf die Videos eines einzelnen Users beschränkt werden.
HTTP GET
URL

http://api.123poi.com/data/poi/api/poi/16709/?filter=video

http://api.123poi.com/data/poi/api/poi/16709/?filter=video&user=13

Als Antwort auf diese Anfrage wird ein Media-RSS zurückgeliefert was als Entries die einzelnen Medienobjekte mit den Mediendetails enthält. Dies sieht zum Beispiel so aus:

 <feed xmlns="http://www.w3.org/2005/Atom" xmlns:poi="http://api.123poi.com/poi/" xmlns:exif="http://api.123poi.com/exif/"
          xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:media="http://search.yahoo.com/mrss/"
          xmlns:falkmedia="http://api.123poi.com/media/" xmlns:user="http://api.123poi.com/user" xmlns:falkgeo="http://api.123poi.com/geo/">
       <openSearch:totalResults>1</openSearch:totalResults>
       <openSearch:startIndex>0</openSearch:startIndex>
       <openSearch:itemsPerPage>10</openSearch:itemsPerPage>
       <openSearch:Query role="request" poi:access="VISIBLE"/>
       <updated>2010-08-02T07:54:46.078Z</updated>
       <link href="http://api.123poi.com/data/poi/api/poi/16709?filter=video" rel="self"/>
       <title type="text">Anzeigen der Videos eines Pois</title>
       <subtitle type="text"/>
       <id>http://api.123poi.com/data/poi/api/poi/16709?filter=video</id>
       <author>
           <name>Falk POI API</name>
       </author>
       <entry>
           <id>http://api.123poi.com/data/poi/api/poi/16709/media/MediaId</id>
           <title type="text">Video 1</title>
           <summary type="text">Youtube Video</summary>
           <author>
               <name>Test user6</name>
               <uri>http://api.123poi.com/data/poi/api/user/6</uri>
           </author>
           <link href="http://api.123poi.com/data/poi/api/media/MediaId" rel="alternate"/>
           <link href="http://api.123poi.com/data/poi/api/media/MediaId" rel="edit"/>
           <media:title>Video 1</media:title>
           <media:description>Youtube Video</media:description>
           <media:content url="http://www.youtube.com/v/JFd9JvyFRYo" xml:lang="all" type="video/3gp" medium="video"/>
           <media:thumbnail url="http://img.youtube.com/vi/JFd9JvyFRYo/0.jpg"/>
           <media:credit role="uploader">get owner from youtube video?</media:credit>
           <falkgeo:coordinates>
                 <falkgeo:lat>48.791599</falkgeo:lat>
                 <falkgeo:lon>9.22989</falkgeo:lon>
           </falkgeo:coordinates>
           <falkmedia:visibility>PUBLIC</falkmedia:visibility>
           <falkmedia:mediaHolderId>42</falkmedia:mediaHolderId>
           <falkmedia:mediaHolderType>POI_MEDIA</falkmedia:mediaHolderType>
           <falkmedia:mediaHolderId>42</falkmedia:mediaHolderId>
           <falkmedia:mediaHolderType>POI_MEDIA</falkmedia:mediaHolderType>
           <content type="video/3gp">http://www.youtube.com/v/JFd9JvyFRYo</content
       </entry>
     </feed>

Abfragen der Videos eines Users

User Story Ein User kann die Videos eines Users abfragen
HTTP GET
URL http://api.123poi.com/data/poi/api/user/16709/?filter=video

Als Antwort auf diese Anfrage entspricht im Aufbau der für Videos eines POIs.

Abfragen der Videos einer Destination

User Story Ein User kann die Videos einer Destination abfragen. Optional kann die Suche zudem auf die Videos eines einzelnen Users beschränkt werden.
HTTP GET
URL

http://api.123poi.com/data/destination/api/destination/4/?filter=video

http://api.123poi.com/data/destination/api/destination/4/?filter=video&user=13

Abfragen der Videos einer Event Series

User Story Ein User kann die Videos einer Event Series abfragen
HTTP GET
URL http://api.123poi.com/data/event/api/eventseries/${eventSeriesID/}?filter=video

Abfragen der Videos einer Event

User Story Ein User kann die Videos einer Event abfragen
HTTP GET
URL http://api.123poi.com/data/event/api/event/${eventID/}?filter=video

Abfragen eines einzelnen Videos

Die in der Liste gelieferten Medienobjekte können auch einzeln aufgerufen werden. Dazu wird die Id des Entries verwendet, welche den Pfad zum einzelnen Medienobjekt enthält.

User Story Ein User kann ein einzelnes Video abfragen
HTTP GET
URL http://api.123poi.com/data/poi/api/poi/16709/media/MediaId

oder

User Story Ein User kann ein einzelnes Video abfragen
HTTP GET
URL http://api.123poi.com/data/poi/api/media/16709

Das zurückgelieferte XML entspricht dem der Liste der Videos wie oben beschrieben.

Anlegen eines Videos

Wie bei Fotos auch können Videos sowohl beim Anlegen eines POIs mitgegeben werden als auch später zu einem POI hinzugefügt werden. Der Media-Schnipsel muss dazu im jeweiligen XML analog zu den Fotos eingefügt werden. Zwingende Elemente sind für Videos der Typ 'video' sowie das Feld 'code':

 <media:media>
       <data:language>all</data:language>
       <falkgeo:coordinates>
            <falkgeo:lat>48.791599</falkgeo:lat>
            <falkgeo:lon>9.229890</falkgeo:lon>
       </falkgeo:coordinates>
       <media:title>Video 1</media:title>
       <media:description>Das erste Bild</media:description>
       <media:code>http://www.youtube.com/watch?v=JFd9JvyFRYo</media:code>
       <media:type>video</media:type>
     </media:media>
User Story Ein User kann Videos zusammen mit einem POI anlegen
HTTP POST
URL http://api.123poi.com/data/poi/api/poi/
User Story Ein User kann Videos zu einem POI anlegen
HTTP POST
URL http://api.123poi.com/data/poi/api/poi/16709/media/

Ändern eines Videos

Analog zu Fotos kann ein Video auch nachträglich akutalisiert werden.

User Story Ein User kann ein Video ändern
HTTP PUT
URL http://api.123poi.com/data/poi/poi/poi/api/media/16709

oder

User Story  Ein User kann ein Video ändern
HTTP PUT
URL http://api.123poi.com/data/poi/api/media/16709

Löschen einer Media

User Story Ein User kann eine Media anlegen / ändern / löschen / abrufen (Teil 3: löschen)
HTTP DELETE
URL http://api.123poi.com/data/poi/api/media/{$mediaId}

Prinzipiell ist es so, dass ein User seine Beitrag zu einer Media löschen kann.

Beispiel für das Löschen der Media:

DELETE http://api.123poi.com/data/poi/api/media/5709

Löschen einer Media durch POI Update

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

Ein User kann seine Media durch POI Update löschen.

Beispiel

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

Beispiel-XML:

<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/">
       <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/" xmlns:falkgeo="http://api.123poi.com/geo/">
               <falkmedia:media>      
               </falkmedia:media>
               <poi:poidata>
                   <poi:type>Contribution</poi:type>
                   <poi:title>Kunsthalle Weishaupt</poi:title>
                   <data:language>de</data:language>
                   <falkgeo:coordinates>
                       <falkgeo:lat>48.397598</falkgeo:lat>
                       <falkgeo:lon>9.99338</falkgeo:lon>
                   </falkgeo:coordinates>
                   <data:address>
                       <data:country>Deutschland</data:country>
                       <data:isoCountryCode>DE</data:isoCountryCode>
                       <data:zip>89073</data:zip>
                       <data:location>Ulm</data:location>
                       <data:subLocation>Mitte</data:subLocation>
                       <data:street>Hans-und-Sophie-Scholl-Platz</data:street>
                       <data:number>1</data:number>
                   </data:address>
                   <data:contact>
                       <data:phone>+49 (0)731 161 43 60</data:phone>
                       <data:fax>+49 (0)731 16 43 65</data:fax>
                       <data:web>http://www.kunsthalle-weishaupt.de</data:web>
                       <data:email>info@kunsthalle-weishaupt.de</data:email>
                   </data:contact>
                   <poi:description>Die Kunsthalle wurde von 2005 bis 2007 im Zuge der Neugestaltung der 'Neuen Mitte' erbaut.</poi:description>
               </poi:poidata>
               <data:category>
                    <data:id>2302</data:id>
               </data:category>
           </poi:poi>
       </content>
     </entry>

Suchen nach Medienobjekten

User Story Ein User kann nach Medienobjekten suchen. Als Suchparameter stehen aktuell search und tag zur Verfügung. Wird kein Suchparameter angegeben, dann werden alle sichtbaren Media-Objekte zurückgegeben. Das Blättern in der Ergebnismenge wird unterstützt.
HTTP GET
URL http://api.123poi.com/data/poi/api/media/all?search=Burg&tag=Sehenswert

Der Suchparameter search bezieht sich nur auf den Titel und die Tags des Media-Objekts, nicht auf den Beschreibungstext. Es werden die Titel in allen Sprachen durchsucht.

Als privat markierte Medienobjekte sind nur für den Benutzer sichtbar, der das Medienobjekt angelegt hat. Medienobjekte eines Benutzers, dessen ProvidedChannel für den Customer nicht sichtbar ist, werden nicht ausgeliefert.

Die Ergebnisse können nach Relevanz (sort=rel (default)) oder nach Erstellungsdatum (sort=date (aktuellste Bilder zuerst)) sortiert werden.

Sperrung eines Medienobjekten

User Story Ein Permission User kann ein Media inaktiv setzen
HTTP POST
URL http://api.123poi.com/data/poi/api/media/16709/inactive?reason=the reson to inactive

Der Redakteur kann ein Media inaktiv setzen, dann wird das Media nicht mehr angezeigt, aber nicht von der Datenbank löschen.

Media Suche auf Tags

User Story AnyUser sucht nach allen Tags von Meidas, die mit einem Begriff als Suchwort gefunden werden. Es werden alle für AnyUser sichtbaren Tags der gefundenen Media zurückgeliefert.
HTTP GET
URL http://api.123poi.com/data/poi/api/media/all/?filter=tag&search=Museen

Es wird eine Liste von Tags ausgegeben, die mit Media verknüpft sind, die der Suche entsprechen. Die Anzahl des Auftretens der Tags wird mit ausgegeben.

Einschränkung der Medias auf Customer

User Story Ein User kann die Fotos eines hochgeladende Customer abfragen
HTTP GET
URL http://api.123poi.com/data/poi/api/customer/1?filter=photo

Es wird Fotos auf den Customer einzuschränken (z.B. hochgeladen auf Marco Polo).

User Story Ein User kann die Fotos eines hochgeladende Customer abfragen
HTTP GET
URL http://api.123poi.com/data/poi/api/customer/1?filter=video

Es wird videos auf den Customer einzuschränken (z.B. hochgeladen auf Marco Polo).

Einschränkung der Medias auf Marken-Channel

User Story Ein User kann die Medias nach Marken-Channel (brand) abfragen.
HTTP GET
URL http://api.123poi.com/data/poi/api/media/all/?brand=2,3

Die Medias können auf einen Marken-Channel (brand) eingeschränkt werden.

Einschränkung der Media-Suche auf Typ der Verknüpfung

User Story Ein User kann die Media-Suche auf den Typ ihrer Verknüpfung einschränken. So können z.B. die Suche auf Media-Objekte beschränkt werden, die einem POI zugeordnet sind. Dies kann man z.B. für Bildergallerien der neusten Bilder von POIs und Destinationen verwenden, um Bilder von Produkten oder Angeboten auszuschließen.
HTTP GET
URL

http://api.mairdumont.com/data/poi/api/media/all?mediaholder=poi,destination

http://api.mairdumont.com/data/poi/api/media/all?mediaholder=0,1

Es können mehrere Typen angegeben werden, indem sie durch Kommas voneinander getrennt werden. Es können die Kürzel oder die IDs übergeben werden.

Kürzel ID Beschreibung
POI 0 Media-Objekte, die mit POIs verknüpft sind.
DESTINATION 1 Media-Objekte, die mit Destinationen verknüpft sind.
EVENT 2 Media-Objekte, die mit Events verknüpft sind.
EVENT_SERIES 3 Media-Objekte, die mit Eventserien verknüpft sind.
PRODUCT 4 Media-Objekte, die mit Produkten (z.B. Reiseführen, Bildbände, Apps, e-Books) verknüpft sind.
OFFER 5 Media-Objekte, die mit Angeboten (z.B. Rent-A-Guide) verknüpft sind.

Einschränkung der Media-Suche auf Mindestgröße und Bildausrichtung

User Story Ein User kann die Media-Suche auf die Mindestgröße, die Mindestbreite oder die Bildausrichtung (Orientierung) des Original-Bildes einschränken.
HTTP GET
URL http://api.mairdumont.com/data/poi/api/media/all?lang=de&orientation=portrait&minwidth=400&minheight=800
http://api.mairdumont.com/data/poi/api/destination/5618?lang=de&filter=photo&orientation=landscape
http://api.mairdumont.com/data/poi/api/poi/115000162?lang=de&filter=photo&orientation=landscape

Die mögliche Werte für den Parameter "orientation" sind "landscape", "portrait" und "square".

Like It

LikeIt auf Media setzen

Einzelne Media-Objekte können von angemeldeten Benutzern mit einem "LikeIt" markiert werden. "LikeIt" ist portalübergreifend, d.h. wird eine Media-Objekt auf einem Portal mit "LikeIt" versehen, so ist es auch auf anderen Portalen als "LikeIt" markiert. Beim Abrufen des Media-Objektes wird mitgeliefert wieviele Benutzer diese mit "LikeIt" markiert haben und auch ob der aktuell eingeloggte Benutzer sie sie markiert hat.

User Story Ein User kann ein Media-Objekt mit "LikeIt" markieren.
HTTP POST
URL http://api.mairdumont.com/data/poi/api/media//likeit

Beim Abrufen des Media-Objekt stehen die LikeIt-Werte im Ergebnis. Unter "likedCount" steht die Anzahl der Personen, welche dieses Media-Objekt mit "LikeIt" versehen haben. Unter "liked" steht, ob der aktuell angemeldete Benutzer das Media-Objekt mit "LikeIt" versehen hat.

{
    
        "id": 5755895,
    
        "author": { "id": 30, "name": "hotel.de" },
    
        "type": "photo",
    
        "language": "all",
    
        "visibility": "PUBLIC",
    
        "title": "346756_577135_634948161268608943",
    
        "filename": "hotelde_346756_7.jpg",
    
        "url": "http://pic.123poi.com/api/content/images/image/0/3/fd/9z/t1024/c/photo-5755895.jpg",
    
        "customer": { "id": 10, "name": "123poi.com"},
    
        "mimeType": "image/jpeg",
    
        "thumbUrl": "http://pic.123poi.com/api/content/images/image/0/3/fd/9z/t144/c/photo-5755895.jpg",
    
        "defaultImageUrl": "http://pic.123poi.com/api/content/images/image/0/3/fd/9z/t1024/c/photo-5755895.jpg",
    
        "license": { "id": 5, "name": "Partner License", "url": "www.signonservice.com/lizenzen/" },
    
        "creationDate": 1381252302862,
    
        "creationDateFormatted": "2013-10-08 19:11:42 +0200",
    
        "lastUpdate": 1381252302862,
    
        "lastUpdateFormatted": "2013-10-08 19:11:42 +0200",
    
        "mediaHolderId": 117438819,
    
        "mediaHolderType": "POI_MEDIA",
    
        "mediaHolderName": "Hotel El Cabo",
    
        "likedCount": 3,
    
        "likes": true
    
    }

LikeIt von Media entfernen

Der angemeldete Benutzer kann sein "LikeIt" von einem Media-Objekt wieder entfernen.

User Story Ein User kann sein "LikeIt" von einem Media-Objekt entfernen.
HTTP DELETE
URL http://api.mairdumont.com/data/poi/api/media//likeit

Media mit "LikeIt" abfragen

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

User Story Ein User kann alle Media-Objekte abfragen, bei denen er ein "LikeIt" gesetzt hat.
HTTP GET
URL http://testapi.mairdumont.com/data/poi/api/media/likeit?lang=de

Abfragen der externer Fotos (z.B. Flickr) einer Destination

User Story Ein User kann die Fotos externer Anbieter einer Destination abfragen.
HTTP GET
URL http://api.123poi.com/data/destination/api/destination/123/?filter=externalphoto

Als Antwort auf diese Anfrage wird ein Media-RSS zurückgeliefert was als Entries die einzelnen Medienobjekte mit den Mediendetails enthält. Dies sieht zum Beispiel so aus:

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:product="http://api.123poi.com/product/"
        xmlns:poi="http://api.123poi.com/poi/" xmlns:exif="http://api.123poi.com/exif/"
        xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:data="http://api.123poi.com/data/"
        xmlns:purchase="http://api.123poi.com/purchase/" xmlns:user="http://api.123poi.com/user"
        xmlns:media="http://search.yahoo.com/mrss/" xmlns:falkmedia="http://api.123poi.com/media/"
        xmlns:falkgeo="http://api.123poi.com/geo/">
        <openSearch:totalResults>12</openSearch:totalResults>
        <openSearch:startIndex>0</openSearch:startIndex>
        <openSearch:itemsPerPage>1</openSearch:itemsPerPage>
        <openSearch:Query role="request" poi:access="VISIBLE"/>
        <updated>2014-06-03T08:54:51.702Z</updated>
        <link
            href="http://testapi.123poi.com/data/poi/api/destination/19850?filter=externalphoto&amp;itemsperpage=1"
            rel="self"/>
        <title type="text"/>
        <subtitle type="text"/>
        <id>http://testapi.123poi.com/data/poi/api/destination/19850?filter=externalphoto&amp;itemsperpage=1</id>
        <author>
            <name>Falk POI API</name>
        </author>
        <openSearch:searchtime>56</openSearch:searchtime>
        <entry>
            <id>http://testapi.123poi.com/data/poi/api/media/18267804</id>
            <title type="text">An der Alb</title>
            <summary type="text">http://farm5.staticflickr.com/4074/4951729877_089b582a12_b.jpg&#xd; </summary>
            <author>
                <name>Flickr</name>
                <uri>http://testapi.123poi.com/data/poi/api/user/58</uri>
                <user:id>58</user:id>
            </author>
            <published>2014-06-02T12:12:44.082Z</published>
            <updated>2014-06-02T12:12:44.082Z</updated>
            <link href="http://testapi.123poi.com/data/poi/api/externalmedia/18267804" rel="alternate"/>
            <link href="http://testapi.123poi.com/data/poi/api/externalmedia/18267804" rel="edit"/>
            <media:title>An der Alb</media:title>
            <media:description/>
            <exif:tags/>
            <media:credit role="photographer">Chez Eskay</media:credit>
            <media:license type="text/html" href="http://creativecommons.org/licenses/by-nc-nd/2.0/"
                >Attribution License</media:license>
            <falkmedia:tags>
                <falkmedia:tag>
                    <data:language>all</data:language>
                    <poi:value>ettlingen</poi:value>
                </falkmedia:tag>
                <falkmedia:tag>
                    <data:language>all</data:language>
                    <poi:value>badenwürttemberg</poi:value>
                </falkmedia:tag>
                <falkmedia:tag>
                    <data:language>all</data:language>
                    <poi:value>karlsruhe</poi:value>
                </falkmedia:tag>
            </falkmedia:tags>
            <falkgeo:coordinates>
                <falkgeo:lat>48.941836</falkgeo:lat>
                <falkgeo:lon>8.40792</falkgeo:lon>
            </falkgeo:coordinates>
            <falkmedia:mediaHolderId>19850</falkmedia:mediaHolderId>
            <falkmedia:mediaHolderType>DESTINATION_MEDIA</falkmedia:mediaHolderType>
    
           <falkmedia:uploadDate>1401711164082</falkmedia:uploadDate>
            <falkmedia:creationDate>1401711164082</falkmedia:creationDate>
            <falkmedia:lastUpdate>1401711164082</falkmedia:lastUpdate>
    
            <falkmedia:externalId>4768990<falkmedia:externalId>
    
            <falkmedia:externalProvider>flickr</falkmedia:externalProvider>
            <content type="application/xml"/>
        </entry>
    </feed>

Abfragen eines einzelnen externen Photos

User Story Ein User kann ein einzelnes externes Photo direkt abfragen
HTTP GET
URL

http://api.123poi.com/data/poi/api/externalmedia/7357

http://api.123poi.com/data/poi/api/externalmedia/{external-media-id}

Abfragen von Thumbnails

Will man nicht die default Größe des Bildes haben, sondern ein Thumbnail, so kann der Pfad zum Abrufen des externen Phoptos um den Parameter "thumsize" erweitert werden. Da nicht alle Anbieter die selben Bildgrößen unterstützen, liefert die API, falls die entsprechende Größe nicht gefunden werden kann, das nächts größe  Bild aus.

Die folgende Tabelle gibt einen Überblick über die vohandenen Bildgrößen der unterschiedlichen Anbieter.

Flickr
Booking.com

75

100

150

240

320

500

800

1024

60

300

500

Suchen nach externen Photos

User Story Ein User kann nach externen Photos suchen. Als Suchparameter stehen aktuell search und tag zur Verfügung.Wird kein Suchparameter angegeben, dann werden alle sichtbaren Media-Objekte zurückgegeben. Das Blättern in der Ergebnismenge wird unterstützt.
HTTP GET
URL http://api.123poi.com/data/poi/api/externalmedia/all?search=Burg&tag=Sehenswert

Der Suchparameter search bezieht sich nur auf den Titel und die Tags des externen Photos, nicht auf den Beschreibungstext. Es werden die Titel in allen Sprachen durchsucht.

Fotos, dessen ProvidedChannel für den Customer nicht sichtbar ist, werden nicht ausgeliefert.

Die Ergebnisse können nach Relevanz (sort=rel (default)) oder nach Erstellungsdatum (sort=date (aktuellste Bilder zuerst)) sortiert werden.

Tags von externen Photos

User Story Ein User sucht nach allen Tags von externer Photos, die mit einem Begriff als Suchwort gefunden werden. Es werden alle sichtbaren Tags der gefundenen Photos zurückgeliefert.
HTTP GET
URL http://api.123poi.com/data/poi/api/externalmedia/all/?filter=tag&search=Museen

Es wird eine Liste von Tags ausgegeben, die mit Media verknüpft sind, die der Suche entsprechen. Die Anzahl des Auftretens der Tags wird mit ausgegeben.