====== HDHomeRun DVR XMLTV API access ======
<btn type="success" size="xs" icon="fa fa-chevron-left">[[:DVR|Go back to all DVR topics]]</btn>\\

<WRAP center info>
This is a mirror of the documentation from: https://github.com/Silicondust/documentation/wiki/XMLTV-Guide-Data
</WRAP>

<lead>XMLTV guide data is available for HDHomeRun customers to use with third party apps.</lead>

  * No account is required for access to 3 days of guide data.

  * A paid [[:DVR:activation|HDHomeRun DVR guide subscription]] is required to access 14 days of guide data.

====API URL====
<WRAP indent>

GET<code>https://api.hdhomerun.com/api/xmltv</code>

</WRAP>
====API Parameters====
<WRAP indent>

^ Parameter ^ Type ^ Description ^
| DeviceAuth | string | Concatenation of the DeviceAuth strings from all HDHomeRun tuners. This can be found from http://hdhomerun.local/discover.json and changes every 8 hours. |

OR

^ Parameter ^ Type ^ Description ^
| Email | string | Email address associated with the DVR account |
| DeviceIDs | string | Comma-separated list of DeviceIDs |

</WRAP>
==== Additional requirements ====
<WRAP indent>

  * The HTTP client must accept gzip encoding.
  * The DeviceAuth changes regularly and is valid for 16-24 hours. If using the DeviceAuth access approach the DeviceAuth must be read from the HDHomeRun tuner(s) to get the latest value each time this API is invoked.
  * Do not schedule the download for midnight or a fixed time each day - requests should be made at a random interval. For example, after downloading the xmltv guide, schedule the next download for 20 to 28 hours (randomized delay) in the future.

</WRAP>
==== Example ====
<WRAP indent>

<code>curl --compressed "https://api.hdhomerun.com/api/xmltv?Email=xxx&DeviceIDs=xxx,xxx,xxx" > guide.xml</code>

<code>curl --compressed "https://api.hdhomerun.com/api/xmltv?DeviceAuth=xxx" > guide.xml</code>

</WRAP>

====History====
<WRAP indent>
  * 20251026:
    * URL must be quoted in most shells.

  * 20251025:
    * New Email+DeviceIDs access approach.
    * Clarifications.

  * 20251023:
    * Add note regarding scheduling the download.

  * 20250928:
    * Initial documentation.


Copyright © 2016-2025 Silicondust USA Inc. <www.silicondust.com>.

</WRAP>

{{tag>DVR}}
{{tag>development}}