API Reference

Media.getFiles

Returns a list of media based on provided parameters.

The actual return value is a struct with the totalCount and data properties. totalCount contains the number of items that would have been returned if there was no offset or limit specified.

pageSize has a maximum value of 500 - ie. no more than 500 media items will ever be returned from a single call to this function.

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.


Syntax

array media.getFiles ( int vhost, string sort = 'upload DESC', array filters = array(), int start = 0, int limit = 25, array fields = array(), int noCache = 0, int includeCollectionDetails = 0, int voter_uid = NULL, int includeChildMedia = 0, array childFilters = array(), array childFields = array(), string childSort = NULL, array parentFields = array(), int userId = 0, array options = array() )

Arguments

NameTypeRequiredDefault valueDescription
vhostintRequirednoneThe vhost id.
sortstringOptional'upload DESC'Specify here which field you want to sort on.
filtersarrayOptionalarray()You can specify the filter parameters here as an array. Recognized filters are listed below.
startintOptional0If you specify an offset, you will be the media items starting at this position.
limitintOptional25The total number of files you want to receive.
fieldsarrayOptionalarray()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.
noCacheintOptional0By default this method caches its result for 30 seconds. Setting this parameter to 1 will always give you the latest data. This is only allowed if you have the media.getFiles permission.
includeCollectionDetailsintOptional0 Note: This argument has been deprecated.
The data previoiusly returned when includeCollectionDetails was set to 1 (collectionInfo) is now returned by default when filters[collection] is set to a valid collection id.

For more information, refer to the collectionInfo parameter in the Response Table.
voter_uidintOptionalNULLOptionally, a user ID can be provided to retrieve the user vote values corresponding to the result-set, media items.
includeChildMediaintOptional0If set to 1, immediate children of the media returned in the getFiles will be included in a children p
childFiltersarrayOptionalarray()You can specify the filter parameters for the child media. Valid child media filters are channel,filetype,status,moderationstatus,context and uid
childFieldsarrayOptionalarray()The list of fields you want returned with the child media. Default fields are 'title','message','uid','date','rating','moderationstatus''
childSortstringOptionalNULLSpecify here which field you want to sort the child media on.
parentFieldsarrayOptionalarray()The list of fields you want returned with the mediai's parent. Default fields are 'title','id','uid'
userIdintOptional0The ID of the user, if the user is logged in, it will be determined via the sessionToken, otherwise it will use the parameter, and not return content posted by that users block list
optionsarrayOptionalarray()'searchFields' An array of fields to limit searches to, valid array values are message, title,user,firstname,lastname,filename and tags

Filters

Filters allow you to restrict the data that is returned. Below is a list of valid filters.

NameTypeDescriptionDefault Values
filetypeINTThe 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
moderationStatusINT / STRINGThe 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
exlude_childrenINT / STRINGComma separated list of media IDs to ignore, supported in childFilters also.None
querySTRINGA 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
channelINT / STRINGSpecify a channel ID or a channel Short Name to have media returned from the specified channel.empty
includeChildrenINTSpecifies 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
collectionINTThe collection ID that the media item will be returned from. This field must be the ID of collection in your vhost.empty
uidINTOnly return media uploaded by the specified user ID.empty
titleSTRINGSearches for all media files with a title that contains the specified string.empty
favoriteuidINTReturns 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
parentidINTReturn media who has a parent ID matching this integer.empty
groupidINT/ARRAYReturn media that is a member of the specified group ID(s)empty
eventidINTReturn media that is a member of the specified event ID.empty
includeChildGroupsINTSpecifies 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
contextSTRINGReturn 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'
statusINTThe 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 glossary3
hiddenSTRINGOnly 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
geoDistanceINTDistance in meters from geoCenterempty
notuidINT Return media only from users other than the specified user IDempty
parentuidINTReturn 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
timeLimittimestampReturn 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
startTimeSTRINGThis 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
endTimeSTRINGThis 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
activeTimeSTRINGThis attribute filters by the startdate. If only one value is provided No media with a start date before the activeTime will be returned. Otherwise you can pass a start and end time separated by , eg. 2021-01-10 10:00:00,2021-01-10 12:00,00, and this will return only media with a startdate in that range. 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
notActiveTimeSTRINGThis attribute filters by the end date . No media with an end date past the notActiveTime 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
externalidSTRINGFilters 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
tagSTRINGReturn media that contains the given tagempty
geoSTRINGSet this to 'notnull' to return media that have valid geo-location values, meaning ones with geo_latitude <> null and geo_longitude <> nullempty

