TIH regularly enhances its APIs products to follow good API design practices and standards, with the aim to reduce complexity, improve the quality and consistency of the TIH APIs for developers.

A new version (v2) of all TIH APIs was released in October 2022 with the enhancements described in the following table and will replace the older versions of the APIs. The older API versions v1 and v1.1 will become non-functional and deprecated on October 31, 2023*

*This is an extension from the earlier deprecation date of April 30, 2023 to give businesses more time to make the necessary changes.

What you need to do:

  • Assess the impact of the version changes for the APIs you're using in your application
  • Modify/upgrade and test your application with the latest API version v2
  • Deploy changes before the deprecation date.

 

Important Information:

Kindly ensure your application is updated to use the latest API version v2, before the deprecation date. This is to avoid your application to malfunction. For more information, you may refer to respective API pages for the latest documentation.

 

1. List of enhancements introduced in TIH APIs version 2:

a. Global Changes on TIH APIs

TIH API Breaking Changes
For content providers and users of TIH APIs New Domain Name Enhancement Changes:

Applicable for all TIH APIs(except Visit Singapore Account APIs).

New domain name:  api.stb.gov.sg

Old domain name:  tih-api.stb.gov.sg

For content providers and users of TIH APIs Changes to Request Header Enhancement Changes

  • API Key (also known as ClientId) to be provided in the request header using header parameter "X-API-Key", instead of in the URL request parameter "apikey" which has been removed.
  • Content Language - For APIs supporting multi-language content, the language will be provided in the request header using header parameter "X-Content-Language ", instead of in the URL request parameter "language" which has been removed.
    • Possible values: "en" (English), "zh-cn" (Simplified Chinese), "zh-tw" (Traditional Chinese), "ja" (Japanese) and "ko" (Korean). The default language is English if the header parameter "X-Content-Language" is not set.
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
For content providers and users of TIH APIs New API URL Endpoint Enhancement Changes

Changes in URL endpoint in the updated version (v2) of TIH APIs, to follow a standardised service endpoint format. Refer to the table below for the respective v2 APIs pages on the updated URL endpoint.
TIH API Other Changes
For content providers and users of TIH APIs Enhanced HTTP Status Response Enhancement Changes

The structure of the HTTP status response is enhanced with the following fields, to provide more details on the error scenario for developers:

  • "code": HTTP error code.
  • "name": Contain the unique name of HTTP error.
  • "subcode": Contain the computer readable description of the error.
  • "message": Contain the human readable description of the error.
  • "debugId": Unique error id (also known as tracer ID) generated on the server side, for troubleshooting purpose. 
Example of Request Header
{
“status”: {
“code”: 422,
“name”: “UNPROCESSABLE ENTITY”,
“message”: “The searchValues parameter must be 255 characters or less.”,
“subCode”: “exceedLengthInSearchValues”,
“debugId”: "fghjk437s"
}
}
For content providers and users of TIH APIs Changes to DateTime Format in API Response Enhancement Changes

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’.
For content providers and users of TIH APIs New HATEOAS Feature Enhancement Changes

HATEOAS (Hypermedia as The Engine of Application State) is a component of the REST application architecture. With HATEOAS, application servers can provide information dynamically through links, provided to the clients and users, to improve interaction and discoverability of APIs.
The following HATEOS guidelines are introduced in the updated version (v2) of TIH APIs:

  • For resources created with "POST", the links to update ("PUT") or delete ("DELETE") the resource will be returned, where applicable.
  • For "PUT" request creating a new resource or replacing resources, links to update or delete a resource will be provided, where applicable.
  • For "GET" request fetching all the resources, a self-link will be provided for each resource, where applicable.
Example of HATEOAS given in the API response may be like:
{
... ...
“links”: [
    {
        “href”: “https://api.stb.gov.sg/content-management/cruises/v2/jfwXHguv7Vi,”,
        “rel”: “update”
        “method”: “PUT”
    },
    {
        “href”: “https://api.stb.gov.sg/content-management/cruises/v2/jfwXHguv7Vi”,
        “rel”: “delete”
        “method”: “DELETE”
    }
] 
... ...
}

 

b. Specific Changes

 TIH API Breaking Changes
For content  users of TIH APIs New Pagination Method APIs:

 

Enhancement Changes:

Changes to the pagination method in the TIH APIs with pagination.

  • Added new request parameters "limit" and "offset".
    • "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 is 50.
    • "offset" parameter defines the number of records that will be discarded before returning the response. The default value is 0.
  • Removed request parameters "nextToken", "maxrecord", "page" and "pageSize".
Example of API request:
https://api.stb.gov.sg/content/attractions/v2/search?limit=20&offset=0

 

  • Added new fields "TotalRecords" and "RetrievedRecords" in API response.
    • TotalRecords” field will be assigned the total record count value.
    • RetrievedRecords” field will be assigned the count of records for that response.
  • The API response of paginated records will also include links to "first", "next", "previous" and "last" pages, where applicable.
    • 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
}
For content  users of TIH APIs Changes to Sorting Request Parameters

APIs:

 

Enhancement Changes:

Changes to the sorting request parameters:

  • Changed request parameter "sortBy" to "sort". The "sort" parameter defines the attribute to be sorted by.
  • Change request parameter "sort_order" to "sortOrder". The "sortOrder" parameter defines the order in which the result should be sorted.
Example of API request:
https://api.stb.gov.sg/content/attractions/v2/search?sort=name&sortOrder=desc

https://api.stb.gov.sg/content/deals/v2/search?sort=name&sortOrder=asc
For content  users of TIH APIs  Changes to Search APIs

