/searchBasic 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.netExample response:
HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Transfer-encoding: chunked
Connection: keep-alive
Date: Wed, 02 Apr 2025 21:29:35 GMT
Server: Apache
Access-control-allow-origin: *
Content-encoding: gzip
Vary: accept-encoding
X-cache: Miss from cloudfront
Via: 1.1 b467a4a34e9f37bba6d2f0aba8257b5e.cloudfront.net (CloudFront)
X-amz-cf-pop: IAD12-P4
Alt-svc: h3=":443"; ma=86400
X-amz-cf-id: ZcTBsUuPnt9UMxwlUxhVKc6kYxxJe7x9d_aa2H5C05QNqh3JkDGZHA==
{
"page_info":{
"total_results":1000,
"results_per_page":2
},
"results":[
{
"publishdate":"2025-04-02T21:04:47Z",
"date":"2025-04-02T16:03:00Z",
"category":"Mo'olelo",
"title":"Mo'olelo - April 2, 2025",
"id":"publication_issue:72930",
"type":"publication_issue",
"unit_name":"Commander Navy Region Hawaii",
"branch":"Navy",
"timestamp":"2025-04-02T21:05:03.487Z",
"date_published":"2025-04-02T21:04:47Z"
},
{
"publishdate":"2025-03-27T21:27:17Z",
"date":"2025-03-27T04:00:00Z",
"category":"Miscellaneous",
"title":"Secretary of the Army visits America\u2019s Tank Division and Fort Bliss",
"id":"news:493940",
"type":"news",
"keywords":"#Army250 #Readiness #Modernization #IronSoldiers",
"credit":"MAJ Arturo Rodriguez",
"country":"United States",
"state":"Texas",
"city":"Fort Bliss",
"unit_name":"1st Armored Division",
"branch":"Army",
"timestamp":"2025-03-29T06:00:03.821Z",
"short_description":"FORT BLISS, Texas \u2014 Secretary of the Army Dan Driscoll visited Fort Bliss March 25 and 26, touring one of the Army\u2019s premier power projection platforms for operations across the Western Hemisphere and beyond, marking his first official visit to the installation since his confirmation.",
"thumbnail":"https:\/\/d1ldvf68ux039x.cloudfront.net\/thumbs\/photos\/2503\/8939690\/122x92_q95.jpg",
"thumb_width":122,
"thumb_height":92,
"url":"https:\/\/www.dvidshub.net\/news\/493940\/secretary-army-visits-americas-tank-division-and-fort-bliss",
"date_published":"2025-03-27T21:27:17Z"
}
]
}| 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.
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
