Requesting a News/Event list
support, ws.webtv, api, news, list
GET vars specific to this request:
Var | Value | Description |
go | news | 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=news&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 |
fields | (string) "field1,field2,..." | Specify the fields to be included in the result. "*" = all fields (default). "field1, field2, field2" = subset of the fields [Recommended] - separated by comma. Available fields: id, id_user, status, status_moderation, type, title, title_url, description, description_seo, tags, img_legend, img_poster, img_social, img_thumbnail, img_icon, date, date_end, views_page, socialize, allow_comments, notification, notification_link_type, notification_link, map, map_center_lat, map_center_lng, map_zoom, map_type, map_marker_lat, map_marker_lng, id_import, date_lastmod |
Paging options: | ||
resultsPerPageFilter | (int) n | Number of results per page |
current_page | (int) n | The number of the current page |
paging | (int) 0/1 | To enable/disable paging |
limit | (int) n | Results limit (only if resultsPerPageFilter is not specified and paging=0) |
Frequently used filters: | ||
idUserFilter | (int) author ID | List News/Events from the specified User |
statusFilter | (mixed) status | List News/Events that match the specified status. Available options: 0 (inactive), 1 (active), "any" NOTE: Unsigned requests will only return active News/Events. |
sortByFilter | (string) "option" | Sort the list. Available options: "date" (lates first - default), "title","views_page","id","random","randomSeed","dateRevUp" (reverse date for upcoming events), "date2" (reverse date) |
typeFilter | (mixed) type | List News/Events of the specified type. Available options: "any" (cualquiera), 0 (News), 1 (Event) |
tagsFilter | (string) "tag1,tag2,..." | List News/Events according to tags (separated by comma). |
idFilter | (string) "ID1,ID2,..." | List News/Events whose ID matches the specified ones (separated by comma). |
Date filters: | ||
dateStartFilter | (int) timestamp | List News/Events whose date is equal or later respect the day of the timestamp (from 00:00:00) |
dateStartMaxFilter | (int) timestamp | List News/Events whose date is equal or earlier respect the day of the timestamp (from 00:00:00) |
dateEndFilter | (int) timestamp | [For Events] List items whose "end date" is equal or earlier respect the day of the timestamp (up to 23:59:59) |
Category filters: | ||
categoriesFilter | (int) n | List News/Events associated to the Category. Specify a Category ID or -1 for "orphaned" News/Events (News/Events not associated to a Category) |
categoriesFilterStrict | (int) 0/1 | (Depends on the previous option) List News/Events directly associated with the specified Category (ignoring any Category inheritance). |
Directly related Clip filter - Since WS.WebTV v59 | ||
idClipRelationshipFilter | (int) Clip ID | (This filter is used for listing the News/Events directly related with a particular Clip) ID of the Clip. |
Search filters: | ||
search | (string) "term" | Term to search |
searchMode | (string) "mode" | The way the system searches for the supplied term. Available options: Standard modes (faster): Look for exact matches. "std1" = search on title + tags. "std2" = search on title + tags + short description. "std3" (default) = search on title + tags + full description. Words modes (slower, find more matches): Search by breaking the term into words and looking for all posible combinations of them. "words1" = search on title + tags. "words2" = search on title + tags + short description. "words3" = search on title + tags + full description. |
Forbidden content exclusion filters: (Since WS.WebTV 3.0.2pf1) |
||
excludeForbiddenContent | (int) 0/1 | Whether to exclude "forbidden" Galleries from the list. "Forbidden" means that the user is not allowed to access. Note that you must also past the "cvr" variable (see a bit below). |
cvr | (string) "ID1,ID2,..." | CVR = Content View Restriction. This is a list of comma separated Gallery IDs that the current User is not allowed to access. All Galleries matching these IDs will be excluded from the list when excludeForbiddenContent = 1. If cvr is blank then no Galleries will be excluded from the list regardless of the value of excludeForbiddenContent. |
Other filters (Since WS.WebTV 55) |
||
searchableFilter | (int) 0/1 | List News/Events whose "searchable" property matches the value. |
indexableFilter | (int) 0/1 | List News/Events whose "indexable" property matches the value. |
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 limit or resultsPerPageFilter values.
• list: The item list.
Example:
{ "list_total_found": "38", "list_total": 5, "list": [{ "datesorthint": "1427355660", "id": "58", "img_poster": "http:\/\/...\/public\/common\/images\/_default_event_poster.gif", "title": "Company celebration", "type": "1", "type_name": "event", "user_alias": "WebTV" }, { "datesorthint": "1421622000", "id": "33", "img_poster": "http:\/\/...\/uploads\/images\/event_33_1405010853_poster.jpg", "title": "Live webcast", "type": "1", "type_name": "event", "user_alias": "WebTV" }, { "datesorthint": "1420109160", "id": "57", "img_poster": "http:\/\/...\/public\/common\/images\/_default_event_poster.gif", "title": "Anual meeting", "type": "1", "type_name": "event", "user_alias": "WebTV" }, { "datesorthint": "1420022700", "id": "56", "img_poster": "http:\/\/...\/public\/common\/images\/_default_event_poster.gif", "title": "Eastern party", "type": "1", "type_name": "event", "user_alias": "WebTV" }, { "datesorthint": "1419158700", "id": "55", "img_poster": "http:\/\/...\/public\/common\/images\/_default_event_poster.gif", "title": "Halloween party", "type": "1", "type_name": "event", "user_alias": "WebTV" }] }
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 News/Events were found
Preparing GET and POST data.
// The GET vars $GET_VARS = array( "go" => "news", "do" => "list" ); // The POST vars $POST_VARS = array( "fields" => "id,title,img_poster", // Include fields id, title and img_poster "paging" => 1, // Allow paging "resultsPerPageFilter" => 5, // Return 5 results per page "current_page" => 1, // Return the page No. 1 "sortByFilter" => "date", // Sort by date "typeFilter" => 1, // List Events only "statusFilter" => "any" // Include items with any status );
Generating the salt, timestamp, signature and sending the request
*** The following code block is common to all signed requests ***
// Collect the API Base URL and Credential info $API_URL = "https://www.mywebtvdomain.tv/api.php"; $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)); }