All requests will respond with, at the least, an Integer value for success. This value is either 1 or 0 to represent if the request was processed correctly or not. All requests will also return a String value for error and warnings. This will most likely be blank if you have a success value of 1. However, it is possible to have warnings if your uploaded data, for example, had to be truncated to the appropriate length.
Many responses will be within an array titled medias. In those cases, if you are expecting only one result, you can simply read the first object from that array. However, you should always check to make sure there is only one result when performing a query that could have multiple results rather than simply assume a single result. Exceptions to this are update, deactivate and activate, which return a single Media Object called media.
All functions of the API work exclusively with the Media Object. The purpose of the Media Object is to be a placeholder for an original piece of media uploaded to WellcomeMat, and to link to the appropriately encoded images and videos for that file. The encoded images/videos are linked through an attached Image Object and Video Object. When querying for media, you will always be returned a full description of the Media Object, meaning that it will also include all of the details for the Image Object and Video Object that are attached to that Media Object. If they do not exist, you will simply be returned null values for the Image Object and/or Video Object.
Please note that all return objects are, at their root, a success value, error string, warnings string, and an array of medias.
Media Object
Proper name
JSON variable name
Notes
ID
hash
The unique identifier for this media
WM1 ID
wm1_id
The unique identifier for this media in the old WellcomeMat, if it originated there.
Upload Source
source
How the video was uploaded into the site. You will only need this if you know what it is.
Traffic Generation Override
traffic_url
Traffic override to point all viewers to a webpage where you have embedded your video.
Created
created
The timestamp that this video was created
Updated
updated
The timestamp that this video was last replaced
Data Updated
data_updated
The timestamp at which any associated data was updated
Links to access this media (once media is activated)
Playlists
playlists
The playlists that this video matches
Location Object
Proper name
JSON variable name
Notes
Address
address
City
city
State/Province
state_province
Postal Code
postal_code
Latitude
latitude
Longitude
longitude
Video Object
Proper name
JSON variable name
Notes
HTTPS URL
https_url
URL to retrieve this object's files via HTTPS GET
270p Mobile Video Filename
v270p
360p Low Quality Video Filename
v360p
480p Normal Quality Video Filename
v480p
720p HD Video Filename
v720p
1080p HD Video Filename
v1080p
Preview Object
Proper name
JSON variable name
Notes
Preview ID
preview_id
The unique identifier for the video preview.
HTTPS URL
https_url
URL to retrieve this object's files via HTTPS GET
270p Mobile Preview Filename
v270p_preview
360p Low Quality Preview Filename
v360p_preview
480p Normal Quality Preview Filename
v480p_preview
720p HD Preview Filename
v720p_preview
1080p HD Preview Filename
v1080p_preview
GIF Preview
GIF_preview
A .gif file generated from the preview.
Image Object
Images are taken at 75% of video length. Large image reflects the original aspect ratio. Thumbnail and Play images are cropped if the video ratio is not 16:9.
Proper name
JSON variable name
Notes
Ratio
ID
hash
The unique identifier for this image
HTTPS URL
https_url
The base URL where you can retrieve the following files
Large Image
large
Max width: 1920, Max height: 1080
Video
Thumbnail Image
thumbnail_16x9
320x180
16:9
Play Image
play
640x360. Is a larger version of Thumbnail, but with a Play icon overlayed.
16:9
Links Object
Proper name
JSON variable name
Notes
Base URL
base
Embed URL
embed
Share URL
share
Unbranded Base
unbranded_base
Unbranded Embed
unbranded_embed
Example Response
Endpoint: https://www.wellcomemat.com/api/media/query.php
Parameters Supplied: key, secret, (hash or customid)