Podcast API

GET /podcast/list

List of available podcasts

Example request:

GET /podcast/list?id[]=103&id[]=99&api_key=key-XXXXXXXXXXXXX HTTP/1.1
Host: api.dvidshub.net
Accept-encoding: gzip, deflate
Accept: application/json, text/javascript
Referer: https://api.dvidshub.net

Example response:

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: Apache
Access-control-allow-origin: *
Content-encoding: gzip
Content-length: 569
Date: Thu, 29 Jul 2021 17:04:59 GMT
Connection: keep-alive
Vary: Accept-Encoding

{
    "messages":[
        "max_results was not supplied.  A maximum of 50 results per page will be returned."
    ],
    "page_info":{
        "total_results":1,
        "results_per_page":50
    },
    "results":[
        {
            "id":"99",
            "title":"U.S. Army Bloggers Roundtable",
            "description":"The Army\u2019s Online and Social Media Division hosts Bloggers Roundtables - phone interviews that connect bloggers and online journalists to Senior Army Leaders and subject matter experts. Army Bloggers Roundtables focus on hot topics and exclusive opportunities for the online community such as smartphone technologies for Soldiers, uniform changes, physical training doctrine, and the drawdown in Iraq.",
            "unit_id":"361",
            "branch":"Army",
            "category":"Government & Organizations",
            "first_episode_date":"07-13-11 03:31 PM",
            "most_recent_episode_date":"04-17-15 01:25 PM",
            "tags":"",
            "thumbnail":"https:\/\/cdn.dvidshub.net\/media\/thumbs\/podcast\/images\/99\/122x92_q95.jpg"
        }
    ]
}

Query Parameters:

  • api_key: Public API access key issued by DVIDS (key-xxxxxxxxxxxxx)
  • id: Limit which podcasts are returned. Multiple ids can be be specified with the following syntax "&id[]=99&id=103"
  • prettyprint: [1] Spaces out JSON response in more readable format useful for debugging
  • 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
  • sortdir: One of asc, desc.
  • unit_id: [int] Unit id to retrieve contents for. | unit_id=127 | &unit_id[]=127&unit_id[]=43
  • branch: Branch name to retrieve contents for.
  • category: Category to retrieve contents for. Example: category=Health or category=News %26 Politics (for categories with & symbol) | &category[]=News %26 Politics&category[]=Government %26 Organizations
  • q: Full text search against title, description | q=today |
  • max_results: Maximum number of results to return.
  • page: [int] What page to load. Defaults to 1.
  • tags: Full text search against tags | tags=Dvids, Army |
  • unit: | DVIDS abbreviation of unit credited with media asset.| unit=DVIDSHUB | &unit[]=DVIDSHUB&unit[]=AFNA
  • from_date | Begin value for date range query. | from_date=2011-02-13 |
  • to_date | End value for date range query. | to_date=2011-02-13 |
  • unit_name | Full name of unit credited with media asset.| unit_name=DVIDS hub | &unit_name[]=DVIDS hub&unit_name[]=AFN Afghanistan|

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.

Response Fields:

  • id: Id of podcast
  • title: Title of podcast
  • description: Description of podcast
  • thumbnail: Url to resized image of podcast logo as specified by thumb_XXX params
  • unit_id: Id for the unit that produced this asset
  • branch: Name of branch that produced this asset
  • category: Category of podcast
  • first_episode_date: Date of first podcast episode published
  • most_recent_episode_date: Date of most recent podcast epidsode published
  • tags: Tags of podcast

GET /podcast/get

Get podcast contents

Example request:

GET /podcast/get?id=103&max_results=2&api_key=key-XXXXXXXXXXXXX HTTP/1.1
Host: api.dvidshub.net
Accept-encoding: gzip, deflate
Accept: application/json, text/javascript
Referer: https://api.dvidshub.net

Example response:

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: Apache
Access-control-allow-origin: *
Content-encoding: gzip
Content-length: 668
Date: Thu, 29 Jul 2021 17:05:02 GMT
Connection: keep-alive
Vary: Accept-Encoding

