Playlist API

GET /playlist/list

List of playlists available to your API account. Playlists are created within the DVIDS CMS.

Example request:

GET /playlist/list?max_results=2&api_key=key-XXXXXXXXXXXXX HTTP/1.1
Host: api.dvidshub.net
Accept-encoding: gzip, deflate
User-Agent: Zend_Http_Client
Accept: application/json, text/javascript
Referer: https://api.dvidshub.net

Example response:

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Transfer-encoding: chunked
Connection: keep-alive
Date: Thu, 21 Nov 2024 08:54:04 GMT
Cache-control: no-cache, private
Access-control-allow-origin: *
Server: Apache
Set-cookie: session=expiry=1732179844631569;Max-Age=600;path=/var/lib/php/sessions;domain=yourdomain.com;httpOnly;secure;
Content-encoding: gzip
Vary: accept-encoding
X-cache: Miss from cloudfront
Via: 1.1 4d8384431ad0b8e60c79585b2d139316.cloudfront.net (CloudFront)
X-amz-cf-pop: IAD12-P4
Alt-svc: h3=":443"; ma=86400
X-amz-cf-id: czUHXfynaY67lE9Bu4Ao8-I_w4VhqTyoazSqmvfgOzxsCoMVBkLOzw==

{
    "results":[
        {
            "hash":"97f747b9da700cb5d6758f5477b79abb",
            "name":"Tasers!",
            "description":"Giggity arrrrrrrrrrrrrrrrrrrrrgh",
            "date_created":"2012-09-20T16:33:16-04:00",
            "podcast_url":"https:\/\/www.dvidshub.net\/rss\/podcast\/119"
        },
        {
            "hash":"e6faef8769fa4e67797a7040a5e29bbb",
            "name":"U.S. Marine Corps Reserve Centennial",
            "description":"August 29th brings us to the centennial date of the U.S. Marine Corps Reserve.  Throughout a year-long commemoration of 1916 - 2016, events will be held throughout the nation. Marine Forces Reserve is (1) highlighting our extraordinary Marines and their contributions, (2) thanking our supporters, and (3) sharing our esprit de corps. We will give thanks to individuals and communities for supporting our Marines. As America\u2019s fighting force, a combined Active and Reserve Marine Corps, we are ready to support the next mission.  Semper Fi, America!",
            "date_created":"2017-03-02T08:38:36-05:00"
        },
        {
            "hash":"7b21ad2c9211a073dec4618361f5e3c6",
            "name":"SOUTHCOM Commander Newswire",
            "description":"Supporting media for SOUTHCOM Leadership SASC and HASC hearings, press briefings, speaking engagements, interviews and other events involving the SOUTHCOM commander. Available media includes audio and video clips and products, photos, print stories with bites, and sizzle reels for social media.",
            "date_created":"2017-04-20T11:23:00-04:00"
        },
        {
            "hash":"fa945f32c1647b0540376e5a21689338",
            "name":"2017 AFRICOM Medical Readiness Exercises",
            "description":"AFRICOM's MEDRETE's hosted by United States Army-Africa, pair small teams of military medical professionals from the U.S. with participating African partner nations to train alongside and share best practices in trauma and surgical medicine. U.S. personnel; benefit by providing medical care in a forward and austere environment; African partners develop closer relations ships with medical personnel, and local populations receive additional medical care.",
            "date_created":"2017-05-17T09:27:42-04:00"
        },
        {
            "hash":"378f2beba13239b553dc83adec6fdc1b",
            "name":"test",
            "description":"test",
            "date_created":"2017-06-05T11:10:01-04:00"
        },
        {
            "hash":"3a6acdb0ee9c7002b31d5b454711d261",
            "name":"Operation Sandy Camel",
            "description":"Test",
            "date_created":"2017-07-11T10:35:37-04:00"
        },
        {
            "hash":"7cae043409cd37589d3b5e686bc7b5d7",
            "name":"Test Operation 2017",
            "description":"Test",
            "date_created":"2017-07-22T13:48:32-04:00"
        },
        {
            "hash":"f668fd6d2c1203abdf701be214ba3b8d",
            "name":"Test Exercise",
            "description":"test",
            "date_created":"2017-08-11T11:27:54-04:00"
        },
        {
            "hash":"880e34e9bb33fa89ca84eff72b7215f8",
            "name":"testtt",
            "description":"jfjeo",
            "date_created":"2017-10-02T09:40:16-04:00"
        },
        {
            "hash":"0b769052ada6df8c9db217ef1bbd9010",
            "name":"Test Page",
            "description":"Test Description.",
            "date_created":"2017-10-02T10:08:16-04:00"
        },
        {
            "hash":"b21645769096be753920bbda25fdba75",
            "name":"Test Playlist",
            "description":"",
            "date_created":"2017-10-26T08:53:21-04:00"
        },
        {
            "hash":"f8eb7670da2bc053474f9ebba4dabad2",
            "name":"test1",
            "description":"",
            "date_created":"2018-08-08T13:28:15-04:00"
        },
        {
            "hash":"2e095941146f3bfd7d34950823cbf9d5",
            "name":"test",
            "description":"",
            "date_created":"2018-08-10T11:04:51-04:00"
        },
        {
            "hash":"ca1e6f905f329632a7c653f9dca156fa",
            "name":"test3",
            "description":"",
            "date_created":"2018-08-10T11:18:59-04:00"
        },
        {
            "hash":"a482f5f5e8426ba15abf6787bb74c4e90ea51961093d8291a760498e1a408d2e",
            "name":"DVIDS Daily Feed",
            "description":"",
            "date_created":"2020-01-29T09:00:27-05:00"
        },
        {
            "hash":"80155d52a652720fc7e7d4ba691125aa3cbdbf4ea0821f7134133ddae8a97906",
            "name":"9 Symphony",
            "description":"blah... \r\nIntroducing the 13-inch MacBook Pro. The state-of-the-art dual-core Intel i7 processor delivers up to 2x faster performance over the previous generation of MacBook Pro. New Thunderbolt technology lets you connect high-performance peripherals and high-resolution displays to a single port, and transfer files at lightning speeds. And with the built-in FaceTime HD camera, you can make astonishingly crisp HD video calls.",
            "date_created":"2020-03-23T12:32:51-04:00"
        },
        {
            "hash":"355d168f1abb3553121d1fcb4eccf9c76505bf7ef060ae7300c410f678fd860a",
            "name":"White House Communication Agency",
            "description":"The White House Communications Agency (WHCA) is a one-of-a-kind Department of Defense joint service organization dedicated to providing premier information services and communications support to the president.",
            "date_created":"2020-03-28T11:49:18-04:00"
        },
        {
            "hash":"033028205c126f5c73ba81cb2dc16b2123f5dcd4b9d857040f6e6450ce836822",
            "name":"testYildiz",
            "description":"This is a test",
            "date_created":"2020-04-06T09:13:50-04:00"
        },
        {
            "hash":"185792a21cf0333824f994cf2d93c2f8f4f7ba72144dc9053e613a0411dab5c1",
            "name":"testYildiz",
            "description":"This is a test",
            "date_created":"2020-04-06T09:24:54-04:00"
        },
        {
            "hash":"9fcb34140fa78a658817e07d667aadd258dbbf0e6ec134c265c74eee8ea37ba3",
            "name":"NewsStream - Science & Technology",
            "description":"Playlist used to store videos for NewsStream Science & Technology category",
            "date_created":"2021-03-04T07:00:01-05:00"
        },
        {
            "hash":"73979836fe7822cb8e806b4a2d4c2f21512eb2c288d9f2b3eb6e95dcf88c67b0",
            "name":"NewsStream - Sports",
            "description":"Playlist used to store videos for NewsStream Sports category",
            "date_created":"2021-03-04T07:00:02-05:00"
        },
        {
            "hash":"baccad103de6b83afe2eac771cfdda6681216da64edd645f50960d4ea29ac096",
            "name":"NewsStream - Entertainment",
            "description":"Playlist used to store videos for NewsStream Entertainment category",
            "date_created":"2021-03-04T07:00:02-05:00"
        },
        {
            "hash":"4a8e7f4986d03451002f845b0b0bb02edbf644e0e2bbec988bc71a80a1d7b451",
            "name":"NewsStream - Health",
            "description":"Playlist used to store videos for NewsStream Health category",
            "date_created":"2021-03-04T07:00:02-05:00"
        },
        {
            "hash":"681ffcce2aa2bf31328337cc1cd939a8b44076c4359e1ea6c2aac5b1e89c3169",
            "name":"NewsStream - Family",
            "description":"Playlist used to store videos for NewsStream Family category",
            "date_created":"2021-03-04T07:00:02-05:00"
        },
        {
            "hash":"70268ba2e69171d719cf412dd3744ef88e380afa884cbdc4b03d51fef67480e7",
            "name":"NewsStream - Missions",
            "description":"Playlist used to store videos for NewsStream Missions category",
            "date_created":"2021-03-04T07:00:02-05:00"
        },
        {
            "hash":"2778e5f0c97ea3314022cbeadcfc3c78b6b0038a3535b0ce9d0975a4e1b0c009",
            "name":"Test 1",
            "description":"Test 1",
            "date_created":"2024-06-27T14:50:53-04:00"
        }
    ]
}

