This guide will cover the following topics:
- Using API Key to call TIH APIs
- OAuth Authentication Token Request Flow (To perform specific operations)
- 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):
- Encode the API Key and OAuth Key.
- Obtain OAuth access token from the API response.
- 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:
- Contribute information via the Content Provider APIs and Media Provider APIs
- Access the Visit Singapore Account APIs, which enable a seamless log in for your customers
- Access the Recommendation Engine APIs which let you provide recommendation services to your customers
- Access the Itinerary Planner APIs which empower your visitors to create their own Singapore itinerary. The Visit Singapore Account service is required for the Itinerary Planner service as a convenient and secure way for your customers to log into your application.
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.
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:
- TIH OAuth accessToken API page (For Content Provider APIs, Media Provider APIs and Recommendation Engine APIs)
- Visit Singapore Account OAuth accessToken API page (For Visit Singapore Account APIs and Itinerary Planner APIs)
For more information on the Visit Singapore Account APIs, please refer to the API User Guide - Visit Singapore Account.
|Parameters||Format / Example|
|Authorization||Basic <base64 encoding of "clientId:clientSecret">
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,
- For TIH OAuth: a new token can be obtained by using the TIH accessToken API
- For Visit Singapore Account APIs: a new token can be obtained by calling the Visit Singapore Account accessToken API or Visit Singapore Account refreshToken API. For more information on Visit Singapore Account accessToken, refer to the API User Guide - Visit Singapore Account.
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.
|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|