Search API

GET /search

Basic information about media assets, filtered and sorted according to parameters.

Example request:

GET /search?q=tank&max_results=2&api_key=key-XXXXXXXXXXXXX HTTP/1.1
Host: api.dvidshub.net
Accept-encoding: gzip, deflate
Accept: application/json, text/javascript
Referer: https://api.dvidshub.net

Example response:

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: Apache
Access-control-allow-origin: *
Content-encoding: gzip
Content-length: 2463
Date: Sun, 19 Sep 2021 08:37:45 GMT
Connection: keep-alive
Vary: Accept-Encoding

{
    "page_info":{
        "total_results":1000,
        "results_per_page":2
    },
    "results":[
        {
            "publishdate":"2021-09-09T13:02:05Z",
            "date":"2021-10-08T04:00:00Z",
            "category":"B-Roll",
            "aspect_ratio":"16:9",
            "duration":327,
            "hd":true,
            "title":"European Best Sniper Team Competition",
            "id":"video:812945",
            "type":"video",
            "keywords":"Sniper, competition, US Army",
            "country":"Germany",
            "city":"Hohenfels",
            "unit_name":"Natochannel",
            "branch":"Joint",
            "timestamp":"2021-09-15T13:40:05.159Z",
            "short_description":"Every year, the US Army\u2019s 7th Army Training Command hosts the European Best Sniper Team Competition in Bavaria, Germany. The competition tests participants\u2019 physical endurance, marksmanship and mental toughness over a series of events based on real-life scenarios. In one event, for example, competitors must navigate a trench filled with tear gas while engaging targets both near and far. In another event, participants must rush to a downed helicopter, retrieve a 100-kilogram dummy and drag it to safety.\r\n\r\nTeams from 14 NATO Allies and partners participated in the 2021 competition. Slovenia claimed first place, followed by Turkey in second and Latvia in third.\r\n\r\nFootage includes shots of snipers from the Italian Army, the Slovenian Special Forces, the Swedish Army Ranger Battalion and the Turkish Army during the competition, and interviews with an Italian sniper and a US Army competition leader. COVID-19 safeguards were taken prior to deployment for the competition and participants observed social distancing where training requirements allowed.\r\n\r\nTranscript\r\n\r\n(00:00) TELEPHOTO SHOT \u2013 US ARMY UH-72 LAKOTA HELICOPTER LANDING\r\n(00:05) TELEPHOTO SHOT \u2013 TURKISH SNIPER DISEMBARKING LAKOTA\r\n(00:08) VARIOUS SHOTS \u2013 TURKISH SNIPER TEAM MOVING THROUGH PISTOL AND RIFLE SHOOTING EVENT\r\n(00:55) MEDIUM SHOT \u2013 LAKOTA CABIN INTERIOR\r\n(00:58) VARIOUS SHOTS \u2013 SLOVENIAN SPECIAL FORCES SNIPERS SHOOTING FROM AIRBORNE LAKOTA\r\n(01:21) VARIOUS SHOTS \u2013 SLOVENIAN FORCES MOVING THROUGH PISTOL AND RIFLE EVENT\r\n(01:44) VARIOUS SHOTS \u2013 SWEDISH RANGERS MOVING THROUGH PISTOL AND RIFLE EVENT\r\n(02:26) VARIOUS SHOTS \u2013 ITALIAN SNIPERS CRAWLING THROUGH MUDDY TRENCH\r\n(02:40) VARIOUS SHOTS \u2013 ITALIAN SNIPER ENGAGING TARGETS IN A SNIPER HIDE\r\n(02:45) VARIOUS SHOTS \u2013 ITALIANS DONNING GAS MASKS\r\n(02:54) VARIOUS SHOTS \u2013 ITALIANS MOVING THROUGH TEAR GAS-FILLED TRENCH WHILE ENGAGING TARGETS\r\n(03:54) WIDE SHOT \u2013 ITALIAN SNIPER DUNKING HIMSELF IN A DECONTAMINATION TANK\r\n(04:03) SOUNDBITE (ENGLISH) \u2013 Command Sergeant Major Michael Sanchez, Joint Multinational Readiness Center, US Army\r\n\u201cThe competition\u2019s been great. I\u2019ve went across all of the events so far, and spoke to all the competitors, and they had nothing but positive and great things to say about it. Some things were new. Some things were a shock. As they\u2019ve been told, they\u2019ve told me, they\u2019ve physically, mentally and emotionally been tested, which was the whole idea of this whole competition was to test their physical abilities, their mental abilities, their emotional abilities, and can they combine all their, have control of all three and still be able to maximise and focus on the task and get the achievement that they desire.\u201d\r\n(04:37) SOUNDBITE (ENGLISH) \u2013 Command Sergeant Major Michael Sanchez, Joint Multinational Readiness Center, US Army\r\n\u201cThe biggest benefit, from when we talk about interoperability, not just for this competition, but in any event, is one, we establish a better understanding when we communicate. And as long as we can establish a better understanding when we communicate, then it just makes things that much smoother.\u201d\r\n(05:01) SOUNDBITE (ITALIAN) \u2013 FIRST CORPORAL-MAJOR ALESSIO FRANZOT, REGGIMENTO LAGUNARI SERENISSIMA, ITALIAN ARMY\r\n\u201cIt\u2019s very, very realistic. In every small phase, in every small detail, every small detail was very particular. So for us it\u2019s something exceptional.\u201d\r\n(05:08) SOUNDBITE (ITALIAN) \u2013 FIRST CORPORAL-MAJOR ALESSIO FRANZOT, REGGIMENTO LAGUNARI SERENISSIMA, ITALIAN ARMY\r\n\u201cLike I said before, it is an occasion to share ways of working, materials, equipment. And also learn the language, so learn one more language or improve your English, which I believe is essential.\u201d",
            "thumbnail":"https:\/\/cdn.dvidshub.net\/media\/thumbs\/frames\/video\/2109\/812945\/122x92_q95.jpg",
            "thumb_width":122,
            "thumb_height":92,
            "hls_url":"https:\/\/api.dvidshub.net\/hls\/video\/812945.m3u8?api_key=key-XXXXXXXXXXXXX",
            "url":"https:\/\/www.dvidshub.net\/video\/812945\/european-best-sniper-team-competition",
            "date_published":"2021-09-09T13:02:05Z"
        },
        {
            "publishdate":"2021-09-17T20:52:30Z",
            "date":"2021-09-17T04:00:00Z",
            "category":"Briefings",
            "aspect_ratio":"16:9",
            "duration":3064,
            "hd":true,
            "title":"Pentagon Press Secretary Holds News Conference",
            "id":"video:814368",
            "type":"video",
            "keywords":"John Kirby, DGOV, Pentagon Press Secretary, #DGOVLIVE, DEFENSE ON DEMAND",
            "country":"United States",
            "state":"Delaware",
            "city":"",
            "unit_name":"Defense.gov",
            "branch":"Joint",
            "timestamp":"2021-09-17T21:08:04.076Z",
            "short_description":"Pentagon Press Secretary John F. Kirby briefs the media at the Pentagon.",
            "thumbnail":"https:\/\/cdn.dvidshub.net\/media\/thumbs\/frames\/video\/2109\/814368\/122x92_q95.jpg",
            "thumb_width":122,
            "thumb_height":92,
            "hls_url":"https:\/\/api.dvidshub.net\/hls\/video\/814368.m3u8?api_key=key-XXXXXXXXXXXXX",
            "url":"https:\/\/www.dvidshub.net\/video\/814368\/pentagon-press-secretary-holds-news-conference",
            "date_published":"2021-09-17T20:52:30Z"
        }
    ]
}