Query Parameters:

• api_key: Public API access key issued by DVIDS (key-xxxxxxxxxxxxx)
• fields: Comma separated list of which fields to return
• prettyprint: [1] Spaces out JSON response in more readable format useful for debugging
• sort: One of date_created, name
• sortdir: One of asc, desc

Status Codes:

• 200: no error
• 400: invalid parameter(s) specified. See errors element in response for details.
• 403: api_key not provided, invalid, or accessed from origin (protocol+domain) other than the one associated with the key provided.

Response Fields:

• cover_image: Url to cover image if available
• date_created: Date in ISO8601 format of when the playlist was created
• description: Description of playlist
• hash: Hash for retrieving playlist contents
• name: Name of playlist
• podcast_url: Rss feed for playlist if it is setup as a podcast

GET /playlist/get

Lists assets belonging to the specified playlist in search api response format.

Example request:

GET /playlist/get?hash=97f747b9da700cb5d6758f5477b79abb&max_results=1&api_key=key-XXXXXXXXXXXXX HTTP/1.1
Host: api.dvidshub.net
Accept-encoding: gzip, deflate
User-Agent: Zend_Http_Client
Accept: application/json, text/javascript
Referer: https://api.dvidshub.net

Example response:

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Transfer-encoding: chunked
Connection: keep-alive
Date: Thu, 21 Nov 2024 08:54:04 GMT
Cache-control: no-cache, private
Access-control-allow-origin: *
Server: Apache
Set-cookie: session=expiry=1732179844774698;Max-Age=600;path=/var/lib/php/sessions;domain=yourdomain.com;httpOnly;secure;
Content-encoding: gzip
Vary: accept-encoding
X-cache: Miss from cloudfront
Via: 1.1 4d8384431ad0b8e60c79585b2d139316.cloudfront.net (CloudFront)
X-amz-cf-pop: IAD12-P4
Alt-svc: h3=":443"; ma=86400
X-amz-cf-id: tYKBe67ZbTgJOkh10nXh6eUXuurig6D0NOc9i4ZT273V9lVERZzj2w==

