API Method: /api/photo/list

Name: Twentythree Web Team
Price range: $

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:

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:

Example XML Response

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"}

Personal Video

Video Section

Video Library

Video Player

Spots

Video Analytics

Video Attribution

Webinars

Reports

Tools

Events

Help center

Videos