Asset API

GET /asset

Extended information about a media asset, retrieved by a specific asset id.

Example 1 request:

GET /asset?id=image:366678&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 1 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:51:19 GMT
Cache-control: no-cache, private
Access-control-allow-origin: *
Server: Apache
Set-cookie: session=expiry=1732179679022432;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 f05e3afde72874082b3c4e5699bc66ba.cloudfront.net (CloudFront)
X-amz-cf-pop: IAD12-P4
Alt-svc: h3=":443"; ma=86400
X-amz-cf-id: IaEVcfkafIBTf8WmUwsJFR6f7TSryxTsCe-PgBi8balDUw0I1bKCdA==

{
    "results":{
        "id":"image:366678",
        "title":"Tanks",
        "description":"A U.S. Marine Corps M1A1 Abrams Tank with 2nd Tank Platoon, Delta Company, 1st Tank Battalion, attached to Battalion Landing Team 3\/8, 26th Marine Expeditionary Unit, Regimental Combat Team 2, provides over watch out across the desert at Combat Outpost Ouellette, Helmand province, Afghanistan, Jan. 30. Delta Company, 1st Tank Battalion, was the first U.S. tank company to deploy to Afghanistan Elements of the 26th Marine Expeditionary Unit deployed to Afghanistan to provide regional security in Helmand province in support of the International Security Assistance Force.",
        "keywords":"NATO, 26th MEU, Fire Support, International Security Assistance Force, joint operations, ISAF, artillery, Joint Task Force, BLT 3\/8, Battalion Landing Team 3\/8",
        "date_published":"2011-02-13T11:18:00-05:00",
        "date":"2011-01-30T00:00:00-05:00",
        "unit_name":"26th Marine Expeditionary Unit",
        "branch":"Marines",
        "timestamp":"2024-06-05T11:26:43-04:00",
        "image":"https:\/\/d34w7g4gy10iej.cloudfront.net\/photos\/1102\/366678.jpg",
        "thumbnail":"https:\/\/d1ldvf68ux039x.cloudfront.net\/thumbs\/photos\/1102\/366678\/122x92_q95.jpg",
        "url":"https:\/\/www.dvidshub.net\/image\/366678\/tanks",
        "credit":[
            {
                "id":1046562,
                "name":"Christopher Matt",
                "rank":"Master Sgt.",
                "url":"https:\/\/www.dvidshub.net\/portfolio\/1046562"
            }
        ],
        "location":{
            "city":"Combat Outpost Ouellette",
            "state":"",
            "country":"Afghanistan",
            "country_abbreviation":"AF"
        },
        "dimensions":{
            "width":"4080",
            "height":"2720"
        },
        "rating":3,
        "virin":"110130-M-4471M-045"
    }
}

Query Parameters:

• id: Specific document id to retrieve for search. Example: "image:123456". Required.
• 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
• 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
• include_related_media: [0,1] If set to 1, includes gallery images with a returned image. News always returns related media. Default is 0.

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.
• 403: asset is not currently published. Per TOS, users are obligated to unpublish these assets and destroy cached entries if asset was previously published.

Response Fields:

• aspect_ratio :type=video|image: Aspect ratio of the asset
• branch: Name of branch that produced this asset
• closed_caption_urls: [array] type=video: Urls to closed caption in available formats if the video has been captioned
• credit: [array|string] Info about who created the asset or Courtesy if unknown
• description: Description of asset
• 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
• files: [array] type=video: List of mp4 files associated with asset
• hls_url: type=video: Url to master m3u8 playlist for asset if video has been encoded for HLS playback
• id: Asset id of asset retrieved
• image: type=image: Url to full resolution version of asset, type=video: Url to full resolution frame capture from asset
• location: [array] Info about where the asset was created. Note country_abbreviation will not be present if it can not be determined.
• dimensions: [array] type=image: Original dimensions (width and height) of the asset; not available on other assets
• related_media: [array] Structured info about related media assets. Only available in response for images (if included_related_media=1) and news (always).
• rating: [float] Rating of the asset. Will not be returned if the asset has not been rated.
• 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
• time_start: [float] type=video: Time at which the content actual content of the video is estimated to start
• title: Title of asset
• unit_name: Name of unit that produced this asset
• url: Url to asset on dvidshub.net
• views: Number of times the asset has been viewed. Will only be returned if specified in the fields parameter.
• virin: VIRIN of asset

Example 2 request:

GET /asset?id=video:284392&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 2 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:51:19 GMT
Cache-control: no-cache, private
Access-control-allow-origin: *
Server: Apache
Set-cookie: session=expiry=1732179679181253;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: AP0psreKEj1-PO2kjmSteEy5oW0JHXrU-d72VGSEkBcje-_19HdqcA==