{
    "results":[
        {
            "id":"video:128144",
            "type":"video",
            "title":"Wisconsin Military Police Get A Lift News Package",
            "aspect_ratio":"16:9",
            "short_description":"Package of soldiers of the 32nd Military Police Company,...",
            "duration":66,
            "hls_url":"https:\/\/api.dvidshub.net\/hls\/video\/128144.m3u8?api_key=key-XXXXXXXXXXXXX",
            "date_published":"2011-10-20T11:13:17-04:00",
            "date":"2011-10-10T00:00:00-04:00",
            "keywords":"Muscatatuck Urban Training Center, Black Hawk, MP, non-lethal weapons training, MUTC, Kosovo, High Definition, Military Police, Wisc., Wisconsin Rapids, Nathan Rivard, 32nd MP Company, Branden Mews",
            "country":"US",
            "state":"IN",
            "credit":"Nathan Rivard",
            "unit_id":"1426",
            "unit_name":"172nd Public Affairs Detachment",
            "branch":"Army",
            "timestamp":"2021-09-04T13:29:16-04:00",
            "thumbnail":"https:\/\/d1ldvf68ux039x.cloudfront.net\/thumbs\/frames\/video\/1110\/128144\/122x92_q95.jpg",
            "thumb_width":122,
            "thumb_height":92,
            "url":"https:\/\/www.dvidshub.net\/video\/128144\/wisconsin-military-police-get-lift-news-package",
            "rating":3
        }
    ],
    "page_info":{
        "total_results":1,
        "results_per_page":1
    }
}