Fields

Below you will find a list and description of all of the available fields to have returned with our media.getFiles 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.

NameDescription
avatarThe media ID for the avatar of the user who uploaded the media.
channelChannel ID the media belongs to.
commentcountThe number of comments made on the media item.
extensionThe original file extension of the uploaded media
filetypeThe file type of the piece of media (0,1,2,3,4). Further information is available in the glossary.
hitsThe number of hits the piece of media has received.
messageThe media message.
metadataBy 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.
moderationstatusThe moderation status represented by integers; 0 for unmoderated, 1 for approved, 2 for denied.
ratingMedia rating of the media item.
rotationThe 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.
statusThe media status.
hiddenHave the media hidden value returned in the response.
tagsA string of the media's tags returned to you seperated by a space. Ie: "toronto weather torontoweather".
titleThe media item's title.
uidThe user ID of the user who uploaded the media.
uploadThe date the media item was uploaded (YYYY-MM-DD).
lastupdatetimeThe date the media item was last updated, moderated, rotated.
dateThe date the media was created represented in a 24 hr clock format. (YYYY-MM-DD HH:mm:SS).
user_nameThe username of the user who uplaoded the media item.
votecountThe vote count on the media item.
user_firstnameThe firstname of the user who uploaded the media item.
user_lastnameThe lastname of the user who uploaded the media item.
parentidThe 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_titleThis is available only if the media has a parent media (meaning its parentid is greater than 0). This is available for all filetypes.
parent_infoThis is available only if the media has a parent media (meaning its parentid is greater than 0). This is available for all filetypes.
language2-letter ISO laguage code.
authorThe 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.
streamserverThe RTMP server for streaming if available.
streamnameThe name of the stream to be requested from the streaming server if available.
contextThe context of the media items.
widthThe width of the media item.
heightThe height of the media item.
lengthThe 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_latitudeThe latitude of the piece of media if available.
geo_longitudeThe longitude of the piece of media if avaialble.
offensiveThe number of times the media was reported as offensive.
sharesThe number of times the media was shared.
approvedcommentsThe number of comments posted for this media that were approved.
notdeniedcommentsThe number of comments posted for this media that were not denied (were approved or not yet moderated).
externalidThe external id associated with the file.
Please refer to `externalid` in the Response for the structure of the returned data.
externalidsThe array of external ids associated with the file.
Please refer to `externalids` in the Response for the structure of the returned data.

Response

The responses returned by the getFiles service call.

