Difference between revisions of "Guide Service"

From MythTV Official Wiki
Jump to: navigation, search
Line 288: Line 288:
 
Example Query:
 
Example Query:
  
<code>http://192.168.1.30:6544/Guide/GetProgramList?StartTime=2018-01-13T18:00:00&EndTime=2018-01-13T19:00:00&ChanId=15001&Details=true</code>
+
<code>http://BackendServerIP:6544/Guide/GetProgramList?StartTime=2018-01-13T18:00:00&EndTime=2018-01-13T19:00:00&ChanId=15001&Details=true</code>
  
 
Example Return:
 
Example Return:
Line 380: Line 380:
 
         </Program>
 
         </Program>
 
         <Program>
 
         <Program>
             <StartTime>2018-01-13T18:00:00Z</StartTime>
+
             ...
            <EndTime>2018-01-13T18:40:00Z</EndTime>
 
            <Title>And They're Off! For Sport Relief</Title>
 
            <SubTitle/>
 
            <Category>Game show</Category>
 
            <CatType>series</CatType>
 
            <Repeat>false</Repeat>
 
            <VideoProps>0</VideoProps>
 
            <AudioProps>0</AudioProps>
 
            <SubProps>0</SubProps>
 
            <SeriesId>EP02847709</SeriesId>
 
            <ProgramId>EP028477090002</ProgramId>
 
            <Stars>0</Stars>
 
            <LastModified>2018-01-13T18:00:00Z</LastModified>
 
            <ProgramFlags>0</ProgramFlags>
 
            <Airdate>2018-01-13</Airdate>
 
            <Description>
 
            Five celebrities battle it out in five fun but filthy races while in the studio, five contestants try to pick the winner.
 
            </Description>
 
            <Inetref/>
 
            <Season>1</Season>
 
            <Episode>2</Episode>
 
            <TotalEpisodes>6</TotalEpisodes>
 
            <FileSize>0</FileSize>
 
            <FileName/>
 
            <HostName/>
 
            <Channel>
 
                <ChanId>15001</ChanId>
 
                <ChanNum>1</ChanNum>
 
                <CallSign>BBC1NW</CallSign>
 
                <IconURL>/Guide/GetChannelIcon?ChanId=15001</IconURL>
 
                <ChannelName>BBC One (North West)</ChannelName>
 
                <MplexId>285</MplexId>
 
                <ServiceId>4168</ServiceId>
 
                <ATSCMajorChan>0</ATSCMajorChan>
 
                <ATSCMinorChan>0</ATSCMinorChan>
 
                <Format>Default</Format>
 
                <FrequencyId/>
 
                <FineTune>0</FineTune>
 
                <ChanFilters/>
 
                <SourceId>15</SourceId>
 
                <InputId>0</InputId>
 
                <CommFree>false</CommFree>
 
                <UseEIT>false</UseEIT>
 
                <Visible>true</Visible>
 
                <XMLTVID>I24325.json.schedulesdirect.org</XMLTVID>
 
                <DefaultAuth/>
 
                <ChannelGroups/>
 
                <Inputs/>
 
                <Programs/>
 
            </Channel>
 
            <Recording>
 
                <RecordedId>0</RecordedId>
 
                <Status>Unknown</Status>
 
                <Priority>0</Priority>
 
                <StartTs xsi:nil="true"/>
 
                <EndTs xsi:nil="true"/>
 
                <FileSize>0</FileSize>
 
                <FileName/>
 
                <HostName/>
 
                <LastModified xsi:nil="true"/>
 
                <RecordId>0</RecordId>
 
                <RecGroup/>
 
                <PlayGroup/>
 
                <StorageGroup/>
 
                <RecType>0</RecType>
 
                <DupInType>1</DupInType>
 
                <DupMethod>1</DupMethod>
 
                <EncoderId>0</EncoderId>
 
                <EncoderName/>
 
                <Profile/>
 
            </Recording>
 
            <Artwork>
 
                <ArtworkInfos/>
 
            </Artwork>
 
 
         </Program>
 
         </Program>
 
         <Program>
 
         <Program>
             <StartTime>2018-01-13T18:40:00Z</StartTime>
