TIH API v2 Updates - A new version for all TIH APIs is now available and its older API versions will be deprecated in 2023. Click on the "News" tab for more information.

This guide will cover the following topics:

  1. Using API Key to call TIH APIs
  2. OAuth Authentication Token Request Flow (To perform specific operations)
  3. Other information to note when using TIH APIs

To learn more about the steps in obtaining an API Key or OAuth Key, check out our Getting Started page.

 

1. Using API Key to call TIH APIs

The TIH APIs are built on a RESTful HTTP architecture where the client (your application) makes HTTP requests to access content and services from TIH. The API requests are authenticated with an API Key (also known as a ClientId), verified by the TIH API servers before allowing any operations. The TIH APIs currently only supports JSON format in the API request and response.

To use TIH APIs, do provide the API key in the request header "X-API-Key" parameter.

Example of Request Header
GET /cruises HTTP/1.1
Host: api.stb.gov.sg
Accept: application/json
X-Content-Language: en
X-API-Key: ghijkl67890

 

With the API Key, you can access to most of the TIH APIs such as:

With these APIs, your application can retrieve rich content and images of points-of-interest in Singapore across the 12 content categories (accommodation, attractions, bars and clubs, cruises, deals, events, food and beverages, precincts, malls and shops, tours, venues, and walking trails).

Visit the respective API pages above to learn more about each API, tips on using the API, and experiment with the API through the "Try it out" section.

 

2. OAuth Authentication Token Request Flow (To Perform Specific Operations)

The TIH APIs leverage on the OAuth 2.0 industry-standard protocol for authorisation and authentication. The following steps illustrate the sequence of API calls to TIH API services to retrieve OAuth access token (also known as OAuth Authentication Token):

  1. Encode the API Key and OAuth Key.
  2. Obtain OAuth access token from the API response.
  3. Provide the OAuth access token in the "Authorization" parameter of the request header for APIs calls that require an OAuth access token.

 

Step 1: Encode the API Key and OAuth Key

An OAuth Key, which acts as a secret key associated to your API Key, is needed for your company to access the following additional features and to perform specific operations:

After receiving the ClientId (also known as API Key) and ClientSecret (also known as OAuth Key), you will need to encode the ClientId:ClientSecret combination (separated by colon) in base64 to obtain an access token. You can use these tools available online for encoding to base64.

For example:
ClientId (API Key) is "abcdefg"
ClientSecret (OAuth Key) is "hijklmn"
ClientId:ClientSecret combination (separated by colon) will be "abcdefg:hijklmn" and needs to be encoded in base64 format

 

Step 2: Obtain OAuth Access Token

Head to the respective OAuth accessToken API page below to obtain the OAuth access token with the following header and request parameters:

For more information on the Visit Singapore Account APIs, please refer to the API User Guide - Visit Singapore Account.

HEADER
Parameters Format / Example
Authorization Basic <base64 encoding of "clientId:clientSecret">
For example:
Basic UkV5dVA3SFIThHNG01eENISWZQaHNoTEczOHc6dXkxaUwIyM0RoTQ==
ContentType application/x-www-form-urlencoded
REQUEST
Parameters grant_type
Description Grant Type
Mandatory Yes
Example client_credentials

 

In the JSON response of the various accessToken APIs, you can retrieve the access token from the “access_token” value. Each OAuth access token is valid for 60 minutes.

If the access token has expired, 

 

Step 3: Provide OAuth Access Token in API Calls

With the access token from TIH OAuth, you can use these following APIs:

With the access token from Visit Singapore Account OAuth, you can use these following APIs:

To use the above APIs, you will need to pass the access token as part of the “Authorization” parameter in the request header of your API call.

Header
Authorization BearerToken <OAuth access token>

 

3. Other information to note when using the APIs:

Please note that the following information is returned in the API response body:

  • The datetime information in the API response is in UTC+8 (SGT) and following the format 'YYYY-MM-DD[T]hh:mm:ss+08:00'.
  • The following field types information format are typically returned in the API response if the field value is blank or does not have any value:
Field Types API Response
Numeric Return null, if field does not have any value
Array Return [ ], if field does not have any value
String Return "", if field value is blank or null