{
    "page_info":{
        "total_results":15,
        "results_per_page":2
    },
    "results":[
        {
            "id":9533,
            "asset_id":"video:136010",
            "type":"video",
            "title":"Arctic Ice Bridge Operations",
            "short_description":"Alaska's 2nd Engineer Brigade, 6th Engineer Battalion...",
            "date_published":"2012-01-27T00:01:36-05:00",
            "keywords":"Alaska, USRAK, U.S. Army Alaska, Engineers, 6th Eng. Bn, 2nd Engineer Bde, Brehl Garza",
            "date":"2012-01-25T00:00:00-05:00",
            "category":"Package",
            "aspect_ratio":"16:9",
            "duration":103,
            "hd":true,
            "credit":"Brehl Garza",
            "country":"US",
            "state":"AK",
            "city":"Delta Junction",
            "unit_name":"United States Army Alaska",
            "branch":"Army",
            "timestamp":"2014-08-03T08:26:49-04:00",
            "thumbnail":"https:\/\/cdn.dvidshub.net\/media\/thumbs\/frames\/video\/1201\/136010\/122x92_q95.jpg",
            "url":"https:\/\/www.dvidshub.net\/video\/136010\/arctic-ice-bridge-operations"
        },
        {
            "id":9124,
            "asset_id":"video:129163",
            "type":"video",
            "title":"U.S. Army Alaska Command Video",
            "short_description":"U.S. Army Alaska executes continuous training and...",
            "date_published":"2011-11-02T13:38:38-04:00",
            "keywords":"USARAK, Alaska",
            "date":"2011-11-01T00:00:00-04:00",
            "category":"Package",
            "aspect_ratio":"16:9",
            "duration":470,
            "hd":true,
            "credit":"Brehl Garza",
            "country":"US",
            "state":"AK",
            "city":"Joint Base Elmendorf-Richardson",
            "unit_name":"United States Army Alaska",
            "branch":"Army",
            "timestamp":"2014-08-03T07:57:40-04:00",
            "thumbnail":"https:\/\/cdn.dvidshub.net\/media\/thumbs\/frames\/video\/1111\/129163\/122x92_q95.jpg",
            "url":"https:\/\/www.dvidshub.net\/video\/129163\/us-army-alaska-command-video"
        }
    ]
}

Query Parameters:

  • api_key: Public API access key issued by DVIDS (key-xxxxxxxxxxxxx)
  • fields: Comma separated list of which fields to return
  • id: [int] Podcast id to retrieve contents for. Required.
  • max_results: [1-50] Maximum number of results to return per page. Default and maximum value are both 50.
  • page: [int] What page to load. Defaults to 1.
  • prettyprint: [int] Spaces out JSON response in more readable format useful for debugging
  • short_description_length: [1-300] Specify length of short_description up to 300 characters. Defaults to 60.
  • 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

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.

Response Fields:

  • asset_id: Asset id
  • 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
  • id: Podcast item id
  • short_description: Shortened version of asset's description. Adjusted via short_description_length param.
  • 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

GET /podcast/search

Get podcast contents

Example request:

GET /podcast/search?q=Leadership&branch=joint&unit_id=613&max_results=2&api_key=key-XXXXXXXXXXXXX HTTP/1.1
Host: api.dvidshub.net
Accept-encoding: gzip, deflate
Accept: application/json, text/javascript
Referer: https://api.dvidshub.net

Example response:

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: Apache
Access-control-allow-origin: *
Content-encoding: gzip
Content-length: 1103
Date: Thu, 29 Jul 2021 17:05:02 GMT
Connection: keep-alive
Vary: Accept-Encoding

{
    "page_info":{
        "total_results":4,
        "results_per_page":2
    },
    "results":[
        {
            "id":"10386",
            "podcast_date_published":"06-25-12 03:04 PM",
            "channel_id":"47",
            "title":"Developing Afghan Army Leadership",
            "description":"The Command and Staff College in Kabul offers the chance for Afghan army officers to do develop their skills. Students can chose to follow a variety of courses which run for up to eight months. French, Canadian and Turkish soldiers work at the site as mentors for the army leadership.",
            "keywords":"Mel Preen, high definition, Command and Staff College, Kabul, Afghanistan, French, Canadian, Turkish, mentorship",
            "type":"video",
            "type_id":"143671",
            "asset":{
                "date":"05-10-12 12:00 AM",
                "duration":"173",
                "category":"Package",
                "title":"Developing Afghan Army Leadership",
                "credit":"Melissa Preen",
                "id":"video:143671",
                "type":"video",
                "description":"The Command and Staff College in Kabul offers the chance for Afghan army officers to do develop their skills. Students can chose to follow a variety of courses which run for up to eight months. French, Canadian and Turkish soldiers work at the site as mentors for the army leadership.",
                "country":"AF",
                "city":"Kabul",
                "unit":"Natochannel",
                "branch":"Joint",
                "url":"https:\/\/www.dvidshub.net\/video\/143671\/developing-afghan-army-leadership",
                "date_published":"05-10-12 08:23 AM",
                "image":"https:\/\/cdn.dvidshub.net\/media\/frames\/video\/1205\/143671.jpg",
                "thumbnail":{
                    "url":"https:\/\/cdn.dvidshub.net\/media\/thumbs\/frames\/video\/1205\/143671\/122x92_q95.jpg",
                    "width":122,
                    "height":92
                }
            }
        },
        {
            "id":"33989",
            "podcast_date_published":"10-02-14 11:35 AM",
            "channel_id":"47",
            "title":"Afghan Sandhurst Graduation",
            "description":"More than 240 men have graduated from the Afghan National Army Officer Academy in Kabul. The academy is sometimes referred to as \u2018Sandhurst in the Sand\u2019 as it\u2019s modeled on the Royal Military Academy Sandhurst, in the UK. The graduates have spent the past year learning various skills including tactics and leadership. The footage includes shots of the parade ground, rows of soldiers in various uniforms and sound bites with Brigadier Bruce Russell, Chief Mentor, Afghan National Army Officer Academy and General Sher Mohammad Karimi, Afghan Army Chief of Staff. Also available in high definition.",
            "keywords":"",
            "type":"video",
            "type_id":"362203",
            "asset":{
                "date":"09-22-14 12:00 AM",
                "duration":"146",
                "category":"Package",
                "title":"Afghan Sandhurst Graduation With VO",
                "credit":"Courtesy",
                "id":"video:362203",
                "type":"video",
                "description":"More than 240 men have graduated from the Afghan National Army Officer Academy in Kabul. The academy is sometimes referred to as \u2018Sandhurst in the Sand\u2019 as it\u2019s modeled on the Royal Military Academy Sandhurst, in the UK. The graduates have spent the past year learning various skills including tactics and leadership. The footage includes shots of the parade ground, rows of soldiers in various uniforms and sound bites with Brigadier Bruce Russell, Chief Mentor, Afghan National Army Officer Academy and General Sher Mohammad Karimi, Afghan Army Chief of Staff. Also available in high definition.",
                "country":"AF",
                "city":"Kabul",
                "unit":"Natochannel",
                "branch":"Joint",
                "url":"https:\/\/www.dvidshub.net\/video\/362203\/afghan-sandhurst-graduation-with-vo",
                "date_published":"09-23-14 09:41 AM",
                "image":"https:\/\/cdn.dvidshub.net\/media\/frames\/video\/1409\/362203.jpg",
                "thumbnail":{
                    "url":"https:\/\/cdn.dvidshub.net\/media\/thumbs\/frames\/video\/1409\/362203\/122x92_q95.jpg",
                    "width":122,
                    "height":92
                }
            }
        }
    ]
}