+
             ...
            <EndTime>2018-01-13T19:25:00Z</EndTime>
 
            <Title>Pointless Celebrities</Title>
 
            <SubTitle>Academia</SubTitle>
 
            <Category>Game show</Category>
 
            <CatType>series</CatType>
 
            <Repeat>false</Repeat>
 
            <VideoProps>0</VideoProps>
 
            <AudioProps>0</AudioProps>
 
            <SubProps>0</SubProps>
 
            <SeriesId>EP01363214</SeriesId>
 
            <ProgramId>EP013632140168</ProgramId>
 
            <Stars>0</Stars>
 
            <LastModified>2018-01-13T18:40:00Z</LastModified>
 
            <ProgramFlags>0</ProgramFlags>
 
            <Airdate>2018-01-13</Airdate>
 
            <Description>
 
            Featuring Dr John Cooper Clarke, Suzannah Lipscomb, Mark Horton, Alice Roberts, Maggie Aderin-Pocock, Jim Al-Khalili, Robin Ince and Kate Williams.
 
            </Description>
 
            <Inetref/>
 
            <Season>10</Season>
 
            <Episode>38</Episode>
 
            <TotalEpisodes>0</TotalEpisodes>
 
            <FileSize>0</FileSize>
 
            <FileName/>
 
            <HostName/>
 
            <Channel>
 
            <ChanId>15001</ChanId>
 
            <ChanNum>1</ChanNum>
 
            <CallSign>BBC1NW</CallSign>
 
            <IconURL>/Guide/GetChannelIcon?ChanId=15001</IconURL>
 
            <ChannelName>BBC One (North West)</ChannelName>
 
            <MplexId>285</MplexId>
 
            <ServiceId>4168</ServiceId>
 
            <ATSCMajorChan>0</ATSCMajorChan>
 
            <ATSCMinorChan>0</ATSCMinorChan>
 
            <Format>Default</Format>
 
            <FrequencyId/>
 
            <FineTune>0</FineTune>
 
            <ChanFilters/>
 
            <SourceId>15</SourceId>
 
            <InputId>0</InputId>
 
            <CommFree>false</CommFree>
 
            <UseEIT>false</UseEIT>
 
            <Visible>true</Visible>
 
            <XMLTVID>I24325.json.schedulesdirect.org</XMLTVID>
 
            <DefaultAuth/>
 
            <ChannelGroups/>
 
            <Inputs/>
 
            <Programs/>
 
        </Channel>
 
        <Recording>
 
            <RecordedId>0</RecordedId>
 
            <Status>Unknown</Status>
 
            <Priority>0</Priority>
 
            <StartTs xsi:nil="true"/>
 
            <EndTs xsi:nil="true"/>
 
            <FileSize>0</FileSize>
 
            <FileName/>
 
            <HostName/>
 
            <LastModified xsi:nil="true"/>
 
            <RecordId>0</RecordId>
 
            <RecGroup/>
 
            <PlayGroup/>
 
            <StorageGroup/>
 
            <RecType>0</RecType>
 
            <DupInType>1</DupInType>
 
            <DupMethod>1</DupMethod>
 
            <EncoderId>0</EncoderId>
 
            <EncoderName/>
 
            <Profile/>
 
        </Recording>
 
        <Artwork>
 
            <ArtworkInfos/>
 
        </Artwork>
 
 
         </Program>
 
         </Program>
 
     </Programs>
 
     </Programs>
Line 537: Line 389:
 
</pre>
 
</pre>
  
 +
==GetChannelGroupList==
 +
 +
The <span style="color:LimeGreen">GetChannelGroupList</span> API takes the following arguments:
 +
 +
:<span style="color:SteelBlue">IncludeEmpty</Span> ('''Optional''')
 +
:: '''Parameter Type:''' bool
 +
:: Whether to include groups that contain no channels.
 +
 +
Example Query:
 +
 +
<code>http://BackendServerIP:6544/Guide/GetChannelGroupList?IncludeEmpty=true</code>
 +
 +
Example Return:
  
 +
List of program groups
 
[[Category:Services_API]]
 
[[Category:Services_API]]

Revision as of 19:22, 13 January 2018

What is this?