NameDescriptionPossible Values
avatarThe media ID for the avatar of the user who uploaded the media.INT
channelChannel ID the media belongs to.INT
commentcountThe number of comments made on the media item.INT
extensionThe original file extension of the uploaded media. An example would be png.STRING
filetypeThe file type of the piece of media (0,1,2,3,4). Further information is availe in the glossary.0,1,2,3,4
hitsThe number of hits the piece of media has received.INT
messageThe media message.STRING
metadataThis 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
metadataArrayThe 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
moderationstatusThe moderation status represented by integers; 0 for unmoderated, 1 for approved, 2 for denied.0,1,2
ratingMedia rating of the media item.INT
rotationThe 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
statusMedia StatusINT / STRING 0, 1, 2, 3, -1, 'unmoderated', 'notdenied', 'accepted'/'approved', 'denied', 'all'
hiddenMedia hidden valueSTRING hidden, public, all
tagsA string of the media's tags returned to you seperated by a space. Ie: "toronto weather torontoweather".STRING
titleThe media item's titleSTRING
uidThe user ID of the user who uploaded the media.INT
uploadThe date the media item was uploaded (YYYY-MM-DD).YYYY-MM-DD
dateThe date the media was created represented in a 24 hr clock format.(YYYY-MM-DD HH:mm:SS)
user_nameThe username of the user who uplaoded the media item.INT
votecountThe vote count on the media item.INT
uservoteThis key-value pair will be omitted if voter_uid was not supplied as a parameter. The vote value on the media item with respect to the provided voter_uid user id.NULL (no vote); 0 (negative vote); non-zero (positive vote).
user_firstnameThe firstname of the user who uploaded the media item.STRING
user_lastnameThe lastname of the user who uploaded the media item.STRING
parentidThe 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_titleThe title of the parent media. STRING
parent_infoAn array of the parent media information. STRING
language2-letter ISO code.STRING
authorThe 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
streamserverThe RTMP server for streaming if available.STRING
streamnameThe name of the stream to be requested from the streaming server if available.STRING
contextThe context of the media items.generic, all, comment, note, commentnote, genericcomment, parent, child
widthThe width of the media item.INT
heightThe height of the media item.INT
lengthThe 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_latitudeThe latitude of the piece of media if available.NUMBER
geo_longitudeThe longitude of the piece of media if avaialble.NUMBER
collection_detailsThe 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'=> '' )
collectionDetailsThe 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'=> '' )
collectionInfoThe 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 ) )
offensiveThe number of times the media was reported as offensive.INT
sharesThe number of times the media was shared.INT
approvedcommentsThe number of comments posted for this media that were approved.INT
notdeniedcommentsThe number of comments posted for this media that were not denied (were approved or not yet moderated).INT
externalidThis 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 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
externalidsThis 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 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
   )
)

Sample Response

Sample REST Response
http://api.newspark.ca/services/rest/media/getfiles?vhost=[VHOST_ID]&filters[channel]=[CHANNEL_ID]&fields[]=avatar&fields[]=channel
<?xml version="1.0" encoding="UTF-8"?>
<result>
  <totalCount>1</totalCount>
  <data>
    <item>
      <avatar>0</avatar>
      <channel>CHANNEL_ID</channel>
      <commentcount>0</commentcount>
      <filetype>4</filetype>
      <hits>0</hits>
      <id>MEDIA_ID</id>
      <message><p>
	This is some test text media</p>
</message>
      <rating>0</rating>
      <status>3</status>
      <tags>media test text example</tags>
      <title>Test text media</title>
      <uid>USER_ID</uid>
      <upload>2012-01-24 14:21:52</upload>
      <user_name>USER_NAME</user_name>
      <vhost>VHOST_ID</vhost>
      <votecount>0</votecount>
      <publicUrl>http://fmdevs3.filemobile.com/storage/MEDIA_ID</publicUrl>
      <thumbUrl>http://fmdev.s3.amazonaws.com/storage/MEDIA_ID</thumbUrl>
      <location>fmdevs3</location>
    </item>
  </data>
  <vhost>VHOST_ID</vhost>
</result>

Sample JSON Response
{
    "status": true,
    "result": {
        "totalCount": 1,
        "data": [
            {
                "avatar": "0",
                "channel": CHANNEL_ID,
                "commentcount": 0,
                "filetype": 4,
                "hits": 0,
                "id": MEDIA_ID,
                "message": "

\r\n\tThis is some test text media

\r\n", "rating": 0, "status": 3, "tags": "media test text example", "title": "Test text media", "uid": 1071107, "upload": "2012-01-24 14:21:52", "user_name": "USER_NAME", "vhost": VHOST_ID, "votecount": 0, "publicUrl": "http://fmdevs3.filemobile.com/storage/MEDIA_ID", "thumbUrl": "http://fmdev.s3.amazonaws.com/storage/MEDIA_ID", "location": "fmdevs3" } ], "vhost": VHOST_ID } }

Code examples

0 comments

Be the first to comment on getFiles.

Add a Comment

  • captcha