Requesting a Category list
support, ws.webtv, api, categories, list
GET vars specific to this request:
Var | Value | Description |
go | categories | The API section |
do | list | The API action |
Resulting Request URL:
The resulting request URL would be similar to this (don't forget to append the required info: key, timestamp, salt and signature):
https://....../api.php?go=categories&do=list&{required information}
The following list filters are available by using POST vars.
TIP: You can use several filters at the same time.
Var | Value | Description |
includeData | (int) 0|1 | Whether to include the data fields or not. If 0 only a list with containing the Category ID and status will be returned. |
Paging options: |
||
resultsPerPageFilter | (int) n | Number of results per page |
current_page | (int) n | The number of the current page |
Frequently used filters: |
||
statusFilter | (mixed) status | List Categories that match the specified status. Available options: "any" (default), 0 (inactive), 1 (active) NOTE: Unsigned requests will only return active Categories. |
sortByFilter | (string) "option" | Sort the list. Available options: "title" (default), "id", "order_title", "order_id" |
parentFilter | (mixed) parent | List Categories from a parent ID Specify "any" to list all Categories. Specify a Category ID > 0 to list the requested Category with all its children |
maxLevel | (int) (1-4) | The maximun nesting level to list (up to 4). |
Search filters: |
||
search | (string) "term" | Term to search. Search is performed only on Category titles. |
If the request was successful, you'll receive a response containing:
• list_total_found: The total amount of items found in the WebTV which matched the criteria (for paging purpose).
• list_total: The number of items in the returned list. This will normally match the resultsPerPageFilter value.
• list: The item list.
Example:
{ "list_total_found" : 3, "list_total" : 3, "list" : [{ "breadcrumb" : [5], "children" : [], "description" : "Live events" , "description_seo" : "Live events" , "id" : 5, "id_parent" : null , "img_icon" : "http:\/\/......\/uploads\/images\/category_5_1364385573_icon.jpg" , "img_poster" : "http:\/\/......\/uploads\/images\/category_5_1364385573_poster.jpg" , "img_social" : "http:\/\/......\/uploads\/images\/category_5_1364385573_social.jpg" , "img_thumbnail" : "http:\/\/......\/uploads\/images\/category_5_1364385573_thumb.jpg" , "level" : 1, "status" : "1" , "tags" : "" , "title" : "Live!" , "title_url" : "live!" , "title_url_full" : "live!" , "url" : "http:\/\/......\/index.php\/c\/5\/live!\/" , "views_page" : "102" }, { "breadcrumb" : [1], "children" : [6], "description" : "Latest Movies" , "description_seo" : "Latest Movies" , "id" : 1, "id_parent" : null , "img_icon" : "http:\/\/......\/uploads\/images\/category_1_1364385555_icon.jpg" , "img_poster" : "http:\/\/......\/uploads\/images\/category_1_1364385555_poster.jpg" , "img_social" : "http:\/\/......\/uploads\/images\/category_1_1364385555_social.jpg" , "img_thumbnail" : "http:\/\/......\/uploads\/images\/category_1_1364385555_thumb.jpg" , "level" : 1, "status" : "1" , "tags" : "" , "title" : "Movies" , "title_url" : "movies" , "title_url_full" : "movies" , "url" : "http:\/\/......\/index.php\/c\/1\/movies\/" , "views_page" : "2557" }, { "breadcrumb" : [ "1" , 6], "children" : [], "description" : "Action Movies" , "description_seo" : "Action Movies" , "id" : 6, "id_parent" : "1" , "img_icon" : "http:\/\/......\/uploads\/images\/category_6_1364385648_icon.jpg" , "img_poster" : "http:\/\/......\/uploads\/images\/category_6_1364385648_poster.jpg" , "img_social" : "http:\/\/......\/uploads\/images\/category_6_1364385648_social.jpg" , "img_thumbnail" : "http:\/\/......\/uploads\/images\/category_6_1364385648_thumb.jpg" , "level" : 2, "status" : "1" , "tags" : "" , "title" : "Action" , "title_url" : "action" , "title_url_full" : "movies-action" , "url" : "http:\/\/......\/index.php\/c\/6\/movies-action\/" , "views_page" : "63" }] } |
If the request failed (for example, if the Credential does not have permission to GET), you'll receive a response like the following:
{ "error" : "REQUEST_ERROR" , "error_long" : "Permission error: GET" } |
Possible Error Messages
Besides the general errors, this request can return the following errors:
• REQUEST_ERROR | No Categories were found
Preparing GET and POST data.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | // The GET vars $GET_VARS = array ( "go" => "categories" , "do" => "list" ); // The POST vars $POST_VARS = array ( "includeData" => 1, // Include all data fields "maxLevel" => 4, // List all levels "resultsPerPageFilter" => 3, // Return 3 results per page "current_page" => 1, // Return the page No. 1 "sortByFilter" => "title" , // Sort by title "statusFilter" => 1 // Include only active Categories ); |
Generating the salt, timestamp, signature and sending the request
*** The following code block is common to all signed requests ***
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 | // Collect the API Base URL and Credential info $API_KEY_ID = "1b323a1cb879fd4e66530fbad07a32ee" ; $API_SHARED_SECRET = "MWIzMjNhMWNiODc5ZmQ0ZTY2NTMwZmJhZDA3YTMyZWViOTQ3MDJiOGM2ZTU2NjE3" ; // keep this safe!!! // Generating salt and timestamp $salt = md5(mt_rand()); $timestamp = time(); $signature = base64_encode (hash_hmac( 'sha256' , $salt . $timestamp , $API_SHARED_SECRET , true)); // Generating the validation signature // - Default method: using base64_encode(hash_hmac(...)) $signature = base64_encode (hash_hmac( 'sha256' , $salt . $timestamp , $API_SHARED_SECRET , true)); // comment this line if using the next method // - Simplified method - available since v60: using md5(). // This method requires the variable $API_SIGNATURE_GENERATION_MODE = 1; in the config/Config.inc.php file. // $signature = md5($salt."-".$timestamp."-".$API_SHARED_SECRET); // you must "uncomment" this line when using the simplified method // Append the timestamp, salt, key and signature to the GET vars $GET_VARS [ "timestamp" ] = $timestamp ; // UTC timestamp $GET_VARS [ "salt" ] = $salt ; $GET_VARS [ "key" ] = $API_KEY_ID ; // The API Key ID: This is public and is used by the API to identify the application; $GET_VARS [ "signature" ] = $signature ; // Create the request URL. Please note that if you do not use PHP buit in function // to create the HTTP query then don't forget to URL encode the values $REQUEST_URL = $API_URL . "?" .http_build_query( $GET_VARS ); // The previous will build an URL like .../api.php?go=api_subject&do=api_action&etc... // Create a new cURL resource and set the appropriate options $ch = curl_init(); curl_setopt( $ch , CURLOPT_URL, $REQUEST_URL ); curl_setopt( $ch , CURLOPT_POST, true); curl_setopt( $ch , CURLOPT_RETURNTRANSFER, true); curl_setopt( $ch , CURLOPT_HEADER, false); curl_setopt( $ch , CURLOPT_POSTFIELDS, $POST_VARS ); // If your PHP host does not have a valid SSL certificate, you will need to turn off SSL // Certificate Verification. This is dangerous (!), and should only be done temporarily // until a valid certificate has been installed curl_setopt( $ch , CURLOPT_SSL_VERIFYHOST, false); // Turns off verification of the SSL certificate. curl_setopt( $ch , CURLOPT_SSL_VERIFYPEER, false); // Turns off verification of the SSL certificate. // Sending the request to the API $response = curl_exec( $ch ); // Processing the response if (! $response ) { echo 'API call failed' ; } else { print_r(json_decode( $response ,true)); } |