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
Accept-encoding: gzip, deflate
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Date: Wed, 22 May 2019 15:31:35 GMT
Server: Apache/2.4.18 (Ubuntu)
Access-control-allow-origin: *
Content-length: 1614
Content-type: application/json; charset=utf-8

            "category":"Press Release",
            "title":"Bulldog Brigade hosts NCO induction ceremony",
            "keywords":"Korea, NCO, USARPAC, induction, Iron Soldiers, PACOM, Republic of Korea, readiness, Army, USFK, ROK Army, Warrior Division, Bulldog Brigade, Always Ready, Eighth U.S. Army, 2nd Infantry Division ROK-U.S. Combined Division, America\u2019s Tank Division, Strong Alliance, Iron Support",
            "credit":"SGT Alon Humphrey",
            "country":"South Korea",
            "state":"Seoul Teugbyeolsi [Seoul-T'ukpyolshi]",
            "unit_name":"3rd Armored Brigade Combat Team, 1st Armored Division Public Affairs",
            "short_description":"CAMP HUMPHREYS, Republic of Korea \u2013 More than 90 3rd Armored Brigade Combat Team, 1st Armored Division Soldiers sat patiently waiting for a formal welcome into the NCO corps.",
            "category":"Island Insight",
            "title":"Island Insight - May 21, 2019",
            "unit_name":"U.S. Army Garrison Rock Island Arsenal",

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
Combat Operations
Horn of Africa
Press Release for news
In The Fight
Series for video
Newscasts for audio.

(specify multiple categories
with list notation)

city City where media was captured. city=Atanta
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.
duration Length in seconds of media asset.
Only applies to video, audio, and greetings.
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)
from_date Begin value for date range query.
Date in ISO8601 format.
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_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.
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.
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.

(specify multiple tags
with list notation)

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.
title Match value against the title field of media.
to_date End value for date range query.
Date in ISO8601 format.
to_duration End value of duration range query.
Integer in seconds.
to_publishdate End value for publishdate range query.
Date in ISO8601 format.
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)

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
  • width: [int] type=image: Width of original image