See Services API


Guide Service API List

API Command POST Required? Description
GetProgramGuide No The the guide information for a particular time period and set of channels
GetProgramDetails No Get the detailed guide information for a particular program starting at a particular time on a particular channel.
GetChannelIcon No Get the icon file for a given channel.
GetProgramList No Get a filtered list of programs matching the given search criteria.
GetChannelGroupList No Get the list of channel groups.
GetCategoryList No Get a list of program categories.
GetStoredSearches No Get the list of stored searches.
AddToChannelGroup Yes Add a given channel to a channel group.
RemoveFromChannelGroup Yes Remove a given channel from a channel group.

Guide APIs

GetProgramGuide

The GetProgramGuide API takes the following arguments:

StartTime (Required)
Parameter Type: String
The start time for the guide. This should be in MySQL ISO format, eg: 2011-08-29 18:59:00. You can replace the space with %20 or T.
EndTime (Required)
Parameter Type: String
The end time for the guide. This should be in MySQL ISO format, eg: 2011-08-29 18:59:00. You can replace the space with %20 or T.
StartChanId (Optional)
Parameter Type: Integer
The starting channel id for the guide information.
NumChannels (Optional)
Parameter Type: Integer
The number of channels to return in the guide information.
Details (Optional)
Parameter Type: Boolean
Return extensive details about the program data.

Example Query:

http://BackendServerIP:6544/Guide/GetProgramGuide?StartTime=2011-10-03T19:00:00&EndTime=2011-10-03T20:00:00&StartChanId=2066&NumChannels=10

Example Return:

<?xml version="1.0" encoding="UTF-8"?>
<ProgramGuide version="1.0" serializerVersion="1.1">
    <StartTime>2011-10-03T19:00:00</StartTime>
    <EndTime>2011-10-03T20:00:00</EndTime>
    <StartChanId>2066</StartChanId>
    <EndChanId>2066</EndChanId>
    <NumOfChannels>1</NumOfChannels>
    <Details>false</Details>
    <Count>3</Count>
    <AsOf>2011-10-02T17:01:34</AsOf>
    <Version>0.25.20110928-1</Version>
    <ProtoVer>69</ProtoVer>
    <Channels>
        <Channel>
            <ChanId>2066</ChanId>
            <ChanNum>185</ChanNum>
            <CallSign>HLMRK</CallSign>
            <IconURL></IconURL>
            <ChannelName>Hallmark Channel (Pacific)</ChannelName>
            <Programs>
                <Program>
                    <StartTime>2011-10-03T19:00:00</StartTime>
                    <EndTime>2011-10-03T20:00:00</EndTime>
                    <Title>Little House on the Prairie</Title>
                    <SubTitle>Make a Joyful Noise</SubTitle>
                    <Category>Drama</Category>
                    <CatType>series</CatType>
                    <Repeat>true</Repeat>
                    <Recording>
                        <Status>0</Status>
                        <Priority>0</Priority>
                        <StartTs></StartTs>
                        <EndTs></EndTs>
                        <RecordId>0</RecordId>
                        <RecGroup></RecGroup>
                        <PlayGroup></PlayGroup>
                        <RecType>0</RecType>
                        <DupInType>1</DupInType>
                        <DupMethod>1</DupMethod>
                        <EncoderId>0</EncoderId>
                        <Profile></Profile>
                    </Recording>
                </Program>
                 ...
            </Programs>
        </Channel>
    </Channels>
</ProgramGuide>

GetProgramDetails

The GetProgramDetails API takes the following arguments:

ChanId (Required)
Parameter Type: Integer
The database channel id for the guide item.
StartTime (Required)
Parameter Type: String
The recording start time for the item. This should be in MySQL ISO format, eg: 2011-08-29 18:59:00. You can replace the space with %20 or T.

Example Query:

http://BackendServerIP:6544/Guide/GetProgramDetails?StartTime=2011-10-03T19:00:00&ChanId=2066

Example Return:

<?xml version="1.0" encoding="UTF-8"?>
<Program version="1.1" serializerVersion="1.1">
    <StartTime>2011-10-03T19:00:00</StartTime>
    <EndTime>2011-10-03T20:00:00</EndTime>
    <Title>Little House on the Prairie</Title>
    <SubTitle>Make a Joyful Noise</SubTitle>
    <Category>Drama</Category>
    <CatType>series</CatType>
    <Repeat>true</Repeat>
    <SeriesId>EP00002633</SeriesId>
    <ProgramId>EP000026330155</ProgramId>
    <Stars>0</Stars>
    <FileSize>0</FileSize>
    <LastModified>2011-10-03T19:00:00</LastModified>
    <ProgramFlags>4096</ProgramFlags>
    <Hostname></Hostname>
    <Airdate>1981-01-26</Airdate>
     Joe Kagan works up the courage to court Hester Sue, and learns she plans to marry an undertaker (Mel Stewart).
    <Inetref></Inetref>
    <Season>0</Season>
    <Episode>0</Episode>
    <Channel>
        <ChanId>2066</ChanId>
        <ChanNum>185</ChanNum>
        <CallSign>HLMRK</CallSign>
        <IconURL></IconURL>
        <ChannelName>Hallmark Channel (Pacific)</ChannelName>
        <MplexId>0</MplexId>
        <TransportId>0</TransportId>
        <ServiceId>0</ServiceId>
        <NetworkId>0</NetworkId>
        <ATSCMajorChan>0</ATSCMajorChan>
        <ATSCMinorChan>0</ATSCMinorChan>
        <Format></Format>
        <Modulation></Modulation>
        <Frequency>0</Frequency>
        <FrequencyId></FrequencyId>
        <FrequencyTable></FrequencyTable>
        <FineTune>0</FineTune>
        <SIStandard></SIStandard>
        <ChanFilters></ChanFilters>
        <SourceId>0</SourceId>
        <InputId>0</InputId>
        <CommFree>0</CommFree>
        <UseEIT>false</UseEIT>
        <Visible>false</Visible>
        <XMLTVID></XMLTVID>
        <DefaultAuth></DefaultAuth>
        <Programs/>
    </Channel>
    <Recording>
        <Status>0</Status>
        <Priority>0</Priority>
        <StartTs></StartTs>
        <EndTs></EndTs>
        <RecordId>0</RecordId>
        <RecGroup></RecGroup>
        <PlayGroup></PlayGroup>
        <RecType>0</RecType>
        <DupInType>1</DupInType>
        <DupMethod>1</DupMethod>
        <EncoderId>0</EncoderId>
        <Profile></Profile>
    </Recording>
</Program>

GetChannelIcon

The GetChannelIcon API takes the following arguments:

ChanId (Required)
Parameter Type: Integer
The database channel id for the icon you desire.
Width (Optional)
Parameter Type: Integer
The scaled width to return the image. To preserve proper aspect, you may want to specify only one of width or height.
Height (Optional)
Parameter Type: Integer
The scaled height to return the image. To preserve proper aspect, you may want to specify only one of width or height.

Example Query:

http://BackendServerIP:6544/Guide/GetChannelIcon?ChanId=3736

Example Return:

The return for this command is a binary file which will be interpreted by your browser and downloaded or displayed as appropriate.


GetProgramList

The GetProgramList API takes the following arguments:

Count (Optional)
Parameter Type: Integer
Number of programs to fetch.
StartTime (Optional)
Parameter Type: String
The recording start time for the items. This should be in MySQL ISO format, eg: 2011-08-29 18:59:00. You can replace the space with %20 or T.
EndTime (Optional)
Parameter Type: String
The recording start time for the items. This should be in MySQL ISO format, eg: 2011-08-29 18:59:00. You can replace the space with %20 or T.
ChanId (Optional)
Parameter Type: Integer
The database channel id for the guide item.
TitleFilter (Optional)
Parameter Type: String
Only find programs matching the given title filter.
CategoryFilter (Optional)
Parameter Type: String
Only find programs matching the given category filter.
PersonFilter (Optional)
Parameter Type: String
Only find programs matching the given person filter.
KeywordFilter (Optional)
Parameter Type: String
Only find programs matching the given keyword filter.
OnlyNew (Optional)
Parameter Type: bool
Only find programs flagged as being new in the EPG.
Details (Optional)
Parameter Type: bool
Return some extra detail like recording status and channel info.
Sort (Optional)
Parameter Type: String
Change the sort order of the programs.
Descending (Optional)
Parameter Type: bool
Whether to sort ascending (default) or descending


