Programme Information
=====================

.. http:get:: /radiodns/spi/3.1/id/radiodns.api.bbci.co.uk/{service_id}/{date}_PI.xml

    Gets a Radio DNS Programme Information document. A valid API key is required.

    A successful request will receive a valid `Programme Information document <https://www.etsi.org/deliver/etsi_ts/102800_102899/102818/03.05.01_60/ts_102818v030501p.pdf>`_. It consists of a schedule of programmes for the given service and day, although a number of programmes for the previous and following day are also included. It is only possible to request programme information for up to one week before or after the current date; requests outside that range will result in a 404 response.

    A programme consists of a unique identifier; medium and long names; a location element containing start time and duration; optionally, short and long descriptions; and a link to the programme website.

    All dateTime and duration types are `standard XML schema data types <https://www.w3.org/TR/xmlschema-2/>`_.

    The ``shortId`` field should not be used, as it is set to ``0`` for every programme. This is because the field is restricted to being a 24-bit unsigned integer by ETSI TS 102 818 and the programme number on the end of a BBC CRID is larger than that. If you need an identifier for the programme, please use the ``id`` attribute (CRID) instead.

        **Parameters**

            - ``service_id``: A valid service identifier, e.g. ``p00fzl64``
            - ``date``: The schedule date being requested. The format is ``yyyyMMdd``, e.g. ``20220901``. If the date is greater than seven days before or seven days after the current date, a ``404 Not Found`` response will be returned

        **Responses**

            - ``200 OK``: The request was successful
            - ``400 Bad Request``: One or more of the supplied parameters is invalid
            - ``401 Unauthorized``: An API key was not supplied
            - ``403 Forbidden``: The supplied API key is invalid
            - ``404 Not Found``: The service identifier was not found, or the date requested was out of range

        **Example request**:

        .. sourcecode:: http

            GET /radiodns/spi/3.1/id/radiodns.api.bbci.co.uk/p00fzl86/20220825_PI.xml HTTP/1.1

        **Example response**:

        .. sourcecode:: http

            HTTP/1.1 200 OK
            Content-Type: application/xml

            <?xml version="1.0" encoding="utf-8"?>
            <epg>
                <schedule creationTime="2022-09-01T09:35:57Z" originator="BBC">
                    <scope startTime="2022-08-24T22:00:00Z" stopTime="2022-08-26T11:45:00Z"/>
                        <programme id="crid://bbc.co.uk/m/1226263" shortId="0">
                            <mediumName>Radio 1 Breakf…</mediumName>
                            <longName>Radio 1 Breakfast with Greg James - Scott Mills and Chris Stark - Unpopular Opinion Unleashed</longName>
                            <location>
                                <time time="2022-08-25T06:00:00Z" duration="PT03H00M00S"/>
                            </location>
                            <mediaDescription>
                                <multimedia url="https://ichef.bbci.co.uk/images/ic/1024x576/p0jd82jx.jpg"/>
                            </mediaDescription>
                            <mediaDescription>
                                <multimedia url="https://ichef.bbci.co.uk/images/ic/1920x1080/p0jd82jx.jpg"/>
                            </mediaDescription>
                            <mediaDescription>
                                <shortDescription>Scott and Chris join Greg to get everything off their chest on Unpopular Opinion.</shortDescription>
                            </mediaDescription>
                            <mediaDescription>
                                <longDescription>Scott and Chris join Greg to get everything off their chest on Unpopular Opinion. Plus Yesterday's Quiz, All the Latest Things, 10 Minute Takeover and all the usual nonsense.</longDescription>
                            </mediaDescription>
                            <memberOf id="crid://bbc.co.uk/b/7415250" shortId="0"/>
                            <link uri="https://www.bbc.co.uk/programmes/m001b50w" mimeValue="text/html" description="Website"/>
                            <link uri="dvb://233A..1A40;16AD" description="terrestrial_event_locator"/>
                            <link uri="crid://fp.bbc.co.uk/m/14IAL" description="terrestrial_programme_crid"/>
                        </programme>
                    </scope>
                </schedule>
            </epg>