APIs:

 

Enhancement Changes:

Content User APIs & Deals User APIs

Example of API request:

To search by keyword:

https://api.stb.gov.sg/content/bars-clubs/v2/search?searchType=keyword&searchValues=Marina Bay

To search by UUIDs:

https://api.stb.gov.sg/content/bars-clubs/v2/search?searchType=uuids&searchValues={list of uuids}

 

Media User APIs

  • For libraries, both librarySearchByKeyword API and libraryByUUID API are merged into a single Search Libraries By Keyword or UUIDs API that supports both keyword and UUIDs search.
  • For media, both search by keyword APIs (searchMediaByKeyword, documentSearchByKeyword, imageSearchByKeyword, videoSearchByKeyword) and by UUID APIs (getMediaByUUID, documentByUUID, imageByUUID, videoByUUID) are also merged into a single Search Media By Keyword or UUIDs API that supports both keyword and UUIDs search.
  • The merged API will have new request parameters "searchType" and "searchValue", similar to Content User APIs.
Example of API request:

To search by keyword:

https://api.stb.gov.sg/media/common/v2/search?searchType=keyword& searchValues=Marina Bay

To search by UUIDs:

https://api.stb.gov.sg/media/common/v2/search?searchType=uuids& searchValues={list of uuids}
For content providers and users of TIH APIs  Changes to List Content & Media Content Types, Media Content and Autocomplete List APIs

APIs:

 

Enhancement Changes:

List Content Types APIs

The following Content list<Category>Types APIs are merged into a single List Content Types API to retrieve the list of content types (or sub-categories) for each category. The merged API will have a new request parameter "category" which can have value [accommodation | attractions | bars_clubs | cruises | events | food_beverages | precincts | shops | tours | venues | walking_trails] to indicate the content category.

  • listAccommodationTypes
  • listAttractionsTypes
  • listBarsClubsTypes
  • listCruisesTypes
  • listEventTypes
  • listFoodBeveragesTypes
  • listShopsTypes
  • listTourTypes
  • listVenueTypes
  • listWalkingTrailTypes

 

List Media Content Types APIs

The following Media list<Category>Types APIs are merged into a single List Media Content Types API to retrieve the list of media content types (or sub-categories) for each category. The merged API will have a new request parameter "category" which can have value [accommodation | attractions | bars_clubs | cruises | events | food_beverages | precincts | shops | tours | venues | walking_trails] to indicate the media content category.

  • listAccommodationTypes
  • listAttractionTypes
  • listBarsClubsTypes
  • listCruisesTypes
  • listEventFestivitiesTypes
  • listFoodBeveragesTypes
  • listShopsTypes
  • listTourTypes
  • listVenuesTypes

 

Content & Media - AutoComplete List By Type API

The following two APIs are merged into a single AutoComplete List By Type API for both content and media. The merged API will have a new request parameter "searchResourceType" which can have values "content" or "media" to indicate the resource type to search.

  • autoCompleteByType (Content)
  • autoCompleteByType (Media)
For content providers and users of TIH APIs  Changes to Fields in API Response

APIs:

 

Enhancement Changes:

All content categories:

  • Aligned all 11 content categories (dataset) to plural form across all APIs.

 

Attractions, Shops, Bars & Clubs, Food & Beverages and Tours content category:

  • Changed field name "notes" (for business hours) to "businessHourNotes.notes". Example:
    "businessHourNotes": {
       "notes": "Opens only on Mondays"
    }

 

Attractions content category:

  • Changed data type of field "pricing" from string to the following object. Example:
    "pricing": {
       "others": "$100"
    }

 

Cruises content category:

  • Changed maximum field length of field "organisationName' to 100 characters.

 

Events content category:

  • Changed field name "price" to "pricing".
  • Changed maximum field length of field "eventOrganizer' to 100 characters.

 

Precincts content category:

  • Changed field name 'perimeter["lat"]' to 'perimeter["latitude"]'.
  • Changed field name 'perimeter["lon"]' to 'perimeter["longitude"]'.
  • Changed maximum field length of field "organisationName' to 100 characters.

 

Tours content category:

  • Changed field name "price" to "pricing".
  • Change field name "language" to "tourLanguage".
  • Changed maximum field length of field "companyName' to 100 characters.

 

Venues content category:

  • Changed field name "configurable" to "layoutConfigurable".

 

Search Company By Keyword API:

  • Changed field name "status" to "companyStatus".

 

c. New API URL Endpoint

Changes in URL endpoint in the updated version (v2) of TIH APIs, to follow a standardised service endpoint format. Refer to the respective v2 APIs pages on the updated URL endpoint:

Updated v2 APIs Old v1/v1.1 APIs
Content User API (v2) Content User API (v1)
Content Provider API (v2) Content Provider API (v1/v1.1)
Deals User and Provider API (v2) Deals User and Provider API (v1/v1.1)
Media User API (v2) Media User API (v1)
Media Provider API (v2) Media Provider API (v1)
Enhanced Navigation Map API (v2) Enhanced Navigation Map API (v1/v1.1)
Itinerary Planner API (v2) Itinerary Planner API (v1)
Recommendation Engine API (v2) Recommendation Engine API (v1)
3rd Party Information Sources API (v2) 3rd Party Information Sources API (v1)

 

2. Cessation of 360 Image and 360 Video APIs

The following 360 Image and 360 Video APIs will be ceased and no longer available from 30 April 2023, without any API replacement:

  • 360imageByUUID
  • 360imageSearchByKeyword
  • 360videoByUUID
  • 360videoSearchByKeyword