{
    "results":{
        "id":"video:284392",
        "type":"video",
        "title":"Walt Peters - Ramblin' Country Man",
        "description":"U.S. Army Staff Sergeant (Retired) Walt Peters supports Soldiers and Veterans with his music and generosity. Walt was part of the All Soldier Band of which George Strait was also a member. Walt is an inspiration to people he meets in many walks of life. Walt is nearly blind now because of diabetes, but that doesn't stop him from helping to take care of homeless Veterans as well as blind Veterans. His band, The Ramblin' Country Band, uses many of its proceeds to support Walt in his endeavors for the troops in the greater Savannah, Georgia area. Includes interview with Mickey Huggins, Lead Singer & Rhythm Guitarist - Ramblin' Country Band. Also available in high definition.",
        "keywords":"guitar, Veteran, Fort Stewart, 3rd Infantry Division, Homeless veterans, savannah, Vietnam veteran, soldiers, 3rd ID, 2nd Brigade Combat Team, music, Hunter Army Airfield, 2 BCT, support soldiers, Blind Veterans, Walt Peters, All Soldier Band, Ramblin' Country Band, George Strait",
        "date_published":"2013-03-19T00:57:42-04:00",
        "date":"2013-01-11T00:00:00-05:00",
        "category":"Package",
        "unit_id":"23",
        "unit_name":"2nd Armored Brigade Combat Team, 3rd Infantry Division Public Affairs",
        "branch":"Army",
        "timestamp":"2021-10-06T20:29:46-04:00",
        "image":"https:\/\/d1ldvf68ux039x.cloudfront.net\/thumbs\/frames\/video\/1303\/284392\/2000w_q95.jpg",
        "url":"https:\/\/www.dvidshub.net\/video\/284392\/walt-peters-ramblin-country-man",
        "credit":[
            {
                "id":1157593,
                "name":"Stephen Dornbos",
                "rank":"Sgt.",
                "url":"https:\/\/www.dvidshub.net\/portfolio\/1157593"
            }
        ],
        "location":{
            "city":"Savannah",
            "state":"Georgia",
            "country":"United States",
            "state_abbreviation":"GA",
            "country_abbreviation":"US"
        },
        "rating":5,
        "time_start":4.1374700000000004,
        "virin":"130319-A-FW223-001",
        "duration":396,
        "aspect_ratio":"16:9",
        "files":[
            {
                "src":"https:\/\/d34w7g4gy10iej.cloudfront.net\/video\/1303\/DOD_100765434\/DOD_100765434-486x274-300k.mp4",
                "type":"video\/mp4",
                "height":274,
                "width":486,
                "size":18307252,
                "bitrate":300
            },
            {
                "src":"https:\/\/d34w7g4gy10iej.cloudfront.net\/video\/1303\/DOD_100765434\/DOD_100765434-720x406-800k.mp4",
                "type":"video\/mp4",
                "height":406,
                "width":720,
                "size":43075778,
                "bitrate":800
            },
            {
                "src":"https:\/\/d34w7g4gy10iej.cloudfront.net\/video\/1303\/DOD_100765434\/DOD_100765434-720x406-1500k.mp4",
                "type":"video\/mp4",
                "height":406,
                "width":720,
                "size":77484637,
                "bitrate":1500
            },
            {
                "src":"https:\/\/d34w7g4gy10iej.cloudfront.net\/video\/1303\/DOD_100765434\/DOD_100765434-1280x720-3000k.mp4",
                "type":"video\/mp4",
                "height":720,
                "width":1280,
                "size":152515502,
                "bitrate":3000
            },
            {
                "src":"https:\/\/d34w7g4gy10iej.cloudfront.net\/video\/1303\/DOD_100765434\/DOD_100765434.mp4",
                "type":"video\/mp4",
                "height":720,
                "width":1280,
                "size":469871403,
                "bitrate":9173
            }
        ],
        "hls_url":"https:\/\/api.dvidshub.net\/hls\/video\/284392.m3u8?api_key=key-XXXXXXXXXXXXX",
        "closed_caption_urls":{
            "srt":"https:\/\/api.dvidshub.net\/closed-captions\/get?asset_id=video:284392&format=srt&api_key=key-XXXXXXXXXXXXX",
            "webvtt":"https:\/\/api.dvidshub.net\/closed-captions\/get?asset_id=video:284392&format=webvtt&api_key=key-XXXXXXXXXXXXX"
        },
        "thumbnail":{
            "url":"https:\/\/d1ldvf68ux039x.cloudfront.net\/thumbs\/frames\/video\/1303\/284392\/122x92_q95.jpg",
            "width":122,
            "height":92
        }
    }
}

