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
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: Sat, 20 Apr 2024 23:43:54 GMT
Server: Apache
Access-control-allow-origin: *
X-cache: Miss from cloudfront
Via: 1.1 7610b91e2653cd801af5fb6517906ed4.cloudfront.net (CloudFront)
X-amz-cf-pop: IAD66-C1
Alt-svc: h3=":443"; ma=86400
X-amz-cf-id: y_wYDphJrS0HED60Kas9DnsGFjdyxypxd3mGCkm5B_SuJx-YsKLlMg==

{
    "page_info":{
        "total_results":1000,
        "results_per_page":2
    },
    "results":[
        {
            "publishdate":"2024-03-11T13:57:06Z",
            "date":"2024-11-03T04:00:00Z",
            "category":"Briefings",
            "aspect_ratio":"16:9",
            "duration":860,
            "hd":true,
            "title":"Accession of Sweden: Joint press statements by the NATO Secretary General and the Prime Minister of Sweden (Q&A)",
            "id":"video:915363",
            "type":"video",
            "keywords":"NATO, SG, SG remarks",
            "country":"Belgium",
            "unit_name":"Natochannel",
            "branch":"Joint",
            "timestamp":"2024-03-11T14:14:05.212Z",
            "thumbnail":"https:\/\/d1ldvf68ux039x.cloudfront.net\/thumbs\/frames\/video\/2403\/915363\/DOD_110171349.0000001\/122x92_q95.jpg",
            "thumb_width":122,
            "thumb_height":92,
            "short_description":"Joint press statements by NATO Secretary General Jens Stoltenberg and the Prime Minister of Sweden Ulf Kristersson ahead of the flag-raising ceremony to mark Sweden\u2019s accession to NATO on 11 March 2024 in Brussels.",
            "hls_url":"https:\/\/api.dvidshub.net\/hls\/video\/915363.m3u8?api_key=key-XXXXXXXXXXXXX",
            "url":"https:\/\/www.dvidshub.net\/video\/915363\/accession-sweden-joint-press-statements-nato-secretary-general-and-prime-minister-sweden-qa",
            "date_published":"2024-03-11T13:57:06Z"
        },
        {
            "publishdate":"2024-03-14T16:57:50Z",
            "date":"2024-11-03T04:00:00Z",
            "category":"B-Roll",
            "aspect_ratio":"16:9",
            "duration":808,
            "hd":true,
            "title":"NATO Allies conduct drills in exercise Dragon 2024",
            "id":"video:915828",
            "type":"video",
            "keywords":"exercise, natochannel, Steadfast Defender 24",
            "country":"Poland",
            "unit_name":"Natochannel",
            "branch":"Joint",
            "timestamp":"2024-03-20T11:04:05.545Z",
            "thumbnail":"https:\/\/d1ldvf68ux039x.cloudfront.net\/thumbs\/frames\/video\/2403\/915828\/DOD_110179537.0000001\/122x92_q95.jpg",
            "thumb_width":122,
            "thumb_height":92,
            "short_description":"Nine NATO Allies are gathering in the Polish-led multinational exercise \u201cDragon 2024\u201d. The exercise involves infantry operations and urban combat, and a live-fire tank exercise.\r\nSynopsis\r\nNine Allies are participating in the Polish-led multinational exercise \u201cDragon 2024\u201d. It involves troops from France, Germany, Lithuania, Poland, Slovenia, Spain, T\u00fcrkiye, the United Kingdom and the United States. The exercise helps NATO Allies train on military operations at both the tactical and operational level. It involves training on infantry operations and urban combat, and a live-fire tank exercise.\r\nExercise Dragon falls under Steadfast Defender 2024 \u2013 NATO\u2019s largest exercise in decades. Steadfast Defender 2024 is testing the Alliance\u2019s new regional defence plans with forces practising rapid deployment and combat in both Norway and Poland. It is enabling Allies to demonstrate their ability to command and control large ground, air and sea forces across significant distances, within the Euro-Atlantic area.\r\nExercise Dragon 2024 runs from 4 to 14 March.\r\nFootage includes shots of a Polish Pilica anti-aircraft system operating, US troops practising tank recovery operations, M1 Abrams tanks firing, troops embarking and disembarking from a Bradley Fighting Vehicle, and trench-clearing operations, as well as French infantry firing, and going through urban combat training. Footage also includes interviews with two French and one US officer.\r\nTranscript\r\n\u2014SHOTLIST\u2014\r\n(00:00) VARIOUS SHOTS \u2013 POLISH PILICA ANTI-AIRCRAFT SYSTEM TRACKING A DRONE\r\n(00:21) CLOSE-UP SHOTS \u2013 SLOW MOTION SHOTS OF POLISH ANTI-AIRCRAFT SYSTEM BEING OPERATED\r\n(01:08) WIDE SHOTS \u2013 US ARMOURED RECOVERY VEHICLE PREPARING MOVING IN PLACE FOR A RECOVERY OPERATION DURING THE EXERCISE\r\n(01:28) VARIOUS SHOTS \u2013 US ARMY SOLDIERS ENGAGING IN A RECOVERY OPERATION DURING THE EXERCISE\r\n(02:17) VARIOUS SHOTS \u2013 M1 ABRAMS TANKS MANOEUVRING TO A FIRING RANGE\r\n(02:31) WIDE SHOT \u2013 US ARMOURED RECOVERY VEHICLE MOVING TO A FIRING RANGE\r\n(02:40) WIDE SHOT \u2013 M1 ABRAMS TANKS STANDING BY ON A FIRING RANGE\r\n(02:45) VARIOUS SHOTS \u2013 M1 ABRAMS TANKS FIRING\r\n(02:58) VARIOUS SHOTS \u2013 M1 ABRAMS TANKS MANOEUVRING BACK TO BASE\r\n(03:35) VARIOUS SHOTS \u2013 FRENCH VBCI VEHICLES (ARMOURED INFANTRY FIGHTING VEHICLE) MANOEUVRING IN AN OPEN FIELD\r\n(04:04) VARIOUS SHOTS \u2013 FRENCH TROOPS SETTING UP POSITION AND PREPARING TO OPEN FIRE ON A FIRING RANGE DURING THE EXERCISE\r\n(04:39) VARIOUS SHOTS \u2013 FRENCH TROOPS OPENING FIRE ON A FIRING RANGE DURING THE EXERCISE\r\n(04:56) WIDE SHOT \u2013 FRENCH TROOPS STANDING BY ON A FIRING RANGE\r\n(05:00) WIDE SHOT \u2013 FRENCH TROOPS EMBARKING IN AN ARMOURED VBCI\r\n(05:08) VARIOUS SHOTS \u2013 FRENCH ARMOURED VBCI CLOSING ITS HATCH AND DRIVING AWAY\r\n(05:23) MEDIUM SHOT \u2013 A US ARMY BRADLEY FIGHTING VEHICLE AND US TROOPS MOVING INTO POSITION FOR AN INFANTRY TRENCH-CLEARING EXERCISE\r\n(05:34) WIDE SHOT \u2013 US TROOPS DISEMBARKING FROM A US ARMY BRADLEY FIGHTING VEHICLE\r\n(05:39) WIDE SHOT \u2013 A US ARMY BRADLEY FIGHTING VEHICLE CLOSING ITS HATCH, WHILE OTHER BRADLEYS MOVE INTO POSITION ON A FIRING RANGE\r\n(05:45) VARIOUS SHOTS \u2013 US TROOPS MOVING THROUGH A TRENCH COMPLEX DURING A TRENCH-CLEARING OPERATION DURING THE EXERCISE\r\n(06:00) VARIOUS SHOTS \u2013 US TROOPS SETTING UP POSITION IN A TRENCH COMPLEX\r\n(06:37) VARIOUS SHOTS \u2013 US TROOPS MOVING OUT OF THE TRENCH COMPLEX\r\n(06:46) WIDE SHOT \u2013 A US ARMY BRADLEY FIGHTING VEHICLE MANOEUVRING AND OPENING HATCH FOR US TROOPS\r\n(06:57) VARIOUS SHOTS \u2013 US TROOPS EMBARKING ON A BRADLEY FIGHTING VEHICLE\r\n(07:12) VARIOUS SHOTS - A FRENCH SOLDIER FIRING A MACHINE GUN FROM A WINDOW DURING URBAN COMBAT TRAINING\r\n(07:24) VARIOUS SHOTS - FRENCH TROOPS MANOEUVRING IN, OUT AND AROUND BUILDINGS DURING URBAN COMBAT TRAINING\r\n\r\n(08:04) SOUNDBITE (FRENCH) - Captain Pierre-Louis, Deputy Officer, 5th Dragons Regiment, French Army\r\n\u201cWe\u2019re participating in the Polish exercise, \u201cDragon 24\u201d. It\u2019s a Polish national exercise, some NATO members were invited, France being one of the invitees.\u201d\r\n\r\n(08:15) SOUNDBITE (FRENCH) - Captain Pierre-Louis, Deputy Officer, 5th Dragons Regiment, French Army\r\n\u201cThe exercise consists of three phases. A logistical deployment from France. A tactical and technical deployment on the ground, which lasted from our arrival on 21 February up until two days ago, in which we had a wet-gap crossing of the Vistula, a 300-km advance to contact. We\u2019re now starting the last phase, a live-fire phase with a combined-arms, joint, Allied exercise.\u201d\r\n\r\n(08:42) SOUNDBITE (FRENCH) - Captain Pierre-Louis, Deputy Officer, 5th Dragons Regiment, French Army\r\n\u201cWe haven\u2019t done the armoured vehicle part since 1996 and now we are doing it in a joint and multinational setting. So it\u2019s especially interesting for us. From my unit\u2019s point of view, it allows us to push our vehicles to their limits. We don\u2019t often do 300 km in a row with a battle tank.\u201d\r\n\r\n(09:00) SOUNDBITE (FRENCH) - Captain Pierre-Louis, Deputy Officer, 5th Dragons Regiment, French Army\r\n\u201cWe\u2019re entering a new era. Until now we were in a low-intensity era. The balance of power was systematically in our favour. Today with the feedback we\u2019re getting from everything that\u2019s happening all around the world, we\u2019ve entered a new phase where we\u2019re going to focus on high intensity. Instead of having a fight between the strong and the weak, we\u2019re now going to have a fight between the strong and the strong; with the same technological capabilities, the same infrastructure, with sometimes situations where we\u2019ll be destabilised. It\u2019s something we feel when we train and we\u2019re taking into account the whole variety of threats, that have been present since 2022 but also for the last five to six years in other parts of the world.\r\n\r\n(09:38) SOUNDBITE - Lieutenant Colonel Kenton Komives, Commander, 3-15 Infantry Battalion, US Army\r\n\u201cExercise Dragon, we brought the battalion, we\u2019re an infantry battalion. So we have two infantry companies, with one armoured company, which is tanks. What we\u2019re doing here during this exercise is lots of things. Starting with the Vistula River, we did a river-crossing down in that town and then we came up to here to do live-fire training. While we\u2019re here we\u2019re doing a lot of interoperability training, learning how other nations and NATO fight, and then how we can fight together to be better as an organisation.\u201d\r\n\r\n(10:10) SOUNDBITE - Lieutenant Colonel Kenton Komives, Commander, 3-15 Infantry Battalion, US Army\r\n\u201cSo everything we do, we fight as a team, we\u2019re never going to fight by ourselves. So having such a strong alliance that we have, and actually seeing all these nations being here is absolutely important for us to see how we can fight, how our equipment talks to each other and how we work together. It\u2019s absolutely important to fight as an alliance and it\u2019s just been a great experience for everybody.\u201d\r\n\r\n(10:29) SOUNDBITE - Lieutenant Colonel Kenton Komives, Commander, 3-15 Infantry Battalion, US Army\r\n\u201cWhen training in the US, you\u2019re only with the other American units, so we understand the equipment. All of our equipment works together very well. But then when we come and train with all these different partners that we have, you have to get creative. How do we talk to each other, how do we communicate, how do we use their equipment, how do we use our equipment to get the end state that we\u2019re looking at? It\u2019s just being a really good force and a really good alliance.\u201d\r\n\r\n(10:54) SOUNDBITE - Lieutenant Colonel Kenton Komives, Commander, 3-15 Infantry Battalion, US Army\r\n\u201cThe strongest military alliance, even today on the 25th anniversary of Poland joining NATO, being part of that ceremony today shows you how strong the bond is. And it does exactly what we\u2019re supposed to do. We\u2019re deterring aggression, we\u2019re here doing that, and then as we\u2019re doing that, the world knows how strong we are. That alliance alone and NATO coming together and showing what we can do is absolutely important for the world and for Europe, absolutely.\r\n\r\n(11:21) SOUNDBITE - Colonel Philippe, Commander, 35th Infantry Regiment, French Army\r\n\u201cMy battlegroup is composed of different enforcements, belonging on my command post to IFV companies coming from my regiment. But I\u2019m also in force with the 7th Armoured Brigade, French Army. Different elements: one Leclerc tank company, and also one combat engineers and some logistical enforcement.\u201d\r\n\r\n(11:44) SOUNDBITE - Colonel Philippe, Commander, 35th Infantry Regiment, French Army\r\n\u201cIt\u2019s very important for the French land forces to work with the other NATO armies because it allowed us to discover new kinds of terrain in the east part of Europe.\u201d\r\n\r\n(11:54) SOUNDBITE - Colonel Philippe, Commander, 35th Infantry Regiment, French Army\r\n\u201cThe French battlegroup embedded into the Dragon 24 exercise is currently under the orders of the 10th Armoured Brigade from the Polish Army in close coordination with a German battalion and a Polish tank battalion.\u201d\r\n\r\n(12:11) SOUNDBITE - Colonel Philippe, Commander, 35th Infantry Regiment, French Army\r\n\u201cThis kind of exercise on the anniversary of NATO is important because it\u2019s our common guarantee to maintain peace and safety in Europe. It\u2019s also a good occasion for us to exchange about training, about our procedures and to have a concrete human and ground knowledge from each other.\u201d\r\n\r\n(12:33) SOUNDBITE - Colonel Philippe, Commander, 35th Infantry Regiment, French Army\r\n\u201cWe find good opportunities to learn lessons from our Polish and US and German colleagues because we discover some elements about wet-gap crossing, for example. We do also wet-gap crossing in France, as you can imagine, but not at the level of a brigade.\u201d\r\n\r\n(12:55) SOUNDBITE - Colonel Philippe, Commander, 35th Infantry Regiment, French Army\r\n\u201cSince the beginning of the crisis in Ukraine, I think these kinds of exercises are a bit more serious from the top to the private. Because everyone understands that it\u2019s a key element, that we need to be ready to protect our territories and the territories of our Allies on the eastern flank. And also the size of the exercise has increased from brigade to division level, and Dragon 24 is part of Steadfast Defender 24, which is the biggest exercise since the 80s in Europe.\u201d\r\n\r\n## END ##\r\nUsage rights\r\nThis media asset is free for editorial broadcast, print, online and radio use. It is restricted for use for other purposes.",
            "hls_url":"https:\/\/api.dvidshub.net\/hls\/video\/915828.m3u8?api_key=key-XXXXXXXXXXXXX",
            "url":"https:\/\/www.dvidshub.net\/video\/915828\/nato-allies-conduct-drills-exercise-dragon-2024",
            "date_published":"2024-03-14T16:57:50Z"
        }
    ]
}

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
USSPACECOM
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, graphics. 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