Query Parameters:

  • id: Limit which podcasts are returned. Multiple ids can be be specified with the following syntax "&id[]=99&id=103"
  • podcast_id: Limit which podcasts episodes are returned. Multiple podcast ids can be be specified with the following syntax "&podcast_id[]=99&podcast_id=103"
  • unit_id: [int] Unit id to retrieve contents for.
  • branch: Army, Navy, Air Force, Marines, Coast Guard, Joint, Civilian | branch=Army |
  • q: Full text search against title, description | q=today |
  • keywords: Full text search against keywords | keywords=Dvids |
  • from_date | Begin value for date range query. | from_date=2011-02-13 |
  • to_date | End value for date range query. | to_date=2011-02-13 |
  • sortdir: One of asc, desc.

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.

Response Fields:

  • id: Podcast episode id
  • channel_id: Podcast episode channel id
  • podcast_date_published: Podcast episode channel id
  • title: Title of podcast episode
  • description: Description of the podcast episode
  • keywords: Comma separated list of keywords
  • type: Podcast asset type
  • type_id: Podcast asset id

  • date: Date when the asset was created
  • duration: [int] type=video|audio: Length of asset in seconds
  • category: Category of the asset
  • title: Title of asset
  • credit: Who created the asset
  • id: Asset id
  • type: Asset type
  • description: Description of the asset
  • country: Country where the asset was created
  • city: City where the asset was created
  • unit_name: Full name of unit credited with media asset.
  • branch: Name of branch that produced this asset
  • url: Url to asset on dvidshub.net
  • date_published: Date when the asset was published at DVIDS
  • image: Url to full resolution version of asset
  • thumbnail: Url to resized image of asset

GET /podcast/category

Get podcast categories

Example request:

GET /podcast/category?&api_key=key-XXXXXXXXXXXXX HTTP/1.1
Host: api.dvidshub.net
Accept-encoding: gzip, deflate
Accept: application/json, text/javascript
Referer: https://api.dvidshub.net

Example response:

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: Apache
Access-control-allow-origin: *
Content-encoding: gzip
Content-length: 239
Date: Thu, 29 Jul 2021 17:05:03 GMT
Connection: keep-alive
Vary: Accept-Encoding

{
    "messages":[
        "max_results was not supplied.  A maximum of 50 results per page will be returned."
    ],
    "page_info":{
        "total_results":8,
        "results_per_page":50
    },
    "results":[
        {
            "category":"Government & Organizations"
        },
        {
            "category":"News & Politics"
        },
        {
            "category":"TV & Film"
        },
        {
            "category":"Technology"
        },
        {
            "category":"Health"
        },
        {
            "category":"Education"
        },
        {
            "category":"Games & Hobbies"
        },
        {
            "category":"Arts"
        }
    ]
}

Query Parameters:


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.

Response Fields:

  • category: Category of the podcast channel