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: - 0 (do not filter based on external ID)
- exists (include only media that has an external ID set)
- mediaType={image|video|audio|text|unknown}
Specifies to include only media of the specified type(s) that have an external ID set - media of other file types will be included regardless of their external IDs.
For example: "mediaType=image,video" will return image and video media items with external IDs and text, audio and unknown media types without external IDs. - and other (include only media that has the exact external ID specified)
| 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: - 0 - other: any provider other than the 7 mentioned below. You can store any reference using this provider.
i.e. 'http://www.arbitrarysite.com/image=123' - 1 - Brightcove
- 2 - Youtube
- 3 - Instagram
- 4 - Twitter
- 5 - Widen
- 6 - Apple
- 7 - Ooyala
NOTE 1
Each recordset in the array is an array itself that contains the following: - external_id (string)
- external_id_provider (integer)
- created (the date the externalid record created/updated)
- vhost
- primary_external_id (Integer. States whether this is the media's primary external id: possible values: 1 or 0.)
.
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
)
) |
| Field | Description | Possible Values |
|---|
| filetypea | The filetype of tyhe media that you want returnedb | 1,2,3,4c |
| moderationStatusa | The moderation status of the media that you want returned. This value can be either an integer ID or status name.b | 0, 1, 2, 3, -1, 'unmoderated', 'notdenied', 'accepted'/'approved', 'denied', 'all'c |
| querya | (only media matching this string in one of the following fields will be returned: title, tags, filename, message, owner first name, owner last name)b | N/A |
| channela | Return media from the specified channel IDb | INTc |
| includeChildrena | Specifies weather to return media from the child channels of the specified parent channel ID. default 0: when 1 media from the specified channel and its children will be returned, otherwise only media from the specified channel is returned; must be used with channel filter)b | 0, 1c |
| collectiona | The collection ID that the media item will be returned fromb | INTc |
| collectionDetailsa | (1 or 0) Set to 1 to receive the Collection Details (ie data in: table: storageapi_collection_searchdata, field: query ). Set to 0 to not receive the details.b | N/A |
| uida | Return media only from the specified user IDb | (a user id, when you are in anonymous mode this can also be -1, which means the currently logged in user. This can optionally be an array for multiple uid's)c |
| titlea | (searches for media files which contain this string)b | N/A |
| favoriteuida | (user ID whose favorite media should be returned, this is only compatible with the 'query' and 'moderationStatus' filters, all others will be ignored) Pass -1 for the current userb | N/A |
| parentida | (only media having the specified media item as a parent)b | N/A |
| groupida | The group ID we want our media returned from (only media from the specified user group)b | N/A |
| eventida | (only media from the specified user event)b | N/A |
| includeChildGroupsa | (only return media that is in the specified group/event or any of its children groups/events, only valid with a "groupid" or "eventid" filter set, "true" or "false", default is "false")b | N/A |
| contexta | Return media which match the specified context valueb | 'generic', 'all', 'comment', 'note', 'commentnote', 'genericcomment', 'parent','child'c |
| + 'generic': default, only normal media (no comments or notes)a | N/A |
| + 'all': all mediaa | N/A |
| + 'comment': only commentsa | N/A |
| + 'note': only moderators' notesa | N/A |
| + 'commentnote': only comments and moderators' notesa | N/A |
| + 'genericcomment': everything but notesa | N/A |
| + 'parent': only parent media (deprecated)a | N/A |
| + 'child': only child media (deprecated)a | N/A |
| statusa | The current state of the media within MediaFactoryb | 0,1,2,3,4,100,101,102,103,104,105c |
| + 0 uploadinga | N/A |
| + 1 queued for conversiona | N/A |
| + 2 convertinga | N/A |
| + 3 converteda | N/A |
| + 4 failed conversiona | N/A |
| + 100 trashed (any trashed status)a | N/A |
| + 101 trashed while uploadinga | N/A |
| + 102 trashed while queued for conversiona | N/A |
| + 103 trashed while convertinga | N/A |
| + 104 trashed after successful conversiona | N/A |
| + 105 trashed after failed conversiona | N/A |
| hiddena | Only return media that matches the value of hidden in MediaFactory. |b | N/A |
| + 'public': default, only public mediaa | N/A |
| + 'private': only private media (you may only retrieve your own private media unless you have the media.setHidden permission)a | N/A |
| + 'all': all media (you may only retrieve all your own media unless you have the media.setHidden permission)a | N/A |
| geoBoundariesa | only media in the specified region will be included, specify as an array: (north-west lat, north-west long, south-east lat, south-east long)b | N/A |
| geoDistancea | Only media within this distance in meters from geoCenter will be returned, this geoCenter must be used with geoDistance. eg. 1000 = 1kmb | N/A |
| geoCentera | Center point to filter media from by distance. Used with geoDistance. format is latitude,longitudeb | N/A |
| parentuida | (a user id, only media whose parent's owner matches this will be returned; useful for showing all comments on any of a user's media in combination with the context filter)b | N/A |
| timeLimita | only media newer than the specified number of seconds will be returned, eg: timeLimit=3600 gives media uploaded in the past hour (3600 seconds is one hour). Maximum time limit is 30 years (946080000 seconds).b | N/A |
| externalida | Filters based on the contents of the external ID property of media items. If set this must be one of the following:b | N/A |
