Media APIs
Media APIs allow applications to contribute and download media, such as images and videos, from the Tourism Information and Services Hub (TIH). This guide will provide the steps to contribute and download media.
Contributing Media
The steps to contribute media follow the entity relationship between Library and Media. The entity relationship between Library and Media can be thought of as following a folder structure, where each library is a folder and each media is a file within the folder. Examples of Media are images, videos and documents.
When a Library is deleted, the Media within the Library would also be deleted. It is recommended to limit to 1 Media per Library.
Following the entity relationship between Library and Media, you must create a library prior to creating the media assets. The steps can be seen in the following diagram.
- Create Library Metadata, using the createLibrary API.
The createLibrary API will return a UUID in the uuid attribute, which is the input for the libraryUUID attribute for the next step.
- Create Media Metadata, using the create media API, such as createImage API.
The createMedia API will require the library UUID generated in the createLibrary API as input for the libraryUUID attribute. The createMedia API will then return a UUID to reference to the Media metadata in the primaryFile attribute, which is required for the next step.
- Upload Media File, using the uploadMedia API.
The uploadMedia API allows you to upload the media’s file data. The file data will be associated to the metadata through the media UUID generated in the create media API, such as createImageAPI. Acceptable file formats are:
- Images may be uploaded in PNG or JPG formats.
- The minimum resolution for image is 1000 by 667 pixels.
- Videos may be uploaded in MOV, MP4, WMV, MPEG, AVI or DVD formats.
- Documents may be uploaded in PDF, DOC, XLS, PPT formats.
- The maximum file size is 20MB.
More tips on the media file requirements can be found here.
For images, if the image has a resolution higher than the following resolution, TIH will auto-generate an image for each of the resolution and associate it with a unique ID in the response:
- small image of width 150 by height 100 pixel resolution (primaryFileSmallUUID),
- medium image of width 280 by height 187 pixel resolution (primaryFIleMediumUUID),
- 1080 hi-res image of height 1080 pixel resolution, width scaled accordingly (thumbnail1080HUUID) and
- 2160 hi-res image of height 2160 pixel resolution, width scaled accordingly (thumbnail 2160HUUID).
{
"primaryFile": "10140870fe29cc94dc2931c1f0307a8d83c",
"primaryFileSmallUuid": "102gf1a3c7cb039459f94d114ef2cge52ya",
"primaryFileMediumUuid": "105015e04af16e3447a960d2a190e7a8462",
"thumbnail1080HUuid": "107235776ec3ca3467087d963798cead030",
"thumbnail2160HUuid": "107735776ec3ca3467087d963798beaa030"
}
To get started, you will need an OAuth token. This page shares more on how to request and use an OAuth token.
Downloading Media
Every media file, from images to videos, is represented by metadata. The metadata is in the form of a JSON object with a set of attributes that provide information about the file. In each metadata, you will find a unique ID (UUID) to reference to the media file.
To download media, the steps are:
- Identify the media UUID, for example:
- Refer to the media search API, such as searchMediaByKeyword API.
- For the media uploaded as part of content contribution (e.g. accommodation, attractions), refer to the response from the Content User API, such as the image array in the searchKeywordByMultiDataset API.
- With the media UUID, you can then download the media using the downloadMedia API.
For images, you can specify the fileType parameter, such as “Small Thumbnail” or “Medium Thumbnail”. If the fileType parameter is empty, the default will download the original image, which is also the highest possible resolution for that image.
To get started, you will need an API key. Learn how to get an API key.
