API Method: /api/photo/list
Return a list of photos or videos.
Note, that since the photo_id
and album_id
parameters might both be matched to the token
, you won't be able to use album_id
and photo_id
together. If album_id
is set, the photo_id
parameter is ignored.
Parameters
Parameter | Description |
---|---|
album_id | List content from a single album or channel. Also see token. If this parameter is set, `photo_id` is ignored. |
photo_id | Limit to a single photo or video. Also see token. If `album_id` is set, this parameter is ignored. |
token | The token for a specific video/photo or an album − depending on whether photo_id or album_id is set. Specifying either an album_id/token or a photo_id/token will give the client access to information about the video/photo/album/channel irregardless of permission level. When requesting a single photo object, tokens can be explicitly time-limited. |
user_id | Search for photos or videos uploaded by a specific users. |
player_id | The identifier for a video player. Including the parameter will allow contextualization of the content for the specific player; for example by fitting the playflow (preroll, postroll, after text etc) based on the player. |
tags | Search for one or more tags. To search for multiple tags, separate tags with spaces. Multi-word tags can be quotes with ". |
tag_mode | Set the value all means that all tags must be present for a videos or photos to be included in the response. Specifying the value all will get you all videos or photos with just one of the tags. Default: and |
custom_variable_mode | To search in custom variables, set this value to either all or any -- specify each custom variable to search for by key in the parameters as well. When you set the value to all, every specified custom variable filter must match. Specifying the value any will get you all videos or photos with just a single matching custom variable in the filters. Default: none |
search | Search photos and video for a specific term. |
source | A source for the request, designed to be used in analytics (normal options are admin, site, share, embed, podcast, download, search and facebook but you may choose your own source). |
year | Only include content from a specific year in the response. |
month | Only include content from a specific month in the response. Requires year to be set. |
day | Only include content from a specific day in the response. Requires year and month to be set. |
after_time | Only include content created, uploaded or published after this time. See also `datemode`. |
before_time | Only include content created, uploaded or published before this time. See also `datemode`. | datemode | Variable to select which property to use when filtering by 'after_time' or 'before_time'. Default: uploaded Valid values: 'uploaded' or 'published' |
video_p | Limit to either video content or not video content. Default: (empty) Valid values: (empty), 0 or 1 |
audio_p | Limit to either audio content or not audio content. Default: (empty) Valid values: (empty), 0 or 1 |
video_encoded_p | Limit to either video, which has been transcoded or stuff waiting to be transcoder. Requires read permissions. Default: (empty) Valid values: (empty), 0 or 1 |
include_unpublished_p | Include unpublished videos or photos in the response. Requires read permissions. Default: 0 Valid values: 0 or 1 |
has_coordinates_p | Filter results by whether or not a geographic coordinate has been associated with the photo or video. Default: (empty) Valid values: (empty), 0 or 1 |
include_actions_p | Include a list of Actions for photo object. This options is only allowed when requesting a single photo object. In other cases, use [/api/action/get](action-get) to retrieve the same data. Default: 1 Valid values: (empty), 0 or 1 |
upload_token | An upload token from a browser-based upload. |
related_to_photo_id | Search for related `photo` objects. |
related_to_photo_id | Search for related `photo` objects. |
spot_id | Filter and sort items for spot widget or spot landing page, requires spot_token to be set. |
spot_token | Token for spot widget or spot landing page. |
orderby | Variable to order content by. Default: published Valid values: views, comments, taken, title, words, rating, created, uploaded, published |
order | Order of the objects in the response. Default: desc Valid values: desc and asc |
license_id | The license associated with the content item. See [/api/license/list](license-list) for information on available values. |
live_id | The ID of the live event associated with the content item. See [/api/live/list](live-list) for more information. |
prioritize_promoted_p | Should the request prioritize videos marked as promoted or not Default: 1 Valid values: 0 or 1 |
promoted_p | Filter list to only include videos which are promoted or not promoted. Default: (empty) Valid values: (empty), 0 or 1 |
p | Page offset for the request. See [pagination](index#pagination) for details. |
size | Number of objects to include in the response. See [pagination](index#pagination) for details. |
Permission level
The minimum required permission level is:
<pre><code>none</code></pre>
For non-public sites, the minimum level is:
<pre><code>anonymous</code></pre>
To acces unpublished videos or content of hidden channels the client must provide a correct token for the object or be authenticated with:
<pre><code>read</code></pre>
Example XML Response
<pre><code><response status="ok" permission_level="super" p="1" size="20" total_count="407" cached="0"> <photo photo_id="11623454" title="USA - 5 things to see in the west" tree_id="10820441" token="5622160c758c5d18423d31153458b5f7" protected_p="0" protection_method="" album_id="11623459" album_title="Travels" album_hide_p="0" all_albums="11623459" published_p="1" one="/video/11623454/example" publish_date_ansi="2012-07-23 14:24:38" publish_date_epoch="1343046278" publish_date__date="Monday July 23, 2012" publish_date__time="14:24" creation_date_ansi="2015-05-30 15:48:38" creation_date_epoch="1432993718" creation_date__date="Saturday May 30, 2015" creation_date__time="15:48" original_date_ansi="2015-05-30 15:48:38" original_date__date="Saturday May 30, 2015" original_date__time="15:48" view_count="5" avg_playtime="2.97029702970297" number_of_comments="0" number_of_albums="1" number_of_tags="13" photo_rating="" number_of_ratings="0" video_p="1" video_encoded_p="1" audio_p="0" video_length="159" text_only_p="0" user_id="3551134" username="kkabell" display_name="Kalle" user_url="/user/kkabell/" has_deck_p="0" subtitles_p="0" sections_p="0" license_id="0" coordinates="" video_hls_size="0" video_hls_download="" video_dash_size="0" video_dash_download="" original_filename="/var/web/visualprod/data/um/storage/containers/4959039/4959050/21/6592247-video_original" original_width="1920" original_height="1080" original_size="95916" original_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/original" quad16_width="160" quad16_height="90" quad16_size="3616" quad16_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/quad16" quad50_width="280" quad50_height="158" quad50_size="8465" quad50_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/quad50" quad75_width="75" quad75_height="75" quad75_size="1688" quad75_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/quad75" quad100_width="340" quad100_height="191" quad100_size="11396" quad100_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/quad100" small_width="200" small_height="113" small_size="5179" small_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/small" medium_width="260" medium_height="146" medium_size="7699" medium_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/medium" portrait_width="520" portrait_height="293" portrait_size="22203" portrait_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/portrait" standard_width="580" standard_height="326" standard_size="26351" standard_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/standard" large_width="800" large_height="450" large_size="42953" large_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/large" video_medium_width="640" video_medium_height="360" video_medium_size="21144211" video_medium_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_medium/example-video.mp4" video_hd_width="1280" video_hd_height="720" video_hd_size="33032948" video_hd_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_hd/example-video.mp4" video_1080p_width="1920" video_1080p_height="1080" video_1080p_size="49869927" video_1080p_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_1080p/example-video.mp4" video_4k_width="" video_4k_height="" video_4k_size="0" video_4k_download="" video_frames_width="320" video_frames_height="180" video_frames_size="1435199" video_frames_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_frames/example-frames.jpg" video_wmv_width="" video_wmv_height="" video_wmv_size="0" video_wmv_download="" video_mobile_h263_amr_width="176" video_mobile_h263_amr_height="141" video_mobile_h263_amr_size="1899517" video_mobile_h263_amr_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_mobile_h263_amr/example-video.3gp" video_mobile_h263_aac_width="176" video_mobile_h263_aac_height="141" video_mobile_h263_aac_size="1764112" video_mobile_h263_aac_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_mobile_h263_aac/example-video.3gp" video_mobile_mpeg4_amr_width="176" video_mobile_mpeg4_amr_height="141" video_mobile_mpeg4_amr_size="1851051" video_mobile_mpeg4_amr_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_mobile_mpeg4_amr/example-video.3gp" video_mobile_high_width="320" video_mobile_high_height="180" video_mobile_high_size="7170756" video_mobile_high_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_mobile_high/example-video.mp4" audio_width="" audio_height="" audio_size="958526" audio_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/audio/example-audio.mp3" video_webm_360p_width="640" video_webm_360p_height="360" video_webm_360p_size="22243197" video_webm_360p_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_webm_360p/example-video.webm" video_webm_720p_width="1280" video_webm_720p_height="720" video_webm_720p_size="44630941" video_webm_720p_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_webm_720p/example-video.webm" video_original_width="1920" video_original_height="1080" video_original_size="307506558" video_original_download="/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_original"> <content></content> <content_text></content_text> <before_download_type/> <before_link/> <before_download_url/> <after_download_type/> <after_link/> <after_download_url/> <after_text/> <tags></tags> </photo> (...)</response></code></pre>
Example JSON Response
{ "status": "ok", "permission_level":"super", "cached":"0", "photos":[{ "photo_id": "11623454", "title": "USA - 5 things to see in the west", "tree_id": "10820441", "token": "5622160c758c5d18423d31153458b5f7", "protected_p": 0, "protection_method": "", "album_id": "11623459", "album_title": "Travels", "album_hide_p": 0, "all_albums": "11623459", "published_p": 1, "one": "/video/11623454/example", "publish_date_ansi": "2012-07-23 14:24:38", "publish_date_epoch": "1343046278", "publish_date__date": "Monday July 23, 2012", "publish_date__time": "14:24", "creation_date_ansi": "2015-05-30 15:48:38", "creation_date_epoch": "1432993718", "creation_date__date": "Saturday May 30, 2015", "creation_date__time": "15:48", "original_date_ansi": "2015-05-30 15:48:38", "original_date__date": "Saturday May 30, 2015", "original_date__time": "15:48", "view_count": "5", "avg_playtime": "2.97029702970297", "number_of_comments": "0", "number_of_albums": "1", "number_of_tags": "13", "photo_rating": "", "number_of_ratings": "0", "video_p": 1, "video_encoded_p": 1, "audio_p": 0, "video_length": "159", "text_only_p": 0, "user_id": "3551134", "username": "kkabell", "display_name": "Kalle", "user_url": "/user/kkabell/", "has_deck_p": 0, "subtitles_p": 0, "sections_p": 0, "license_id": "0", "coordinates": "", "video_hls_size": "0", "video_hls_download": "", "video_dash_size": "0", "video_dash_download": "", "original_filename": "/var/web/visualprod/data/um/storage/containers/4959039/4959050/21/6592247-video_original", "original_width": "1920", "original_height": "1080", "original_size": "95916", "original_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/original", "quad16_width": "160", "quad16_height": "90", "quad16_size": "3616", "quad16_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/quad16", "quad50_width": "280", "quad50_height": "158", "quad50_size": "8465", "quad50_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/quad50", "quad75_width": "75", "quad75_height": "75", "quad75_size": "1688", "quad75_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/quad75", "quad100_width": "340", "quad100_height": "191", "quad100_size": "11396", "quad100_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/quad100", "small_width": "200", "small_height": "113", "small_size": "5179", "small_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/small", "medium_width": "260", "medium_height": "146", "medium_size": "7699", "medium_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/medium", "portrait_width": "520", "portrait_height": "293", "portrait_size": "22203", "portrait_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/portrait", "standard_width": "580", "standard_height": "326", "standard_size": "26351", "standard_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/standard", "large_width": "800", "large_height": "450", "large_size": "42953", "large_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/large", "video_medium_width": "640", "video_medium_height": "360", "video_medium_size": "21144211", "video_medium_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_medium/example-video.mp4", "video_hd_width": "1280", "video_hd_height": "720", "video_hd_size": "33032948", "video_hd_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_hd/example-video.mp4", "video_1080p_width": "1920", "video_1080p_height": "1080", "video_1080p_size": "49869927", "video_1080p_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_1080p/example-video.mp4", "video_4k_width": "", "video_4k_height": "", "video_4k_size": "0", "video_4k_download": "", "video_frames_width": "320", "video_frames_height": "180", "video_frames_size": "1435199", "video_frames_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_frames/example-frames.jpg", "video_wmv_width": "", "video_wmv_height": "", "video_wmv_size": "0", "video_wmv_download": "", "video_mobile_h263_amr_width": "176", "video_mobile_h263_amr_height": "141", "video_mobile_h263_amr_size": "1899517", "video_mobile_h263_amr_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_mobile_h263_amr/example-video.3gp", "video_mobile_h263_aac_width": "176", "video_mobile_h263_aac_height": "141", "video_mobile_h263_aac_size": "1764112", "video_mobile_h263_aac_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_mobile_h263_aac/example-video.3gp", "video_mobile_mpeg4_amr_width": "176", "video_mobile_mpeg4_amr_height": "141", "video_mobile_mpeg4_amr_size": "1851051", "video_mobile_mpeg4_amr_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_mobile_mpeg4_amr/example-video.3gp", "video_mobile_high_width": "320", "video_mobile_high_height": "180", "video_mobile_high_size": "7170756", "video_mobile_high_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_mobile_high/example-video.mp4", "audio_width": "", "audio_height": "", "audio_size": "958526", "audio_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/audio/example-audio.mp3", "video_webm_360p_width": "640", "video_webm_360p_height": "360", "video_webm_360p_size": "22243197", "video_webm_360p_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_webm_360p/example-video.webm", "video_webm_720p_width": "1280", "video_webm_720p_height": "720", "video_webm_720p_size": "44630941", "video_webm_720p_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_webm_720p/example-video.webm", "video_original_width": "1920", "video_original_height": "1080", "video_original_size": "307506558", "video_original_download": "/10820441/11623454/5622160c758c5d18423d31153458b5f7/video_original", "content": "", "content_text": "", "before_download_type": "", "before_link": "", "before_download_url": "", "after_download_type": "", "after_link": "", "after_download_url": "", "after_text": "", "tags": [] }, ...], "p": "1", "size": "20", "total_count": "407", "site": { ... }, "endpoint": "/api/photo/list"}