Example Query:

http://BackendServerIP:6544/Guide/GetProgramList?StartTime=2018-01-13T18:00:00&EndTime=2018-01-13T19:00:00&ChanId=15001&Details=true

Example Return:

This XML file does not appear to have any style information associated with it. The document tree is shown below.
<ProgramList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0" serializerVersion="1.1">
<StartIndex>0</StartIndex>
<Count>3</Count>
<TotalAvailable>3</TotalAvailable>
<AsOf>2018-01-13T19:02:20Z</AsOf>
<Version>30.20171120-1</Version>
<ProtoVer>91</ProtoVer>
    <Programs>
        <Program>
            <StartTime>2018-01-13T17:50:00Z</StartTime>
            <EndTime>2018-01-13T18:00:00Z</EndTime>
            <Title>North West Tonight; Weather</Title>
            <SubTitle/>
            <Category>Newsmagazine</Category>
            <CatType>series</CatType>
            <Repeat>true</Repeat>
            <VideoProps>0</VideoProps>
            <AudioProps>0</AudioProps>
            <SubProps>0</SubProps>
            <SeriesId>EP01293915</SeriesId>
            <ProgramId>SH012939150000</ProgramId>
            <Stars>0</Stars>
            <LastModified>2018-01-13T17:50:00Z</LastModified>
            <ProgramFlags>4096</ProgramFlags>
            <Airdate>2004-11-15</Airdate>
            <Description>
            The latest news, sport and weather for the North West of England.
            </Description>
            <Inetref/>
            <Season>0</Season>
            <Episode>0</Episode>
            <TotalEpisodes>1</TotalEpisodes>
            <FileSize>0</FileSize>
            <FileName/>
            <HostName/>
            <Channel>
                <ChanId>15001</ChanId>
                <ChanNum>1</ChanNum>
                <CallSign>BBC1NW</CallSign>
                <IconURL>/Guide/GetChannelIcon?ChanId=15001</IconURL>
                <ChannelName>BBC One (North West)</ChannelName>
                <MplexId>285</MplexId>
                <ServiceId>4168</ServiceId>
                <ATSCMajorChan>0</ATSCMajorChan>
                <ATSCMinorChan>0</ATSCMinorChan>
                <Format>Default</Format>
                <FrequencyId/>
                <FineTune>0</FineTune>
                <ChanFilters/>
                <SourceId>15</SourceId>
                <InputId>0</InputId>
                <CommFree>false</CommFree>
                <UseEIT>false</UseEIT>
                <Visible>true</Visible>
                <XMLTVID>I24325.json.schedulesdirect.org</XMLTVID>
                <DefaultAuth/>
                <ChannelGroups/>
                <Inputs/>
                <Programs/>
            </Channel>
            <Recording>
                <RecordedId>0</RecordedId>
                <Status>Unknown</Status>
                <Priority>0</Priority>
                <StartTs xsi:nil="true"/>
                <EndTs xsi:nil="true"/>
                <FileSize>0</FileSize>
                <FileName/>
                <HostName/>
                <LastModified xsi:nil="true"/>
                <RecordId>0</RecordId>
                <RecGroup/>
                <PlayGroup/>
                <StorageGroup/>
                <RecType>0</RecType>
                <DupInType>1</DupInType>
                <DupMethod>1</DupMethod>
                <EncoderId>0</EncoderId>
                <EncoderName/>
                <Profile/>
            </Recording>
            <Artwork>
                <ArtworkInfos/>
            </Artwork>
        </Program>
        <Program>
            ...
        </Program>
        <Program>
            ...
        </Program>
    </Programs>
</ProgramList>

GetChannelGroupList

The GetChannelGroupList API takes the following arguments:

IncludeEmpty (Optional)
Parameter Type: bool
Whether to include groups that contain no channels.

Example Query:

http://BackendServerIP:6544/Guide/GetChannelGroupList?IncludeEmpty=true

Example Return:

List of program groups