Live API

GET /live/list

List of live events

Example request:

GET /live/list?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
Date: Mon, 13 Jul 2020 15:10:30 GMT
Server: Apache/2.4.43 (Ubuntu)
Access-control-allow-origin: *
Content-length: 1154
Content-type: application/json; charset=utf-8

{
    "results":[
        {
            "type":"live_webcasts",
            "id":"24434",
            "title":"DOD LIVE: USD(A&S) Ellen Lord virtual fireside chat w\/ Reagan Foundation on National Defense in the Age of COVID-19",
            "description":"Periscope (DOD)\r\nStream URL: rtmp:\/\/va.pscp.tv:80\/x\r\nStream Name: 93zra9f7pzx9\r\n\r\nFacebook\r\nServer URL: rtmps:\/\/live-api-s.facebook.com:443\/rtmp\/\r\nStream Key:\r\n10158316342000719?s_bl=1&s_ps=1&s_sw=0&s_vt=api-s&a=AbxP6X5ShCZ3V-Jv",
            "hashtag":"",
            "begin":"2020-07-16T15:30:00+00:00",
            "end":"2020-07-16T18:00:00+00:00",
            "url":"https:\/\/www.dvidshub.net\/webcast\/24434",
            "hls_url":"https:\/\/atl-cli-dvids-01.akamaized.net\/hls\/live\/2015608\/24434\/master.m3u8",
            "unit_id":"127"
        },
        {
            "type":"live_webcasts",
            "id":"24353",
            "title":"USAG Wiesbaden Change of Command",
            "description":"USAG Wiesbaden Change of Command, July 17, at Clay Kaserne, Wiesbaden. The event begins at 4 a.m. EDT.",
            "hashtag":"",
            "begin":"2020-07-17T07:50:00+00:00",
            "end":"2020-07-17T09:15:00+00:00",
            "url":"https:\/\/www.dvidshub.net\/webcast\/24353",
            "hls_url":"https:\/\/live-cdn.dvidshub.net\/webcast\/24353\/master.m3u8",
            "unit_id":"1583"
        }
    ],
    "current_time":"2020-07-13T15:10:30+00:00"
}

Query Parameters:

  • api_key: Public API access key issued by DVIDS (key-xxxxxxxxxxxxx)
  • from_date: Specify a date/time in ISO8601 format to return events newer than from_date
  • has_video_id: [1] If set only return events that have a video_id associated with it
  • hashtag: If set only return events with that hashtag specified
  • max_results: [1-50] Maximum number of results to return per page. Default and maximum value are both 50.
  • prettyprint: [1] Spaces out JSON response in more readable format useful for debugging
  • sort: One of begin, end
  • sortdir: One of asc, desc
  • 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
  • to_date: Specify a date/time in ISO8601 format to return events older than to_date
  • include_snippets: [0,1] default 0, include external live event HTML snippets such as embed codes

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 the live event
  • type: Type of live event (live_webcast, snippets)
  • begin: Date/time event starts in ISO8601 format
  • current_time: Current server date/time in ISO8601 format. Useful for calculating time offset between server and client to provide time sync
  • description: Event description
  • end: Date/time event ends in ISO8601 format
  • thumbnail: [array] Resized image of event poster as specified by thumb_XXX params
  • url: Url to asset on dvidshub.net
  • video_id: Returned if the live event has been linked to a video asset

GET /live/get

Get additional details about live event including links to feed(s)

Example request:

GET /live/get?id=3852&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
Date: Mon, 13 Jul 2020 15:10:30 GMT
Server: Apache/2.4.43 (Ubuntu)
Access-control-allow-origin: *
Content-length: 679
Content-type: application/json; charset=utf-8

{
    "current_time":"2020-07-13T15:10:30+00:00",
    "results":{
        "id":"3852",
        "title":"US Department of State Press Briefing",
        "description":"Marie Harf, US Department of State Deputy Spokesperson, will deliver the daily press briefing. Feed begins at 1:30 PM EDT.  *** Time subject to change.",
        "begin":"2014-04-03T17:25:00+00:00",
        "end":"2014-04-03T19:48:00+00:00",
        "hls_url":"https:\/\/api.dvidshub.net\/hls\/live\/3852.m3u8?api_key=key-XXXXXXXXXXXXX&dvrTime=1396545900",
        "thumbnail":{
            "url":"https:\/\/cdn.dvidshub.net\/media\/thumbs\/frames\/video\/1404\/326950\/122x92_q95.jpg",
            "width":122,
            "height":92
        },
        "url":"https:\/\/www.dvidshub.net\/webcast\/3852",
        "video_id":"326950",
        "unit_id":"127"
    }
}

Query Parameters:

  • api_key: Public API access key issued by DVIDS (key-xxxxxxxxxxxxx)
  • fields: Comma separated list of which fields to return
  • id: [int] Id of of the live event
  • 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
  • video_id: Returned if the current event has been linked to a video asset

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 the live event
  • begin: Date/time event starts in ISO8601 format
  • current_time: Current server date/time in ISO8601 format. Useful for calculating time offset between server and client to provide time sync
  • description: Event description
  • end: Date/time event ends in ISO8601 format
  • hls_url: Url to master m3u8 playlist for event
  • thumbnail: [array] Resized image of event poster as specified by thumb_XXX params
  • url: Url to asset on dvidshub.net
  • video_id: Returned if the live event has been linked to a video asset