Basic Usage
Programme and Schedule information are provided on a 'has data' basis. Therefore if there is no data, the property may not exist so this needs to be accounted for in any client application.
For example, when requesting schedules for a channel, if there is no episode title then the "episodeTitle" property will not appear within the object.
In some cases, the response data will be restricted for one of two reasons:
- No authenticated user is supplied
- An authenticated user is supplied but does not have a subscription to any Digiguide.tv Services
Where this is the case, the documentation would indicate the specific restriction applied and an additional response property "responseRestricted" will be set to 'true' or 'false.
Authentication
The Digiguide API requires all calls to the API to be accompanied by your unique Application ID. This is to ensure that other applications do not abuse the system which can cause Digiguide to close access to the API for your app; but also so the end-user has some control and can stop an application having access to their account without their knowledge or consent.
Whilst in Beta, access to the API will be limited, please request an Application ID in our online forums and we will do our best to accomodate you.
Certain API calls/endpoints also require a valid authenticated 'Digiguide.tv ID'; these values may change but if the API endpoint requires account authentication then an error response may be returned which would need handling by the application. Some endpoints may only return a subset of information depending on if it is accompanied by a valid account or if the account is 'subscribed' (i.e. the customer account has a valid and current product subscription).
The basic method for providing customer account authentication with a requests is:
Include a custom "Authorization" header with the header value consisting of:
- customer's email and SHA256 hashed password separated by a colon
- this string is then Base64 encoded
- finally the encoded value is prefixed by the word "Basic " (including trailing space). Example:
"Basic " + Base64.encode( email + ":" + passwordSHA256Hash )
As an example, a simple jQuery call to perform an authenticated request would be something like (this example will not work unless you replace the appid with your own):
$.ajax( {
url: "https://api.digiguide.tv/1.2/tv/person/?name=Brad+Pitt",
type: "GET",
data: "appid=<add-your-appid-here>,
cache: false,
dataType: "json",
beforeSend: function( xhrObj ){ xhrObj.setRequestHeader( "Authorization", "Basic " + Base64.encode( email + ":" + passwordSHA256Hash ) ); },
success: function( data ) {
console.log( data );
},
error: function( XMLHttpRequest, textStatus, errorThrown ) {
console.log( "Got error: " + XMLHttpRequest.responseText );
console.log( "Got error (status): " + XMLHttpRequest.status );
console.log( "Got error (statusText): " + XMLHttpRequest.statusText );
console.log( "Got error (textStatus): " + textStatus );
console.log( "Got error (errorThrown): " + errorThrown );
}
} );
However, if you wish to use JSONP then JQuery does not allow the setting of custom headers so you can pass in the authentication as an additional parameter (again, this example will not work unless you replace the appid with your own):
$.ajax( {
url: "https://api.digiguide.tv/1.2/tv/person/?name=Brad+Pitt",
type: "GET",
data: "appid=<add-your-appid-here>&auth=Basic+" + escape( Base64.encode( email + ":" + passwordSHA256Hash ) ),
cache: false,
dataType: "jsonp",
success: function( data ) {
console.log( data );
},
error: function( XMLHttpRequest, textStatus, errorThrown ) {
console.log( "Got error: " + XMLHttpRequest.responseText );
console.log( "Got error (status): " + XMLHttpRequest.status );
console.log( "Got error (statusText): " + XMLHttpRequest.statusText );
console.log( "Got error (textStatus): " + textStatus );
console.log( "Got error (errorThrown): " + errorThrown );
}
} );
Security
Due to the nature of the user authentication method, it is suggested that all calls to the API which contain user authentication are sent as HTTPS unless there is a specific reason not to do so; i.e. no user authentication is required or all calls are sent from a locked down server and are hidden from client networks.
Handling Errors
All API calls will contain a "success" property that indicates whether the call was successful or not.
If it was successful then the other properties of the response will be determined by the specific API call requested as detailed in the documentation for that call.
If it was not successful then the response will be false and three additional properties will be returned detailing the error codes and reason for failure as detailed below:
| errorID | errorStatusCode | errorMsg |
|---|---|---|
| 1 | 400 | Application ID is invalid or unknown |
| 2 | 400 | Application is no longer permitted to use the API |
| 3 | 403 | User has blocked access to this application |
| 4 | 403 | Values did not match key, params were constructed badly or tampered with in-transit |
| 5 | 405 | Wrong URI scheme, perhaps this should have been an HTTPS request |
| 6 | 405 | Wrong method for request, perhaps you sent a GET instead of a POST |
| 50 | 400 | Some required parameters were missing |
| 51 | 400 | An account could not be found with that e-mail address and password |
| 52 | 400 | An account already exists with that e-mail address, please login instead |
| 53 | 400 | That screen name already exists, please try another |
| 9999 | 503 | Server unavailable, perhaps for maintenance or it is overloaded. Please try again later |
Example
{
"success": false,
"errorID": 51,
"errorStatusCode": 400,
"errorMsg": "An account could not be found with that e-mail address and password"
}