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 various content categories such as accommodation, attractions, events, food and beverages, precincts, malls and shops and tours.
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 tourism offerings and media assets via the Content Provider APIs and Media Provider APIs
- Access the Visit Singapore Account APIs, to enable a seamless log in for your customers
- Access the Recommendation Engine APIs to provide recommendation services for your customers
- Access the Itinerary Planner APIs for your users to create their own Singapore itinerary based on visitors' profile (nationality, interest) and travel period.
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:
- 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.
| 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,
- 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.
| Header | |
| Authorization | BearerToken <OAuth access token> |
3. Other information to note when using the APIs:
The section provides additional useful information on the API response body:
Datetime
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'.
Blank Field
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 |
Content Language
For APIs that support multi-language content, you can contribute or extract content in a different language by providing the language value in the request header under “X-Content-Language”. As an example, if the value “zh-cn” is provided in the request header parameter “X-Content-language”, the API response given will be in Simplified Chinese. If "X-Content-Language" is not set, the default language for the content is English.
| 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 |
TIH APIs that supports multi-language content: