Content APIs allow your applications to contribute and extract content from the Tourism Information and Services Hub (TIH). This guide will cover the following topics:
- Contributing Content to TIH
- Extracting Content from TIH
TIH has rich content of product and experience listings (also known as points-of-interest, POIs or tourism offerings) in Singapore across the various content categories such as accommodation, attractions, events, food and beverages, precincts, malls and shops and tours. In addition, you can also retrieve POIs related to wellness.
1. CONTRIBUTING CONTENT TO TIH
To contribute POIs in Singapore across the various content categories, you can use the following TIH Provider APIs:
Visit the API pages above to find out more about contributing a POI for each content category, such as knowing the mandatory and non-mandatory parameters within the request JSON body, the format of the field types and examples.
Using the TIH Provider APIs
- Create a new POI using the Create <Category> API for a content category. An unique identifier (i.e. uuid) will be generated upon successful creation of the POI record.
- Whenever there are new or changes to information on your existing POI, update the POI using the Update <Category> API and specify the unique identifier of the POI.
- (For all categories) When your existing POI is no longer valid, delete the POI using the Delete <Category> API and specify the unique identifier of the POI.
To perform these functions using the TIH Provider APIs, you will need an OAuth token. For more information on requesting and using OAuth token, please visit this Getting Started page.
Other useful tips on TIH Provider APIs
- Content Language - TIH supports POIs in multiple languages.
- The available languages are English (default), Simplified Chinese, Traditional Chinese, Japanese and Korean.
- When creating a new POI in a particular language,
- The "name", "description" and "body" fields should be written in that particular language.
- The "type" and "tags" fields contain specific terms in the various languages. Please refer to the respective APIs below to retrieve the list for "type" and "tags" in the respective languages.
- To create a POI in a particular language, you can provide the language in the request header under "X-Content-Language".
Possible values for “X-Content-Language” "en" (English, default),
"zh-cn" (Simplified Chinese),
"zh-tw" (Traditional Chinese),
"ja" (Japanese), or
"ko" (Korean)Example of Request Header GET HTTP/1.1
Host: api.stb.gov.sg
Accept: application/json
X-Content-Language: en
X-API-Key: ghijk167890
- Parameters with Specific Values - Use the corresponding general content APIs to retrieve the possible parameter values for the following parameters:
- "type" parameter - use the List Content Types API to retrieve a list of content types (or sub-category) for each content category in the respective languages.
- "tags" parameter - use the List Tags API to retrieve the full list of tags available in the respective languages.
- "dataset" parameter - use the List Datasets API to retrieve the full list of datasets (or content category) available.
- Supported Media for POI - TIH supports two methods to add media such as images to your POI via API:
- Upload media on TIH (Method 1) - Media such as images can be uploaded onto TIH using TIH Media APIs. After uploading of images, the media identifier details (e.g. "uuid", "primaryFileMediumUuid") can be retrieved from the Search Libraries By Keyword or UUIDs API and provided within the following "image" and "thumbnails" parameters when using the Create <Category> API:
- images["uuid"] - "uuid" of image media
- images["libraryUuid"] - "uuid" of library
- images["primaryFileMediumUuid"] - "primaryFileMediumUuid" of image media
- images["url"] - to leave blank
- thumbnails["uuid"] - "primaryFileMediumUuid" of image media
- thumbnails["libraryUuid"] - "uuid" of library
- thumbnails["primaryFileMediumUuid"] - "primaryFileMediumUuid" of image media
- thumbnails["url"] - to leave blank
- Link to external media (Method 2) - Provide the URL for the external media such as images in the following "image" and "thumbnails" parameters when using the Create <Category> API:
- images["url"]
- thumbnails["url"]
- Upload media on TIH (Method 1) - Media such as images can be uploaded onto TIH using TIH Media APIs. After uploading of images, the media identifier details (e.g. "uuid", "primaryFileMediumUuid") can be retrieved from the Search Libraries By Keyword or UUIDs API and provided within the following "image" and "thumbnails" parameters when using the Create <Category> API:
- New Wellness tag - For POIs related to Wellness, you can tag them to Wellness for greater discoverability by specifying the value "wellness" in the "group" parameter within the request JSON body through the Create <Category> API (for new POI) API or Update <Category> API (for existing POI).
- New Events Content Category for Leisure & Business/MICE Events
- The Events content category has been enhanced to support two types of events creation, namely Leisure Events and Business/MICE Events.
- The table below provides a summary on Leisure Events and Business/MICE Events:
Features Leisure Events Business/MICE Events Supported creation of
(a) a single entity or;
(b) a main entity with multiple sub-entities(a) A single event can be created
(b) A main event with multiple sub-events can be created(a) A single event can be created
(Multiple sub-events not supported)Supported Parameters Common parameters (e.g. name, description, body, type, tags, etc).
For more information on the list of parameters for Leisure Events, you may refer to Create Events (Leisure) API.Common parameters (e.g. name, description, body, type, tags, etc), with additional parameters required (e.g. event type, event mode, event edition, projected event statistics and exhibition details*, STB representative details, etc) that are specific for Business/MICE Events.
For more information on the list of parameters for Business/MICE Events, you may refer to Create Business/MICE Events API.
*Note: The additional information on projected event statistics and exhibition details are for STB's reference only and will not be displayed on TIH.Supported Media Media such as images can be uploaded onto TIH using TIH Media APIs. After uploading of images, the media identifier details can be provided within the "image" and "thumbnails" parameters when using the Create Events (Leisure) API Media such as images can be uploaded onto TIH using TIH Media APIs. After uploading of images, the media identifier details can be provided within the "image" and "thumbnails" parameters when using the Create Business/MICE Events API: In addition, Business/MICE Events supports the upload and download of one Business/MICE Event logo image.
The Business/MICE Event logo works with the following APIs and requires the associated Business/MICE Event POI UUID identifier:
- Upload Business/MICE Event Logo - To add or update logo image after the creation of a Buisness/MICE Event POI
- Download Business/MICE Events Logo - To download logo image
- Categories with Business Hours - For Attractions, Shops, Bars & Clubs, Food & Beverages and Tours content categories, you can provide the business hours of your POI using the "businessHour" and "businessHourNotes" parameters. The table below provides some examples of possible business hours scenarios that can be specified using the "businessHour" and businessHourNotes" parameters.
Scenario Example Scenario Examples Daily open (24h) including public holiday "businessHour": [
{
"day": "daily",
"openTime": “00:00",
"closeTime": "23:59",
"description": "",
"sequenceNumber": 1,
"daily": true
}
],
"businessHourNotes": { "notes": ""
},Daily open (time based) including public holiday "businessHour": [
{
"day": "daily",
"openTime": “08:30",
"closeTime": "20:30",
"description": "",
"sequenceNumber": 1,
"daily": true
}
],
"businessHourNotes": {
"notes": ""
},Daily (24h) with public holiday open (time based) "businessHour": [
{
"day": "daily",
"openTime": “00:00",
"closeTime": “23:59",
"description": "",
"sequenceNumber": 1,
"daily": true
},
{
"day": "public_holiday",
"openTime": "08:30",
"closeTime": “14:30",
"description": "",
"sequenceNumber": 2,
"daily": false
}
],
"businessHourNotes": {
"notes": ""
},Daily (time based) with public holiday open (time based) "businessHour": [
{
"day": "daily",
"openTime": “08:30",
"closeTime": "20:30",
"description": "",
"sequenceNumber": 1,
"daily": true
},
{
"day": "public_holiday",
"openTime": "08:30",
"closeTime": “15:30",
"description": "",
"sequenceNumber": 2,
"daily": false
}
],
"businessHourNotes": {
"notes": ""
},Daily open with multiple public holidays "businessHour": [
{
"day": "daily",
"openTime": “00:00",
"closeTime": “23:59",
"description": "",
"sequenceNumber": 1,
"daily": true
},
{
"day": "public_holiday",
"openTime": "09:30",
"closeTime": “15:30",
"description": “Chinese New Year",
"sequenceNumber": 2,
"daily": false
},
{ "day": "public_holiday",
"openTime": “10:00",
"closeTime": “17:00",
"description": “New Year’s Day",
"sequenceNumber": 3,
"daily": false
}
],
"businessHourNotes": {
"notes": "closed on 1st Chinese New Year"
},Monday to Friday same "businessHour": [
{
"day": “monday",
"openTime": “08:30",
"closeTime": “16:30",
"description": "",
"sequenceNumber": 1,
"daily": false
},
{
"day": “tuesday",
"openTime": "08:30",
"closeTime": “16:30",
"description": “",
"sequenceNumber": 2,
"daily": false
},
{
"day": “wednesday",
"openTime": “08:30",
"closeTime": “16:30",
"description": “",
"sequenceNumber": 3,
"daily": false
},
{
"day": “thrusday",
"openTime": “08:30",
"closeTime": “16:30",
"description": "",
"sequenceNumber": 4,
"daily": false
},
{
"day": “friday",
"openTime": "08:30",
"closeTime": “16:30",
"description": “",
"sequenceNumber": 5,
"daily": false
},
{
"day": "public_holiday ",
"openTime": “10:00",
"closeTime": “14:30",
"description": “",
"sequenceNumber": 6,
"daily": false
}
],
"businessHourNotes": {
"notes": "closed on 1st Chinese New Year"
},3 continuous days with same time "businessHour": [
{
"day": “wednesday",
"openTime": “11:30",
"closeTime": “14:30",
"description": “Lunch",
"sequenceNumber": 1,
"daily": false
},
{
"day": “wednesday ",
"openTime": “17:00",
"closeTime": “20:30",
"description": “Dinner",
"sequenceNumber": 2,
"daily": false
},
{
"day": “friday",
"openTime": “11:30",
"closeTime": “14:30",
"description": “Lunch",
"sequenceNumber": 3,
"daily": false
},
{
"day": “friday",
"openTime": “17:00",
"closeTime": “20:30",
"description": “Dinner",
"sequenceNumber": 4,
"daily": false
},
{
"day": “saturday",
"openTime": “11:30",
"closeTime": “14:30",
"description": “Launch",
"sequenceNumber": 5,
"daily": false
},3 continuous days with same time (continued) {
"day": " saturday ",
"openTime": “17:00",
"closeTime": “20:30",
"description": “Dinner",
"sequenceNumber": 6,
"daily": false
},
{"day": “sunday","openTime": “11:30",
"closeTime": “14:30",
"description": “Launch",
"sequenceNumber": 7,
"daily": false
},
{
"day": “sunday ",
"openTime": “17:00",
"closeTime": “20:30",
"description": “DInner",
"sequenceNumber": 8,
"daily": false
},
{
"day": "public_holiday ",
"openTime": “10:00",
"closeTime": “14:30",
"description": “Lunch",
"sequenceNumber": 9,
"daily": false
}
],
"businessHourNotes": {
"notes": "Buffet dinner menu only available on Friday, Saturday, Sunday"
},
2. EXTRACTING CONTENT FROM TIH
Using the following TIH APIs, your application can retrieve rich content and images of POIs in Singapore across the various content categories such as accommodation, attractions, events, food and beverages, precincts, malls and shops and tours.
- Content User API
- Media User API (For more information on the Media User APIs, please refer to the API User Guide - Media)
Search a content category using Search <Category> By Keyword or UUIDs APIs
To search for POIs within a content category, use the Search <Category> By Keyword or UUIDs API that supports keyword search or UUIDs search and specify the following query parameters:
- "searchType" parameter: can have values either "keyword" or "uuids".
- "searchValues" parameter: [keywords] if "searchType=keyword" or [one or a list of uuids separated by comma] if "searchType=uuids".
Search multiple content categories using Search Multiple Datasets By Keyword API
To search for POIs across multiple content categories (or datasets), use the Search Multiple Datasets By Keyword API and specify the keywords to search in the "keyword" parameter.
For scenarios that search multiple datasets at a location in Singapore, use the Search Map By Multiple Datasets API of TIH Enhanced Navigation service to search for multiple content categories within an area identified by location and radius.
Other useful information on TIH Content User APIs
- Pagination Method - TIH APIs supports a combination of "limit" and "offset" query parameters for extracting paginated records in the API response.
- "limit" parameter defines the maximum number of records that can be returned. When no limit is defined, the limit will be set to a default value 20. The maximum value allowed is 50.
- "offset" parameter defines the number of records that will be discarded before returning the response. The default value is 0.
Example of API request: https://api.stb.gov.sg/content/attractions/v2/search?limit=20&offset=0
- The API response of paginated records will also include the following fields, where applicable:
- “totalRecords” field will be assigned the total record count value.
- “retrievedRecords” field will be assigned the count of records for that response.
- "paginationLinks" field with following attributes:
- first attribute provides a link to the first page.
- next attribute provides a link to the next page.
- previous attribute provides a link to the previous page.
- last attribute provides a link to the last page.
Example of API response: { ... ... "paginationLinks": { “self”: “https://api.stb.gov.sg/content/attractions/v2/search?limit=20&offset=60”, “first”: https://api.stb.gov.sg/content/attractions/v2/search?limit=20&offset=0”, “prev”: “https://api.stb.gov.sg/content/attractions/v2/search?limit=20&offset=40”, “next”: “https://api.stb.gov.sg/content/attractions/v2/search?limit=20&offset=80”, }, "totalRecords": 100, "retrievedRecords": 20 }
- Sorting Method - The records in the API response can be sorted using a combination of "sort" and "sortOrder" query parameters.
- "sort" parameter defines the attribute to be sorted by.
- "sortOrder" parameter defines the order in which the result should be sorted. Possible values: "asc" to sort in ascending order, or "desc" to sort in descending order.
Example of API request: https://api.stb.gov.sg/content/attractions/v2/search?sort=name&sortOrder=desc
- Content Language- TIH supports POIs in multiple languages (English, Simplified Chinese, Traditional Chinese, Japanese and Korean). To extract POIs in a particular language, you can provide the language in the request header under "X-Content-Language ". Please refer "1. Contributing Content to TIH" above for an example of the request header with "X-Content-Language".
To get started with extracting TIH content, you will need an API key. Learn how to get an API key from the Getting Started page.