Query Parameters:

Field Example
api_key Public API access key issued by DVIDS api_key=key-xxxxxxxxxxxxx
aspect_ratio 4:3, 16:9, landscape, portrait, square aspect_ratio=landscape
branch Army, Navy, Air Force, Marines, Coast Guard, Joint, Civilian branch=Army
category
categories_exclude
Combat Operations
Miscellaneous
Afghanistan
Guantanamo
Horn of Africa
Iraq
Kuwait
US
Press Release for news
B-Roll
Briefings
Commercials
Greetings
In The Fight
Interviews
Newscasts
Package
PSA
Series for video
Interviews
Newscasts for audio.
category=cat1

(specify multiple categories
with list notation)


category[]=cat1&category[]=cat2
categories_exclude[]=cat1
city City where media was captured. city=Atanta
cocom USAFRICOM
USCENTCOM
USEUCOM
USPACOM
USNORTHCOM
USSOUTHCOM
cocom=USAFRICOM
country Country where media was captured country=US
credit Full name including rank of personnel credited with the media asset. credit=Sgt John Doe
date Date media was acquired by shooter/producer.
Date in ISO8601 format.
date=2011-02-13T16:18:00Z
duration Length in seconds of media asset.
Only applies to video, audio, and greetings.
type=video&duration=75
fields Comma separated list of which fields to return. fields=title,description,date
format Format of response. json [default], rss.
(rss response structure/fields differ from json)
format=rss
from_date Begin value for date range query.
Date in ISO8601 format.
from_date=2011-02-13T16:18:00Z
from_duration Begin value for duration range query. from_duration=165
from_publishdate Begin value for publish date range query.
Date in ISO8601 format.
from_publishdate=2011-02-13T16:18:00Z
from_rating [0-5] Begin value for rating range query. from_range=3
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_image=1
has_captions [1] Limit to videos containing subtitles. has_captions=1
hash 32 character hash identifying playlist to retrieve. hash=97f747b9da700cb5d6758f5477b79abb
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.
hd=1
highlight_fields [0,1] Default is 0. Wraps found instances of q parameter with HTML tags for highlighting
id Specific document id to retrieve for search. id=image:123456
keywords 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 What page to load. Defaults to 1. page=1
prettyprint [1] Spaces out JSON response in more readable format useful for debugging prettyprint=1
publishdate Date/time item was published at DVIDS.
Date in ISO8601 format.
publishdate=2011-02-13T16:18:00Z
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 Field to sort by. date, publishdate, timestamp, score, rating sort=date
sortdir asc, desc sortdir=asc
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.
Multiple tag queries will return result if either tag is found.
tags[]=army-color-guard

(specify multiple tags
with list notation)


&tags[]=tag1&tags[]=tag2
tags_exclude Exclude resources with tags specified. &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/time of last update to asset.
Date in ISO8601 format.
timestamp=2011-02-13T16:18:00Z
title Match value against the title field of media.
to_date End value for date range query.
Date in ISO8601 format.
to_date=2011-02-13T16:18:00Z
to_duration End value of duration range query.
Integer in seconds.
to_duration=300
to_publishdate End value for publishdate range query.
Date in ISO8601 format.
to_publishdate=2011-02-13T16:18:00Z
to_rating [1-5] End value of rating range query. to_rating=4
type news, video, image, audio, publication_issue, webcast. type=image

(specify multiple types
with list notation)


&type[]=image&type[]=video
unit_name Full name of unit credited with media asset.
unit DVIDS abbreviation of unit credited with media asset.
unit_rollup [0-1] default 0. Include results from subordinate units.

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