API Method: /api/photo/list

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

ParameterDescription
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 any 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`.
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.
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:

none

For non-public sites, the minimum level is:

anonymous

To acces unpublished videos or content of hidden channels the client must provide a correct token for the object or be authenticated with:

read

Example XML Response

<response status="ok" permission_level="super" p="1" size="20" total_count="407" cached="0">
  <photo photo_id="60433" title="" token="zoyZt0ugycplufdd4eiiaaJhwxgkpime" 
    published_p="1" one="/video/60433" creation_date_ansi="2010-02-16 18:13:32" 
    creation_date__date="February 16, 2010" creation_date__time="06:13 PM" 
    original_date_ansi="2010-02-16 17:13:32" original_date__date="February 16, 2010" 
    original_date__time="05:13 PM" view_count="0" number_of_comments="0" number_of_albums="0" 
    number_of_tags="0" photo_rating="" number_of_ratings="0" video_p="1" audio_p="0" video_encoded_p="1" 
    video_length="55.248" text_only_p="0" user_id="17488" username="__hidden" display_name="Hidden User" 
    user_url="/user/__hidden/" original_width="640" original_height="480" original_size="22124" 
    original_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/original" 
    quad16_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/quad16" quad50_width="50" 
    quad50_height="50" quad50_size="1252" quad50_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/quad50" 
    quad75_width="75" quad75_height="75" quad75_size="1943" 
    quad75_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/quad75" quad100_width="100" quad100_height="100" 
    quad100_size="2765" quad100_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/quad100" small_width="200" 
    small_height="150" small_size="5931" small_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/small" 
    medium_width="260" medium_height="195" medium_size="8908" 
    medium_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/medium" portrait_width="300" portrait_height="225" 
    portrait_size="10916" portrait_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/portrait" 
    standard_width="600" standard_height="450" standard_size="30278" 
    standard_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/standard" large_width="640" large_height="480" 
    large_size="22124" large_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/large" video_small_width="320" 
    video_small_height="240" video_small_size="739004" 
    video_small_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/video_small/download-video.flv" 
    video_medium_width="640" video_medium_height="480" video_medium_size="1236274" 
    video_medium_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/video_medium/download-video.mp4" 
    video_hd_width="640" video_hd_height="480" video_hd_size="1213503" 
    video_hd_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/video_hd/download-video.mp4" 
    video_mobile_h263_amr_width="176" video_mobile_h263_amr_height="132" video_mobile_h263_amr_size="675277" 
    video_mobile_h263_amr_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/video_mobile_h263_amr/download-video.3gp" 
    video_mobile_h263_aac_width="176" video_mobile_h263_aac_height="132" video_mobile_h263_aac_size="641341" 
    video_mobile_h263_aac_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/video_mobile_h263_aac/download-video.3gp" 
    video_mobile_mpeg4_amr_width="176" video_mobile_mpeg4_amr_height="132" video_mobile_mpeg4_amr_size="659552" 
    video_mobile_mpeg4_amr_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/video_mobile_mpeg4_amr/download-video.3gp" 
    audio_width="" audio_height="" audio_size="334545" 
    audio_download="/7340/60433/zoyZt0ugycplufdd4eiiaaJhwxgkpime/audio/download-audio.mp3">
      <content></content>
      <content_text></content_text>
      <before_download_type></before_download_type>
      <before_download_url></before_download_url>
      <after_download_type></after_download_type>
      <after_download_url></after_download_url>
      <after_text></after_text>
  </photo>

  (...)

</response>

Example JSON Response

{
  "status": "ok", 
  "permission_level":"super",
  "cached":"0",
  "photos":[{
    "photo_id": "60433", "title": "", "token": "5622160c758c5d18423d31153458b5f7", 
    "published_p": 1, "one": "/video/60433", "creation_date_ansi": "2010-02-16 18:13:32", 
    "creation_date__date": "February 16, 2010", "creation_date__time": "06:13 PM", 
    "original_date_ansi": "2010-02-16 17:13:32", "original_date__date": "February 16, 2010", 
    "original_date__time": "05:13 PM", "view_count": "0", "number_of_comments": "0", 
    "number_of_albums": "0", "number_of_tags": "0", "photo_rating": "", 
    "number_of_ratings": "0", "video_p": 1, "audio_p": 0, "video_encoded_p": 1, "video_length": "55.248", 
    "text_only_p": 0, "user_id": "17488", "username": "__hidden", "display_name": "Hidden User", 
    "user_url": "/user/__hidden/", "original_width": "640", "original_height": "480", 
    "original_size": "22124", "original_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/original", 
    "quad16_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/quad16", "quad50_width": "50", 
    "quad50_height": "50", "quad50_size": "1252", 
    "quad50_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/quad50", 
    "quad75_width": "75", "quad75_height": "75", "quad75_size": "1943", 
    "quad75_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/quad75", 
    "quad100_width": "100", "quad100_height": "100", "quad100_size": "2765", 
    "quad100_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/quad100", 
    "small_width": "200", "small_height": "150", "small_size": "5931", 
    "small_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/small", 
    "medium_width": "260", "medium_height": "195", "medium_size": "8908", 
    "medium_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/medium", 
    "portrait_width": "300", "portrait_height": "225", "portrait_size": "10916", 
    "portrait_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/portrait", 
    "standard_width": "600", "standard_height": "450", "standard_size": "30278", 
    "standard_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/standard", 
    "large_width": "640", "large_height": "480", "large_size": "22124", 
    "large_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/large", 
    "video_small_width": "320", "video_small_height": "240", "video_small_size": "739004", 
    "video_small_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/video_small/download-video.flv", 
    "video_medium_width": "640", "video_medium_height": "480", "video_medium_size": "1236274", 
    "video_medium_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/video_medium/download-video.mp4", 
    "video_hd_width": "640", "video_hd_height": "480", "video_hd_size": "1213503", 
    "video_hd_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/video_hd/download-video.mp4", 
    "video_mobile_h263_amr_width": "176", "video_mobile_h263_amr_height": "132", 
    "video_mobile_h263_amr_size": "675277", 
    "video_mobile_h263_amr_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/video_mobile_h263_amr/download-video.3gp", 
    "video_mobile_h263_aac_width": "176", "video_mobile_h263_aac_height": "132", "video_mobile_h263_aac_size": "641341", 
    "video_mobile_h263_aac_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/video_mobile_h263_aac/download-video.3gp", 
    "video_mobile_mpeg4_amr_width": "176", "video_mobile_mpeg4_amr_height": "132", 
    "video_mobile_mpeg4_amr_size": "659552", 
    "video_mobile_mpeg4_amr_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/video_mobile_mpeg4_amr/download-video.3gp", 
    "audio_width": "", "audio_height": "", "audio_size": "334545", 
    "audio_download": "/7340/60433/5622160c758c5d18423d31153458b5f7/audio/download-audio.mp3", "content": "", 
    "content_text": "", "before_download_type": "", "before_download_url": "", "after_download_type": "", 
    "after_download_url": "", "after_text": "My site"
  }, ...],
  "p": "1",
  "size": "20",
  "total_count": "407",
  "site": { ... },
  "endpoint": "/api/photo/list"
}
Every feature. Unlimited videos. Unlimited flexibility. Just $675/mo.