<p>Returns a list of media based on provided parameters.</p>
<p>The actual return value is a struct with the totalCount and data properties. <code>totalCount</code> contains the number of items that would have been returned if there was no offset or limit specified.</p>
<p><code>pageSize</code> has a maximum value of 500 - ie. no more than 500 media items will ever be returned from a single call to this function.</p>
<p>If no API key is supplied, or there are insufficient permissions, this method will switch to anonymous mode. In that situation, if global moderation is set for this project it will never return unmoderated files.</p>
array media.getMediaByMetaData ( int vhost, mixed metadata = array(), array filters = array(), int start = 0, int limit = 20, mixed type = 'AND', string sort = 'upload DESC', array fields = array(), mixed includeChildMedia = 0, mixed childFilters = array(), mixed childFields = array(), mixed childSort = 'UPLOAD DESC', mixed voter_uid = 0, mixed parentFields = array() )
Name | Type | Required | Default value | Description |
---|---|---|---|---|
vhost | int | Required | none | The vhost id. |
metadata | mixed | Optional | array() | |
filters | array | Optional | array() | You can specify the filter parameters here as an array. Recognized filters are listed below. |
start | int | Optional | 0 | If you specify an offset, you will be the media items starting at this position. |
limit | int | Optional | 20 | The total number of files you want to receive. |
type | mixed | Optional | 'AND' | |
sort | string | Optional | 'upload DESC' | Specify here which field you want to sort on. |
fields | array | Optional | array() | The list of fields you want to have returned. If fields are not supplied a set number of default fields will be returned The list of available fields are avaiable below. |
includeChildMedia | mixed | Optional | 0 | |
childFilters | mixed | Optional | array() | |
childFields | mixed | Optional | array() | |
childSort | mixed | Optional | 'UPLOAD DESC' | |
voter_uid | mixed | Optional | 0 | |
parentFields | mixed | Optional | array() |
Filters allow you to restrict the data that is returned. Below is a list of valid filters.
Name | Type | Description | Default Values |
---|---|---|---|
filetype | INT | The filetype of the media that you wish to have returned to your. Values can be any combination of the following: 1 (image), 2 (video), 3 (audio), 4 (text). | 1,2,3,4 |
moderationStatus | INT / STRING | The moderation status of the media that you want returned. This value can be either an integer or a media status name. For more information on moderationStatus values visit our glossary. Possible values are 0 (unmoderated), 1 (approved), 2 (denied), 3 (notdenied) or -1 (all). | notdenied |
query | STRING | A string that we will query available media for a match. We search the media filename, title, description and tags for a match with the string. Possible values would be 'teststring', or 'cats AND dogs', 'cats OR dogs', 'dogs NOT cats'. | empty |
channel | INT / STRING | Specify a channel ID or a channel Short Name to have media returned from the specified channel. | empty |
includeChildren | INT | Specifies weather to return media from the child channels of the specified parent channel. Possible values are 0 or 1 where 1 will return media from the specified channel and its children otherwise only media from the specified channel will be returned. This filter must be used in conjunction with the channel filter). | 0 |
collection | INT | The collection ID that the media item will be returned from. This field must be the ID of collection in your vhost. | empty |
uid | INT | Only return media uploaded by the specified user ID. | empty |
title | STRING | Searches for all media files with a title that contains the specified string. | empty |
metadata | array | Finds media that the metadata key matches the provided value, multiple metadata fields are matched using AND logic. (Eg. metadata[eyecolor]=blue&metadata[hair]=brown) Not null is supported via !null. (Eg. metadata[type]=!null | empty |
favoriteuid | INT | Returns all of the favorited media by the user with the user ID that was specified. This Field is only compatible with the 'query','moderationStatus', 'channel', 'groupid' and 'includeChildGroups' filters. All other fields will be ignored. Pass -1 for the current user. | empty |
parentid | INT | Return media who has a parent ID matching this integer. | empty |
groupid | INT | Return media that is a member of the specified group ID. | empty |
eventid | INT | Return media that is a member of the specified event ID. | empty |
includeChildGroups | INT | Specifies whether or not to return media from the childgroups (groups/events) of the parent group, which is specified by the filter 'groupid' or 'eventid'. This filter is only valid when the "groupid" or "eventid" filter is set. The possible values are "true" / 1 or "false" / 0 | false / 0 |
context | STRING | Return media which match the specified context for media type. Possible values are generic, all, comment, note, commentnote, genericcomment, parent, child. More information on context can be found in our glossary | 'generic' |
status | INT | The current status of uploaded media within MediaFactory. There is a status for uploading, transcoding, success, denied, error etc... The possible values are 0,1,2,3,4,100,101,102,103,104,105. To find out more information on the possible values visit the glossary | 3 |
hidden | STRING | Only return media that has the same value of the passed hidden variable. Possible values are public, private and all. An expoination of the differences between the different hidden values can be found in our glossary | 'all' |
geoBoundaries | [float LAT, float LNG, float LAT, float LNG] | Return media that is located inside the bounding box made up of the latitude and longitude cooridinites. Specify as an array: [north-west lat, north-west long, south-east lat, south-east long] ([62.86,-52.44,35.08,-131.55]) to receive media within the cooridinites. | empty |
geoCenter | [float LAT, float LNG] | Return media that is located inside the specified distance from this center point ([62.86,-52.44]), sorted by distance. | empty |
geoDistance | INT | Distance in meters from geoCenter | empty |
notuid | INT | Return media only from users other than the specified user ID | empty |
parentuid | INT | Return only media whose parent's owner matches this UID will be returned. This filter is useful for showing all comments on any of a user's media when used in combination with the context filter). | empty |
timeLimit | timestamp | Return media that has been uploaded after specified number of seconds. For example timeLimit=3600 will return media uploaded in the past hour (3600 seconds is one hour). Maximum time limit is 30 years (946080000 seconds). | empty |
startTime | STRING | This attribute filters by the upload date. No media uploaded before the startTime will be returned. Usually you should use the 'YYYY-MM-DD HH:MM:SS' format, but using the following values will also work: 'yesterday', 'midnight', 'today', 'now', 'noon', or 'tomorrow'. | empty |
endTime | STRING | This attribute filters by the upload date. No media uploaded past the endTime will be returned. Usually you should use 'YYYY-MM-DD HH:MM:SS' format, but using the following values will also work: 'yesterday', 'midnight', 'today', 'now', 'noon', or 'tomorrow'. | empty |
externalid | STRING | Filters media based on the external ID of the media items. The possible values can be one of the following:
| empty |
tag | STRING | Return media that contains the given tag | empty |
geo | STRING | Set this to 'notnull' to return media that have valid geo-location values, meaning ones with geo_latitude <> null and geo_longitude <> null | empty |
Below you will find a list and description of all of the available fields to have returned with our media.getMediaByMetaData service. If you do not specify any fields the following default list will be returned to you avatar, channel, commentcount, filetype, hits, id, message, rating, status, tags, title, uid, upload, user_name, vhost, votecount, publicUrl, thumbUrl and location. If you specify atleast one filter the reponse will include id, vhost, publicUrl, thumbUrl, location and the fields sent with the request.
Name | Description |
---|---|
avatar | The media ID for the avatar of the user who uploaded the media. |
channel | Channel ID the media belongs to. |
commentcount | The number of comments made on the media item. |
extension | The original file extension of the uploaded media |
filetype | The file type of the piece of media (0,1,2,3,4). Further information is available in the glossary. |
hits | The number of hits the piece of media has received. |
message | The media message. |
metadata | By specifying this to be returned as one of the fields, you will get back metadata and metadataArray. The metadata is the media metadata formatted as as a string. The metadata can be set by the user (in the media detail page) or by the developer (via the API). This value is returned as a string formatted as: {metadata: {user: {key:value,key,value}}}. For more information on media metadata, please refer to our glossary. The metadataArray allows you to read the media metadata as an array. The metadata can be set by the user (in the media detail page) or by the developer (via the API). This data is accessible with result.data[loopindex].metadataArray.user.key: for example result.data[loopindex].metadataArray.user.key: i.e. result.data[loopindex].metadataArray.user.pin and result.data[loopindex].metadataArray.user.synopisis For more information on accessing media metadata, please refer to our glossary. |
moderationstatus | The moderation status represented by integers; 0 for unmoderated, 1 for approved, 2 for denied. |
rating | Media rating of the media item. |
rotation | The rotation of the media item signified by an int. 0 for no rotation, 1 for 90 degrees, 2 for 180 degrees, 3 for 270 degrees clockwise. |
status | The media status. |
hidden | Have the media hidden value returned in the response. |
tags | A string of the media's tags returned to you seperated by a space. Ie: "toronto weather torontoweather". |
title | The media item's title. |
uid | The user ID of the user who uploaded the media. |
upload | The date the media item was uploaded (YYYY-MM-DD). |
lastupdatetime | The date the media item was last updated, moderated, rotated. |
date | The date the media was created represented in a 24 hr clock format. (YYYY-MM-DD HH:mm:SS). |
user_name | The username of the user who uplaoded the media item. |
votecount | The vote count on the media item. |
user_firstname | The firstname of the user who uploaded the media item. |
user_lastname | The lastname of the user who uploaded the media item. |
parentid | The ID of the parent media item of current media item. This is used to get the parent media ID if you are looping through a list of media comments. |
parent_title | This is available only if the media has a parent media (meaning its parentid is greater than 0). This is available for all filetypes. |
parent_info | This is available only if the media has a parent media (meaning its parentid is greater than 0). This is available for all filetypes. |
language | 2-letter ISO laguage code. |
author | The name of the anonymous user (guest or public user) who uploaded the media item anonymously. All anonymous users have an ID of 1. This will be the name the user entered in the form during while commenting. |
streamserver | The RTMP server for streaming if available. |
streamname | The name of the stream to be requested from the streaming server if available. |
context | The context of the media items. |
width | The width of the media item. |
height | The height of the media item. |
length | The duration of the file in seconds, specified as a float with 2 decimals. This will only have a value if the media item is a video or audio file ( filetypes 2 and 3 respectivly ). |
geo_latitude | The latitude of the piece of media if available. |
geo_longitude | The longitude of the piece of media if avaialble. |
offensive | The number of times the media was reported as offensive. |
shares | The number of times the media was shared. |
approvedcomments | The number of comments posted for this media that were approved. |
notdeniedcomments | The number of comments posted for this media that were not denied (were approved or not yet moderated). |
externalid | The external id associated with the file. Please refer to `externalid` in the Response for the structure of the returned data. |
externalids | The array of external ids associated with the file. Please refer to `externalids` in the Response for the structure of the returned data. |
The responses returned by the getMediaByMetaData service call.
Name | Description | Possible Values |
---|---|---|
avatar | The media ID for the avatar of the user who uploaded the media. | INT |
channel | Channel ID the media belongs to. | INT |
commentcount | The number of comments made on the media item. | INT |
extension | The original file extension of the uploaded media. An example would be png. | STRING |
filetype | The file type of the piece of media (0,1,2,3,4). Further information is availe in the glossary. | 0,1,2,3,4 |
hits | The number of hits the piece of media has received. | INT |
message | The media message. | STRING |
metadata | This is the media metadata formatted as as a string. The metadata can be set by the user (in the media detail page) or by the developer (via the API). This value is returned as a string formatted as: {metadata: {user: {key:value,key,value}}}. For more information on media metadata, please refer to our glossary. | STRING |
metadataArray | The metadataArray allows you to read the media metadata as an array. The metadata can be set by the user (in the media detail page) or by the developer (via the API). This data is accessible with result.data[loopindex].metadataArray.user.key: for example result.data[loopindex].metadataArray.user.key: i.e. result.data[loopindex].metadataArray.user.pin and result.data[loopindex].metadataArray.user.synopisis For more information on accessing media metadata, please refer to our glossary. | ARRAY Examples: result.data[index].metadataArray.user.pin result.data[index].metadataArray.user.synopsis |
moderationstatus | The moderation status represented by integers; 0 for unmoderated, 1 for approved, 2 for denied. | 0,1,2 |
rating | Media rating of the media item. | INT |
rotation | The rotation of the media item signified by an int. 0 for no rotation, 1 for 90 degrees, 2 for 180 degrees, 3 for 270 degrees clockwise. | 0,1,2,3 |
status | Media Status | INT / STRING 0, 1, 2, 3, -1, 'unmoderated', 'notdenied', 'accepted'/'approved', 'denied', 'all' |
hidden | Media hidden value | STRING hidden, public, all |
tags | A string of the media's tags returned to you seperated by a space. Ie: "toronto weather torontoweather". | STRING |
title | The media item's title | STRING |
uid | The user ID of the user who uploaded the media. | INT |
upload | The date the media item was uploaded (YYYY-MM-DD). | YYYY-MM-DD |
date | The date the media was created represented in a 24 hr clock format. | (YYYY-MM-DD HH:mm:SS) |
user_name | The username of the user who uplaoded the media item. | INT |
votecount | The vote count on the media item. | INT |
user_firstname | The firstname of the user who uploaded the media item. | STRING |
user_lastname | The lastname of the user who uploaded the media item. | STRING |
parentid | The ID of the parent media item of current media item. This is used to get the parent media ID if you are looping through a list of media comments. | INT |
parent_title | The title of the parent media. | STRING |
parent_info | An array of the parent media information. | STRING |
language | 2-letter ISO code. | STRING |
author | The name of the anonymous user (guest or public user) who uploaded the media item anonymously. All anonymous users have an ID of 1. This will be the name the user entered in the form during while commenting. | STRING |
streamserver | The RTMP server for streaming if available. | STRING |
streamname | The name of the stream to be requested from the streaming server if available. | STRING |
context | The context of the media items. | generic, all, comment, note, commentnote, genericcomment, parent, child |
width | The width of the media item. | INT |
height | The height of the media item. | INT |
length | The duration of the file in seconds, specified as a float with 2 decimals. This will only have a value if the media item is a video or audio file ( filetypes 2 and 3 respectivly ). | NUMBER 10.20 |
geo_latitude | The latitude of the piece of media if available. | NUMBER |
geo_longitude | The longitude of the piece of media if avaialble. | NUMBER |
collection_details | The name, search terms and query of the collection. Note: The filters[collection] argument has to be set and refer to a valid collection id in order for the collection_details field to contain data. | array ( 'name'=>'Collection 1', 'description' => 'Approved media', 'query'=> '' ) |
collectionDetails | The name, search terms and query of the collection. Contains the same data as 'collection_details' does. Note: The filters[collection] argument has to be set and refer to a valid collection id in order for the collectionDetails field to contain data. | array ( 'name'=>'Collection 1', 'description' => 'Approved media', 'query'=> '' ) |
collectionInfo | The full set of information about a collection returned when filters[collection] is set to a valid collection id. This contains more information than collection_details and collectionDetails arrays. The collectionInfo contains the following parameters: name, vhost, type, description, created, baseurl, channel, addtotop, autoactive, thumbnail, searchdata (which includes: collection, sort, sortdir timelimit, query, filetype, limit, channel, includeChildChannels, moderation, groupid, includeChildGroups, tag) terms and query of the collection. Note: The filters[collection] argument has to be set and refer to a valid collection id in order for the collectionInfo field to contain data. | array ( 'id'=>193, 'vhost'=>21, 'thumbnail'=>54321, 'type'=>2, 'name'=>'Collection 1', 'description' => 'Approved media', 'created'=>'2008-05-05 10:06:18', 'channel'=>145, 'autoactive'=>1, 'searchdata'=>array('collection'=>193, 'sort'=>'upload', 'sortdir'=>'ASC', 'timelimit'=>0, 'query'=> '', 'filetype'=>0, 'limit'=>25, 'channel'=>145, 'includeChildChannels'=>0, 'moderation'=>1, 'groupid'=>9500, 'includeChildGroups'=>1 ) ) |
offensive | The number of times the media was reported as offensive. | INT |
shares | The number of times the media was shared. | INT |
approvedcomments | The number of comments posted for this media that were approved. | INT |
notdeniedcomments | The number of comments posted for this media that were not denied (were approved or not yet moderated). | INT |
externalid | This is the third party ID of the file; it is available only if the file is hosted by one of our partners, such as Twitter, Instagram, Youtube, Brightcove, Widen, Apple and Ooyala. NOTE 1 The external id does not always state the external id provider. NOTE 2 It is equal to the primary media externalids reference, with the provider being stated in the reference, while in the externalids the provider is stored in the array as `external_id_provider`. Example: instagram_image:678386240811661326_1187731501 | STRING Format: <externalid provider>:<externalid> Example: instagram_image:6833326_11458501 |
externalids | This is an array of the third party IDs for the file; it is available only if the file is hosted by one of our partners, such as Twitter, Instagram, Youtube, Brightcove, Widen, Apple, and Ooyala. The external id provider values are stored as an integer, and are below:
NOTE 1 Each recordset in the array is an array itself that contains the following:
NOTE 2Only one record can be the primary external id for each media. NOTE 3The record that is noted as the primary external id is stored in the externalid with the reference to the external id provider stated before the external id. | Example array( Array (   'external_id_provider'=>3, 'external_id'=>'6136_1186', 'created'=>'2014-03-19 17:43:11', 'vhost' => 218, 'primary_external_id' => 1 ), Array (   'external_id_provider'=>2, 'external_id'=>'6136_1186', 'created' => '2014-03-23 07:52:54', 'vhost' => 218, 'primary_external_id' => 0 ) ) |