Query Parameters:

• api_key: Public API access key issued by DVIDS (key-xxxxxxxxxxxxx)
• fields: Comma separated list of which fields to return
• hash: 32 character hash identifying playlist to retrieve
• max_results: max_results number. default and maximum value are both 50
• page: what page to load. defaults to 1.
• prettyprint: [1] Spaces out JSON response in more readable format useful for debugging
• short_description_length: Specify length of short_description up to 300 characters. Defaults to 60.

Status Codes:

• 200: no error
• 400: invalid parameter(s) specified. See errors element in response for details.
• 403: api_key not provided, invalid, or accessed from origin (protocol+domain) other than the one associated with the key provided.

Response Fields:

• aspect_ratio: type=video|image: Aspect ratio of the asset
• branch: Name of branch that produced this asset
• credit: Who created the asset
• category: Category of the asset
• city: City where the asset was created
• country: Country where the asset was created
• duration: [int] type=video|audio: Length of asset in seconds
• keywords: Comma separated list of keywords
• date: Date in ISO8601 format of when the asset was created
• date_published: Date in ISO8601 format of when the asset was published at DVIDS
• height: [int] type=image: Height of original image
• id: Asset id
• rating: [float] Rating of the asset. Will not be returned if the asset has not been rated.
• short_description: Shortened version of asset's description. Adjusted via short_description_length param.
• thumb_height: [int] Height of thumbnail
• thumb_width: [int] Width of thumbnail
• thumbnail: Url to resized image of asset as specified by thumb_XXX params
• timestamp: Date in ISO8601 format of when the asset was last updated
• title: Title of asset
• type: Asset type
• unit_name: Full name of unit credited with media asset.
• url: Url to asset on dvidshub.net
• width: [int] type=image: Width of original image

GET /playlist/search

Lists assets belonging to the specified playlist and matching search term in search api response format.

Example request:

GET /playlist/search?q=police&hash=97f747b9da700cb5d6758f5477b79abb&max_results=1&api_key=key-XXXXXXXXXXXXX HTTP/1.1
Host: api.dvidshub.net
Accept-encoding: gzip, deflate
User-Agent: Zend_Http_Client
Accept: application/json, text/javascript
Referer: https://api.dvidshub.net

Example response:

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Transfer-encoding: chunked
Connection: keep-alive
Date: Thu, 21 Nov 2024 08:54:04 GMT
Cache-control: no-cache, private
Access-control-allow-origin: *
Server: Apache
Set-cookie: session=expiry=1732179844868901;Max-Age=600;path=/var/lib/php/sessions;domain=yourdomain.com;httpOnly;secure;
Content-encoding: gzip
Vary: accept-encoding
X-cache: Miss from cloudfront
Via: 1.1 512f238cbc4caf579dfdfec080d485e0.cloudfront.net (CloudFront)
X-amz-cf-pop: IAD12-P4
Alt-svc: h3=":443"; ma=86400
X-amz-cf-id: x1LY1LftMQkMTNbR32lmZGQQNAKSH-Oy8dRgGJ61JjtHfbOcqbeajA==