GET /asset/related

Basic information about media assets, related to the asset specified, filtered and sorted according to parameters.

Example request:

GET /asset/related?id=video:284392&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:51:19 GMT
Cache-control: no-cache, private
Access-control-allow-origin: *
Server: Apache
Set-cookie: session=expiry=1732179679468081;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 bd3f4df95f7c836cc4eb6a22d92ac2c2.cloudfront.net (CloudFront)
X-amz-cf-pop: IAD12-P4
Alt-svc: h3=":443"; ma=86400
X-amz-cf-id: qJkJlMSYsCEBBc_PVfidwNdzjf4l1iLjFMGSWJ0aS4AV2mQK6Ip4dw==

{
    "page_info":{
        "total_results":1000,
        "results_per_page":2
    },
    "results":[
        {
            "publishdate":"2014-07-17T16:23:51Z",
            "date":"2014-07-15T04:00:00Z",
            "width":2226,
            "height":1252,
            "aspect_ratio":"landscape",
            "title":"Walt Sides: Retired Marine larger than life, louder than thunder",
            "id":"image:1451472",
            "type":"image",
            "keywords":"Veteran, P.O.W., M.I.A., Rolling Thunder, Washington, Marine Corps Scout Snipers, Walt Sides",
            "rating":3,
            "country":"Vietnam",
            "unit_name":"Defense Media Activity - Marines",
            "branch":"Joint",
            "timestamp":"2024-01-13T23:25:08.996Z",
            "short_description":"Walt Sides poses for a photo while on deployment in...",
            "thumbnail":"https:\/\/d1ldvf68ux039x.cloudfront.net\/thumbs\/photos\/1407\/1451472\/122x92_q95.jpg",
            "url":"https:\/\/www.dvidshub.net\/image\/1451472\/walt-sides-retired-marine-larger-than-life-louder-than-thunder",
            "date_published":"2014-07-17T16:23:51Z"
        },
        {
            "publishdate":"2020-03-31T05:04:47Z",
            "date":"2020-03-29T04:00:00Z",
            "category":"Video Productions",
            "aspect_ratio":"16:9",
            "duration":133,
            "hd":true,
            "title":"3rd Marine Division Vietnam Heroes.",
            "id":"video:744837",
            "type":"video",
            "keywords":"general, 3rd Marine Division, heroes, Veteran's Day, History Channel, reading a book, Sgt.Maj., history, Vietnam, WWII, Silver Star, 1st Marine Raiders Battalion, Navy Cross recipient, 3rdMarDiv, ACMC, Lewis Walt, Tulagi, veterans #veterans, Walt hall",
            "credit":"Sgt Kallahan Morris",
            "country":"Japan",
            "state":"Okinawa",
            "unit_name":"3d Marine Division",
            "branch":"Marines",
            "timestamp":"2024-06-26T23:29:47.459Z",
            "short_description":"U.S. Marine Corps Sgt.Maj. Dennis M. Bradley, 3rd Marine...",
            "thumbnail":"https:\/\/d1ldvf68ux039x.cloudfront.net\/thumbs\/frames\/video\/2003\/744837\/122x92_q95.jpg",
            "url":"https:\/\/www.dvidshub.net\/video\/744837\/3rd-marine-division-vietnam-heroes",
            "date_published":"2020-03-31T05:04:47Z"
        }
    ]
}

Query Parameters:

• api_key: Public API access key issued by DVIDS (key-xxxxxxxxxxxxx)
• aspect_ratio: One of 4:3, 16:9, landscape, portrait, square. Only applies to video and image
• branch: One of Army, Navy, Air Force, Marines, Coast Guard, Joint, Civilian
• 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 and audio
• fields: Comma separated list of which fields to return
• 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 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
• q: Fulltext search against title, description, keywords
• rating: [0-5] Only return media with the specific rating number specified. Note that the majority of media does not have a rating.
• short_description_length: [1-300] Specify length of short_description up to 300 characters. Defaults to 60.
• sort: one of date, publishdate, timestamp, score, rating
• sortdir: One of asc, desc
• spellcheck: [0,1] Default is 0. Returns a messages element with spelling correction suggestions.
• 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 height of the asset relative to the width requested. Otherwise the resolution is 122x92.
• thumb_height: [1-2000] Height of thumbnail in pixels. If thumb_width is provided, this defaults to the aspect ratio native width of the asset relative to the height requested. Otherwise the resolution is 122x92.
• 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: [0-5] 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:

• 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. Currently locked at 60 characters
• 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