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 3D models.
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 Create Libraries API.
The Create Libraries 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 Create Images API.
The create media API (such as Create Images API and Create Videos API) will require the library UUID generated in the Create Libraries API as an input for the libraryUUID attribute. The create media API will return a UUID to reference to the Media metadata in the primaryFile attribute, which is required for the next step.
To create the metadata of 3D model, you can use the Create Images API and specify the parameter mediaType to "image" in the request JSON body.
- Upload Media File, using the Upload Media File API.
The Upload Media File API allows you to upload the media’s file data. The file data will be associated with the metadata of the media UUID generated in the create media API, such as Create Images API. Acceptable file formats are:
- Images: PNG or JPG formats
- The minimum resolution for image is 1000 by 667 pixels
- Videos: MP4 format
- 3D Models: FBX 2014/2015 (Binary) and MAX (3DS MAX) format
- The maximum file size is 20MB.
For more information, refer below:
If an image has a resolution higher than the following resolutions listed below, 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) which is typically used for thumbnail display,
- 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).
After uploading of image, the media identifier details (e.g. "uuid", "primaryFileMediumUuid") can be retrieved from the Search Libraries By Keyword or UUIDs API.
{
"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 Search Media By Keyword or UUIDs 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 or thumbnail array in the Search Multiple Datasets By Keyword API.
- With the media UUID, you can then download the media using the Download Media File 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.
Downloading 3D Model New
To download the compressed library containing 3D model file, the steps are:
- Identify the library UUID
- Refer to the library search API, such as Search Libraries By Keyword or UUIDs API. For 3D model, you can specify the parameter mediaType value as "3dmodel".
- Refer to the library search API, such as Search Libraries By Keyword or UUIDs API. For 3D model, you can specify the parameter mediaType value as "3dmodel".
- With the library UUID, you can download the compressed library containing the 3D model file using the Download Compressed Library of 3D Model File API.
To get started, you will need an API key. Learn how to get an API key.
