Searching
Basic Search
Use this API to get a list of programmes or people from the Digiguide database, including any schedules, given a search phrase. The search uses fuzzy search technology so approximate matches are also returned.
| End Point | http://api.digiguide.tv/1.2/tv/search/ |
| Supported Responses | JSON |
| Supported Methods | GET or POST |
| URI Scheme | Either HTTP or HTTPS requests are supported. |
| User Authentication | Optional If an authenticated user is passed, then only schedule results for the users channel selection are returned. If no 'subscribed' authenticated user is passed, then only 3 search results are returned. |
Required Parameters
| appid=<yourappid> | Your unique and secret Application ID |
expression=<string> |
Partial or full phrase for searching. Case insensitive and will correctly find results even if accents are part of the name, e.g. "Pokémon". The expression can contain various filters to expand or narrow down the results. To perform an approximate search match, postfix each 'word' in the expression with a tilde '~' character. For example, pokemon~. You can also use boolean logic and quotes to better perform queries like: "True Blood". To perform field searches, add the field name and a colon with boolean logic. For example, "true blood" AND category:drama Field names that can be searched are shown below:
|
Optional Parameters
limit=<unsigned integer> |
When specified, limits the number of results to specified number; when omitted or an invalid value is specified will return 20 results (unless unsubscribed as detailed above) |
limitschedules=<unsigned integer> |
When specified, limits the number of schedules for each programme result to specified number; when omitted or an invalid value is specified will return 10 results (unless unsubscribed as detailed above) |
what=people |
When specified, does a search for people instead of programmes; when omitted will only search programmes |
what=schedules |
When specified, returns a 'schedules' property containing an array of schedule information |
what=oldschedules |
When specified, returns a 'schedules' array property which contains schedules that have already been broadcast. If this parameter is specified the 'what=schedules' is not required |
what=adult |
When specified, will include 'Adult' categorised programmes. Default is to not include them |
Successful Response
Matches are returned in order of relevance, with a maximum of 10 schedule results per match if schedules are requested and exist.
A programme search would return the following:
{
"success": true,
"results": [
{
"id": 663898,
"name": "True Blood",
"category": "Drama",
"year": 2008,
"rating": 4,
"seasons": 3,
"imageMain": {
"url": "http:\/\/i.digiguide.tv\/up\/0907\/1247864400-663898-TrueBlood-12471342240.jpg",
"width": 350,
"height": 192
},
"imageThumb": {
"url": "http:\/\/i.digiguide.tv\/up\/0907\/\/tn-1247864400-663898-TrueBlood-12471342240.jpg",
"width": 150,
"height": 150
},
"imageTinyThumb": {
"url": "http:\/\/i.digiguide.tv\/up\/0907\/\/ttn-1247864400-663898-TrueBlood-12471342240.jpg",
"width": 75,
"height": 75
},
"schedules": [
{
"channelID": "50253",
"channelName": "FX",
"startUTC": "1305237600",
"episodeTitle": "Release Me",
"specialEpisode": false,
"seasonNumber": "2",
"episodeNumber": "7"
},
{
"channelID": "50650",
"channelName": "FX HD",
"startUTC": "1305237600",
"episodeTitle": "Release Me",
"specialEpisode": false,
"seasonNumber": "2",
"episodeNumber": "7"
},
{
"channelID": "50456",
"channelName": "FX+",
"startUTC": "1305241200",
"episodeTitle": "Release Me",
"specialEpisode": false,
"seasonNumber": "2",
"episodeNumber": "7"
},
{
"channelID": "50253",
"channelName": "FX",
"startUTC": "1305324000",
"episodeTitle": "Timebomb",
"specialEpisode": false,
"seasonNumber": "2",
"episodeNumber": "8"
}
]
}
]
}
A person search would return the following:
{
"success": true,
"results": [
{
"id": 663898,
"name": "Brad Pitt",
"schedules": [
{
"channelID": "50253",
"channelName": "FX",
"startUTC": "1305237600",
"episodeTitle": "Release Me",
"specialEpisode": false,
"seasonNumber": "2",
"episodeNumber": "7"
},
{
"channelID": "50650",
"channelName": "FX HD",
"startUTC": "1305237600",
"episodeTitle": "Release Me",
"specialEpisode": false,
"seasonNumber": "2",
"episodeNumber": "7"
},
{
"channelID": "50456",
"channelName": "FX+",
"startUTC": "1305241200",
"episodeTitle": "Release Me",
"specialEpisode": false,
"seasonNumber": "2",
"episodeNumber": "7"
},
{
"channelID": "50253",
"channelName": "FX",
"startUTC": "1305324000",
"episodeTitle": "Timebomb",
"specialEpisode": false,
"seasonNumber": "2",
"episodeNumber": "8"
}
]
}
]
}