Indexing a PhotoDeck website's content

Overview

This scheme makes available, under a single URL, an XML file containing the details of media (images, videos, documents) publicly accessible on a given website.

Content in protected (hidden or password/login-protected galleries) is excluded. The file is automatically updated within a few hours following content update.

File format

The file PhotoDeck will return for a given website has the following format:

<?xml version="1.0" encoding="UTF-8"?>
<reply>
  <medias>
    <media>
      <uuid>80faf08a-031e-11e1-81a2-0019e3fffe1a</uuid>
      <file-name>file.jpg</file-name>
      <mime-type>image/jpeg</mime-type>
      <title>Image title</title>
      <description>Image description</description>
      <location>Image location</location>
      <city>City</city>
      <state>State</state>
      <region>Region</region>
      <country>Country</country>
      <keywords>keyword1, keyword2</keywords>
      <author>Author name</author>
      <copyright>Copyright notice</copyright>
      <date-created>2016-05-20T13:39:30Z</date-created>
      <width>uploaded_file_width_in_pixels</width>
      <height>uploaded_file_height_in_pixels</height>
      <model-release>false</model-release>
      <property-release>false</property-release>
      <license-types>RF, Print</license-types>
      <thumbnail-url>https://medias.photodeck.com/80faf08a-031e-11e1-81a2-0019e3fffe1a/file_medthumb.jpg</thumbnail-url>
      <image-url>https://medias.photodeck.com/80faf08a-031e-11e1-81a2-0019e3fffe1a/file_xgaplus.jpg</image-url>
      <url>https://www.myphotowebsite.com/media/80faf08a-031e-11e1-81a2-0019e3fffe1a</url>
      <price-url>https://www.myphotowebsite.com/media/75f3128e-3e02-11e1-aa7b-0019e3fffe1a-title/price</price-url>
    </media>
    [...]
  </medias>
</reply>

Notes

  • <license-types> can be RF (royalty-free, also applies to simple downloads), RM (rights-managed), Print, and/or Package.
  • <thumbnail-url> points to an image of 175px on its longest side.
  • <image-url> points to the same image displayed on the site, its size depends on user settings.
  • All fields are always included but can be empty, e.g. <price-url/>

Image files should not be hot-linked, they must be retrieved and cached by your frontend.

Activating the feature on a website / file URL

A website owner must proactively activate the XML file export. The XML file URL also contains a security token specific to the website.

The feature can be activated by the website owner under My Website / Setup / Advanced Settings / Integration with another website / Activate my website indexing URL:

Medias export

(for French-speaking users: Mon site / Configuration / Paramètres avancés / Integration avec un autre site / Activer l'URL d'indexation de mon site)

Fetching the file and the If-Modified-Since header

The file is automatically updated and always contains a website's full indexable content. To avoid unnecessary fetching of what can be a very large file, you must use the If-Modified-Since HTTP header.

Do not poll the file more than a couple of times a day. It is also essential you use the If-Modified-Since HTTP header. Frequent unnecessary fetching of the file might result in the access being revoked.

When fetching the file, in addition to the file itself also store the Last-Modified HTTP header returned by the reply to your query. The Last-Modified header can be seen for example with the following command:

curl -D - $url

A correct fetch therefore looks like this (not taking into account the storing of the Last-Modified header):

curl -H "If-Modified-Since: Wed, 16 Nov 2016 14:18:18 GMT" https://www.myphotowebsite.com/medias.xml?auth=131a2733a658a4d347161d9fdfa258b7

If the file hasn't been modified, a HTTP Status Code 304 will be returned. If the file has been modified, you may be redirected (HTTP Status Code 302) to the actual file location for download.

The file is gzipped and must therefore be uncompressed after retrieval