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, 18 Jan 2025 05:16:13 GMT
Server: Apache
Access-control-allow-origin: *
Content-encoding: gzip
Vary: accept-encoding
X-cache: Miss from cloudfront
Via: 1.1 bd3f4df95f7c836cc4eb6a22d92ac2c2.cloudfront.net (CloudFront)
X-amz-cf-pop: IAD12-P4
Alt-svc: h3=":443"; ma=86400
X-amz-cf-id: n9mkhsaBBYStogY9LH0IZqqQDLX32WLTo5LxNopYCPEbXAaFXaJaHQ==

{
    "page_info":{
        "total_results":1000,
        "results_per_page":2
    },
    "results":[
        {
            "publishdate":"2025-01-18T01:15:15Z",
            "date":"2025-01-17T05:00:00Z",
            "category":"Video Productions",
            "aspect_ratio":"16:9",
            "duration":4652,
            "hd":true,
            "title":"MCRD San Diego Lima Company Graduation - 1\/17\/25",
            "id":"video:949873",
            "type":"video",
            "keywords":"MCRD, Marine Corps Base Camp Pendleton, 3rd Recruit Training Battalion",
            "country":"United States",
            "state":"California",
            "city":"Marine Corps Base Camp Pendleton",
            "unit_name":"Marine Corps Recruit Depot, San Diego",
            "branch":"Marines",
            "timestamp":"2025-01-18T01:24:04.444Z",
            "thumbnail":"https:\/\/d1ldvf68ux039x.cloudfront.net\/thumbs\/frames\/video\/2501\/949873\/DOD_110773380.0000717\/122x92_q95.jpg",
            "thumb_width":122,
            "thumb_height":92,
            "short_description":"The new Marines of Lima Company, 3rd Recruit Training Battalion, graduated from Marine Corps Recruit Depot San Diego, JAN. 17, 2025. Graduation took place at the completion of the 13-week transformation which included training for drill, marksmanship, basic combat skills, and Marines Corps customs and traditions. Following graduation, the Marines were given 10 days of leave before taking the next step in training at the School of Infantry at Marine Corps Base Camp Pendleton, California.",
            "hls_url":"https:\/\/api.dvidshub.net\/hls\/video\/949873.m3u8?api_key=key-XXXXXXXXXXXXX",
            "url":"https:\/\/www.dvidshub.net\/video\/949873\/mcrd-san-diego-lima-company-graduation-1-17-25",
            "date_published":"2025-01-18T01:15:15Z"
        },
        {
            "publishdate":"2025-01-16T21:41:19Z",
            "date":"2025-01-16T16:37:00Z",
            "aspect_ratio":"landscape",
            "width":5892,
            "height":4000,
            "title":"From Humvees to cutting-edge tech: one man's remarkable 50 year military manufacturing career",
            "id":"image:8833012",
            "type":"image",
            "keywords":"Rock Island Arsenal, TACOM, Tank-automotive and Armament Command, RIA-JMTC, U.S. Army, Rock Island Arsenal - Joint Manufacturing and Technology Center",
            "credit":"Kendall Swank",
            "country":"United States",
            "state":"Illinois",
            "city":"Rock Island Arsenal",
            "unit_name":"Rock Island Arsenal-Joint Manufacturing and Technology Center",
            "branch":"Army",
            "timestamp":"2025-01-16T21:42:02.325Z",
            "short_description":"Richard Lorenzen has had a distinguished 50-year career,...",
            "thumbnail":"https:\/\/d1ldvf68ux039x.cloudfront.net\/thumbs\/photos\/2501\/8833012\/122x92_q95.jpg",
            "thumb_width":122,
            "thumb_height":92,
            "url":"https:\/\/www.dvidshub.net\/image\/8833012\/humvees-cutting-edge-tech-one-mans-remarkable-50-year-military-manufacturing-career",
            "date_published":"2025-01-16T21:41:19Z"
        }
    ]
}

Query Parameters:

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