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: Thu, 21 Nov 2024 08:57:47 GMT
Cache-control: no-cache, private
Access-control-allow-origin: *
Server: Apache
Set-cookie: session=expiry=1732180067198946;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: FwC7osWBYHXY2V0w5nnB97Y221oN_MvHcY7ty48ON7ke0I9wjAZKKw==

{
    "page_info":{
        "total_results":1000,
        "results_per_page":2
    },
    "results":[
        {
            "publishdate":"2024-11-20T13:55:28Z",
            "date":"2024-11-20T05:00:00Z",
            "category":"Newscasts",
            "duration":60,
            "title":"Air Force Radio News 20 November 2024",
            "id":"audio:83530",
            "type":"audio",
            "keywords":"Air Force, Innovation, Air Force Radio News, AFRN, Spark Tank",
            "credit":"SSgt Louis Koconis",
            "country":"United States",
            "unit_name":"Defense Media Activity - Air Force",
            "branch":"Joint",
            "timestamp":"2024-11-20T14:01:02.084Z",
            "short_description":"Today's story: Spark Tank winner revealed.",
            "thumbnail":"https:\/\/d1ldvf68ux039x.cloudfront.net\/thumbs\/frames\/audio\/2411\/83530\/122x92_q95.jpg",
            "thumb_width":122,
            "thumb_height":92,
            "url":"https:\/\/www.dvidshub.net\/audio\/83530\/air-force-radio-news-20-november-2024",
            "date_published":"2024-11-20T13:55:28Z"
        },
        {
            "publishdate":"2024-11-20T19:40:41Z",
            "date":"2024-11-20T05:00:00Z",
            "category":"Briefings",
            "aspect_ratio":"16:9",
            "duration":2774,
            "hd":true,
            "title":"Department of State Daily Press Briefing - November 20, 2024",
            "id":"video:944384",
            "type":"video",
            "keywords":"Mathew Miller",
            "country":"United States",
            "state":"District of Columbia",
            "unit_name":"U.S. Department of State",
            "branch":"Civilian",
            "timestamp":"2024-11-20T19:48:05.609Z",
            "thumbnail":"https:\/\/d1ldvf68ux039x.cloudfront.net\/thumbs\/frames\/video\/2411\/944384\/DOD_110695340.0000001\/122x92_q95.jpg",
            "thumb_width":122,
            "thumb_height":92,
            "short_description":"Department of State Daily Press Briefing - November 20, 2024",
            "hls_url":"https:\/\/api.dvidshub.net\/hls\/video\/944384.m3u8?api_key=key-XXXXXXXXXXXXX",
            "url":"https:\/\/www.dvidshub.net\/video\/944384\/department-state-daily-press-briefing-november-20-2024",
            "date_published":"2024-11-20T19:40:41Z"
        }
    ]
}

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
USINDOPACOM
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