{
    "results":[
        {
            "publishdate":"2011-10-20T15:13:17Z",
            "date":"2011-10-10T04:00:00Z",
            "category":"Package",
            "aspect_ratio":"16:9",
            "duration":66,
            "title":"Wisconsin Military Police Get A Lift News Package",
            "id":"video:128144",
            "type":"video",
            "keywords":"Muscatatuck Urban Training Center, Black Hawk, MP, Non-Lethal Weapons Training, MUTC, Kosovo, High Definition, Military Police, Wisc., Wisconsin Rapids, Nathan Rivard, 32nd MP Company, Branden Mews",
            "credit":"1LT Nathan Rivard",
            "rating":3,
            "country":"United States",
            "state":"Indiana",
            "unit_name":"172nd Public Affairs Detachment",
            "branch":"Army",
            "timestamp":"2024-01-12T19:35:39.827Z",
            "keywords_highlight":"Muscatatuck Urban Training Center, Black Hawk, MP, Non-Lethal Weapons Training, MUTC, Kosovo, High Definition, Military <em>Police<\/em>, Wisc., Wisconsin Rapids, Nathan Rivard, 32nd MP Company, Branden Mews",
            "description_highlight":"Package of soldiers of the 32nd Military <em>Police<\/em> Company, Wisconsin Army National Guard, getting a UH-60 Black Hawk helicopter ride from Camp Atterbury, Ind. to Muscatatuck Urban Training Center (MUTC",
            "title_highlight":"Wisconsin Military <em>Police<\/em> Get A Lift News Package",
            "short_description":"Package of soldiers of the 32nd Military Police Company,...",
            "thumbnail":"https:\/\/d1ldvf68ux039x.cloudfront.net\/thumbs\/frames\/video\/1110\/128144\/122x92_q95.jpg",
            "thumb_width":122,
            "thumb_height":92,
            "url":"https:\/\/www.dvidshub.net\/video\/128144\/wisconsin-military-police-get-lift-news-package",
            "date_published":"2011-10-20T15:13:17Z"
        }
    ],
    "page_info":{
        "total_results":1,
        "results_per_page":1
    }
}

Query Parameters:

• api_key: Public API access key issued by DVIDS (key-xxxxxxxxxxxxx)
• aspect_ratio: One of 4:3, 16:9, landscape, portrait, square
• branch: One of Army, Navy, Air Force, Marines, Coast Guard, Joint
• category: One of Combat Operations, Miscellaneous, Afghanistan, Guantanamo, Horn of Africa, Iraq, Kuwait, US, Press Release for news. one of B-Roll, Briefings, Commercials, Greetings, In The Fight, Interviews, Newscasts, Package, PSA, Series for video. one of B-Roll, Briefings, Greetings, Interviews, Newscasts for audio.
• categories_exclude: Exclude resources with categories specified. You can specify multiple categories with &categories_exclude[]=cat1&categories_exclude[]=cat2
• city: City where media was captured
• cocom: One of USAFRICOM, USCENTCOM, USEUCOM, USPACOM, USNORTHCOM, USSOUTHCOM, USSPACECOM
• country: Country where media was captured
• credit: Full name including rank of personnel credited with the media asset.
• date: Date in ISO8601 format. Example: 2011-02-13T16:18:00Z. Date media was acquired by shooter/producer.
• duration: [int] Length in seconds of media asset. Only applies to video, audio, and greetings.
• fields: Comma separated list of which fields to return
• format: Format of response. one of cjson [default], rss. (note: rss response structure/fields diff from json)
• from_date: Date in ISO8601 format.
• from_duration: [int] Begin value for duration range query.
• from_publishdate: Date in ISO8601 format.
• from_rating: [0-5] Begin value for rating range query.
• has_image: [0,1] If set to 0, only return media NOT associated with an image. If set to 1, only return media associated with a valid image.
• has_captions: [1] Limit to videos containing subtitles
• hash: 32 character hash identifying playlist to retrieve
• hd: [0,1] If set to 0, only return video media that is NOT considered "HD" (at least 1280x720, 6000kbps or higher). If set to 1, only return video media that meets "HD" criteria.
• highlight_fields: [0,1] Default is 0. Wraps found instances of q parameter with HTML tags for highlighting
• id: string. Specific document id to retrieve for search. Example: “image:123456”
• keywords: string. Multiple keywords can be passed in using the syntax &keywords[]=keyword1&keywords[]=keyword2. Will return result if either keyword is found
• max_results: [1-50] Maximum number of results to return per page. default and maximum value are both 50. If page * max_results > 1000 then the last valid page will be returned given the current max_results
• page: [int] What page to load. Defaults to 1.
• prettyprint: [1] Spaces out JSON response in more readable format useful for debugging
• publishdate: Date in ISO8601 format. Date/time item was published at DVIDS.
• q: Full text search against title, description, keywords
• rating: [int] Only return media with the specific rating number specified. Note that the majority of media does not have a rating.
• sort: One of date, publishdate, timestamp, score, rating, title
• sortdir: One of asc, desc
• spellcheck: One of 0, 1. default is 0. Returns a messages element with spelling correction suggestions
• short_description_length: [1-300] Specify length of short_description up to 300 characters. Defaults to 60.
• state: State where media was captured.
• tags: Whitespace collapsed version of keywords. Example: army-color-guard. Multiple tags can be passed in using the syntax &tags[]=tag1&tags[]=tag2. Will return result if either tag is found
• tags_exclude: Exclude resources with tags specified. You can specify multiple tags with &tags_exclude[]=cat1&tags_exclude[]=cat2
• thumb_width: [1-2000] Width of thumbnail in pixels. If thumb_height is provided, this defaults to the aspect ratio native width of the asset relative to the height requested. Otherwise the resolution is 122x92. Max of 2000.
• thumb_height: [1-2000] Height of thumbnail in pixels. If thumb_width is provided, this defaults to the aspect ratio native height of the asset relative to the width requested. Otherwise the resolution is 122x92. Max of 2000.
• thumb_quality: [1-100] Quality of generated thumbnail. Default is 95
• timestamp: Date in ISO8601 format. Date/time of last update to asset.
• title: Match value against the title field of media.
• to_date: Date in ISO8601 format.
• to_duration: [int] End value of duration range query.
• to_publishdate: Date in ISO8601 format.
• to_rating: [int] End value of rating range query.
• type: One of news, video, image, audio, publication_issue, webcast.
• unit_name: Full name of unit credited with media asset.
• unit: DVIDS abbreviation of unit credited with media asset.

Notes: Thumbnails are created on first load. Subsequent request will use cache. Use on larger result sets will take longer to run the first time.

Status Codes:

• 200: no error
• 400: invalid parameter(s) specified. See errors element in response for details.
• 403: api_key not provided, invalid, or accessed from origin (protocol+domain) other than the one associated with the key provided.
• 503: search is temporarily unavailable

Response Fields:

• aspect_ratio: type=video|image: Aspect ratio of the asset
• branch: Name of branch that produced this asset
• credit: Who created the asset
• category: Category of the asset
• city: City where the asset was created
• country: Country where the asset was created
• duration: [int] type=video|audio: Length of asset in seconds
• keywords: Comma separated list of keywords
• date: Date in ISO8601 format of when the asset was created
• date_published: Date in ISO8601 format of when the asset was published at DVIDS
• height: [int] type=image: Height of original image
• id: Asset id
• publishdate: Date in ISO8601 format of when the asset was published at DVIDS. This field is deprecated and will be removed in a later version of the api. Use date_published instead
• rating: [float] Rating of the asset. Will not be returned if the asset has not been rated.
• short_description: Shortened version of asset's description. Adjusted via short_description_length param.
• thumb_height: [int] Height of thumbnail
• thumb_width: [int] Width of thumbnail
• thumbnail: Url to resized image of asset as specified by thumb_XXX params
• timestamp: Date in ISO8601 format of when the asset was last updated
• title: Title of asset
• type: Asset type
• unit_name: Full name of unit credited with media asset.
• url: Url to asset on dvidshub.net
• width: [int] type=image: Width of original image