API User Guide - Itinerary Planner

Itinerary Planner API

The Itinerary Planner service consists of a suite of APIs that allows your digital application to integrate with, allowing your application users to create, manage and generate recommended itineraries based on their preferences and travel period. Your application users can invite friends and family to co-plan their itineraries to Singapore. The Itinerary Planner service is tied with the Visit Singapore Account (VS Account) service as a fast, convenient and secure way for your application users to log into your application.

This guide covers the integration process flow to use the Itinerary Planner APIs with the VS Account service.

Setting Up Your Access to Itinerary Planner and VS Account APIs

To use the Itinerary Planner APIs, start by registering for a TIH Business account and request for both the VS Account and Itinerary Planner Service through the following procedure:

1. The partner shall submit the application form to request for the Itinerary Planner and VS Account service with the following key information. When filling up the application form, please ensure that the Itinerary Planner and VS Account service have been selected.
   
   1. TIH Portal ID refers to the email address used to register for a TIH Business account
   2. Nature of Business
   3. Intended use of Itinerary Planner and VS Account APIs
   4. Application(s) Name, Description and URL
   5. Redirect URL refers to the application's url to redirect the VS Account user to upon successful authorisation
   6. Applicant’s Privacy Policy and Terms of Service URLs
   7. Application administrator’s email address to receive notifications if a user requests to revoke the partner's application permission to access his/her personal data.
       
2. The partner shall submit all necessary information as may be required by STB in connection with their application for the Itinerary Planner and VS Account service. By doing so, the partner warrants that any information, which they have provided in order to obtain the API, is accurate and complete for the duration of their access and/or use of the API. If there is any update to the information provided, they are expected to inform TIH Helpdesk at (stb_tih@stb.gov.sg) immediately.
    
3. By requesting for the Itinerary Planner and VS Account and Itinerary Planner service, the partner unconditionally agree to be bound by TIH Terms of Use, which may be updated and amended from time to time at STB’s sole and absolute discretion.
    
4. Once the request has approved, an email with the Client Id and Client Secret will be sent to the partner’s email address and application administrator’s email address.
    
5. The partner is then able to integrate the Itinerary Planner and VS Account APIs into the specified application(s) by following the specifications captured in this guide for Itinerary Planner document and the API User Guide - Visit Singapore Account.

API Interface Overview

The Itinerary Planner APIs are RESTful web services based on representational state transfer (REST) technology, that uses HTTP requests to access data from the Itinerary Planner service. The APIs leverages the OAuth 2.0 industry-standard protocol for authorization and authentication of the VS Account.

The following provides an overview of the available methods and formats to access the data via the APIs.

The available API endpoints for partners include, but not limited to, the following:

1. Authentication
   • A valid OAuth access token is required to access the Itinerary Planner and VS Account APIs. Refer to OAuth Authentication Process Flow, tapping on the OAuth 2.0 authorisation framework. The flow first gets a code from the authorisation server, followed by exchange the code for an access token. The code-to-token exchange requires the Client Id and Client Secret.
   • For the partner’s application user to access the Itinerary Planner service, it is required to authenticate the VS Account of the application user before accessing the Itinerary Planner APIs. The only exception will be the Recommend Itinerary API, where the application user is not required to login to VS Account.

    

2. Request and Response Format
   • The Itinerary Planner APIs request and response support only the JSON format. Non-JSON format request will receive error code 406.
   • For API with a POST/PUT/DELETE HTTP method, it is mandatory to indicate "application/json" in the "Content-Type" request header.
     

     Example: Request Method & URL	Create Itinerary API POST [domain]/services/itineraries/v2/plans
     Request Header	Content-Type: application/json Authorization: BearerToken <accessToken> X-Content-Language: en

      

3. Available API Endpoints
   • OAuth Authentication APIs use this production domain: account.visitsingapore.com
   • VS User Account related APIs use this production domain: api.visitsingapore.com
   • Itinerary Planner APIs use this production domain: api.stb.gov.sg

Integrating with Itinerary Planner and VS Account APIs

The steps to integration are as follows:

• Register an application with the Tourism Information and Services Hub (TIH)
• Integrate with the VS Account service by following the steps in the API User Guide - Visit Singapore Account
  • Authenticate the VS Account user and user authorises the application to access the user's data
  • Get a code from the authorisation server, followed by exchange the code for a VS account access token of the application user
• Start using the Itinerary Planner APIs with the VS account access token to be added in the Request Headers when calling the APIs

When using the Itinerary Planner service, please note the following:

1. As a pre-requisite, a valid VS Account is required when requesting any of the Itinerary Planner service API, except for the Recommend Itinerary API.
    
2. To access an itinerary, the VS account access token of the application user should be that of either the owner or an authorized participant of the itinerary.
    
3. The following are the user roles defined in the Itinerary Planner service,
   
   1. Owner refers to the partner’s application user who owns the itinerary.
   2. Participants refers to the partner’s application users who have an existing VS account and have been invited to participate in the planning of the itinerary.
   3. Invites refers to users who have been invited to participate in the planning of the itinerary but do not have a VS account.
       
4. The user information of the participants will only be made available in the responses of the Itinerary Planner APIs (e.g. View Itinerary, etc) if the participants have granted access to the partner’s application through a consent page from VS Account portal, as part of the VS Account OAuth Authentication Process Flow.
    
5. An itinerary is private and can only be viewed and updated by its owner and participants of the itinerary.
    
6. Both the owner and participants can invite others to participate in the planning of an itinerary.
    
7. An itinerary can be scheduled or unscheduled.
   
   1. Scheduled refers to the start date and end date of the itinerary is clearly defined and items in the itinerary will be organized into the respective dates (days).
   2. Unscheduled refers to no dates being defined for the itinerary and items in the itinerary will be organized as a single listing.
       
8. An itinerary can only be deleted by its owner.
    
9. A participant can leave an itinerary that he/she is a part of.
    
10. The owner of an itinerary cannot leave the itinerary unless there are other participants associated to the itinerary. The owner will have to delegate another participant of the itinerary as the new owner upon leaving the itinerary.
     
11. The owner of an itinerary must delete the itinerary if he/she wants to leave it when there are no other participants associated to the itinerary.
     

The following table shows the access rights of each user role for the Itinerary Planner APs.

Overall Itinerary Flow

The following diagram shows the process flow to use the Itinerary Planner APIs.

Access the Itinerary Planner APIs

Get started today! The following provides more information on the Itinerary Planner APIs.

Itinerary Planner

Empower your visitors to create their own Singapore itinerary.

View APIs

Recommend Itinerary API

The Recommend Itinerary API will return a recommended itinerary based on a set of query parameters such as start date & end date of trip, arrival & departure time, interests and nationality.

The Recommended Itinerary API will provide a proposed schedule of daily activities, including events, attractions, dining locations for each day across the duration of the travel period.

Create Itinerary API

The Create Itinerary API allows the creation of an itinerary based on the start and end date of the trip. The Create Itinerary API will also allow participants and Points of Interests (POIs) to be added. When inviting the participants to an itinerary, an email or SMS will be sent to the invited participants informing them of the invitation.

Upon successful execution of this API, the itinerary is created in TIH and the partner’s application user that created the itinerary will take on the owner role.

View Itinerary API

The View Itinerary API allows the partner’s application users to view the details of a selected Itinerary and associated participants details. When using the View Itinerary API, a valid itinerary identifier (uuid) should be provided together with a valid VS account access token.

List Itineraries API

The List Itineraries API will display the list of itineraries that the partner’s application user has created or is a participant. Similarly, the response will only show the user information of participants that have granted access to the application.

Update Itinerary API

The Update Itinerary API will allow an authorized user of the itinerary to edit its details by adding and removing points of interest to visit. When using the Update Itinerary API, a valid itinerary identifier (uuid) should be provided together with a valid VS Account access token.

The Update Itinerary API will not allow the removal of participants from an itinerary. To remove a participant, please use the Leave Itinerary API or Remove Participants API.

Leave Itinerary API

The Leave Itinerary API will allow participants to leave itinerary they are associated with. When using the Leave Itinerary API, a valid itinerary identifier (uuid) should be provided together with a valid VS account access token.

If the partner’s application user is the owner of the itinerary, he/she will have to delegate another participant of the itinerary as the new owner of the itinerary. The unique identifier (uuid) of the participant nominated as the new owner will have to be provided as part of the API request.

However, when there are no other participants associated to an itinerary, the owner of the itinerary will not be able to delegate another participate as the new owner and will have to delete the itinerary via the Delete Itineraries API.

Delete Itinerary API

The Delete Itinerary API will allow the owner of the itinerary to delete his/her itinerary. When using the Delete Itinerary API, a valid itinerary identifier (uuid) should be provided together with a valid VS account access token that belongs to the owner of the itinerary. Only the owner of the itinerary can delete his/her itinerary.

Add Participants API

The Add Participants API will allow authorized users of the itinerary to add new participants to the itinerary. When using the Add Participants API, a valid itinerary identifier (uuid) should be provided together with a valid VS account access token.

When inviting participants to an itinerary, an email or SMS will be sent to the invited participants informing them of the invitation. Upon successful execution of this API, the itinerary is updated in TIH and the role of the newly added person is updated either as “Participant” or “Invite” based on the following two possible scenarios.

• Scenario A - Invited person has a VS Account
  • The person will be updated as a “Participant”.
  • If the invited participant has a VS account and has previously granted access to the partner’s application through a consent page from VS Account portal, he/she is immediately added to the itinerary as a participant and receives a notification in the VS Account portal.
     
• Scenario B - Invited person does not have an existing VS Account
  • The person will be updated as an “Invite”.
  • Upon successful creation of a VS Account and granting of access to the partner’s application, the person will be updated as a “Participant” following Scenario A.

Remove Participants API

The Remove Participants API will allow a participant of the itinerary to remove participants from the itinerary. When using the Remove Participants API, a valid itinerary identifier (uuid) should be provided together with a valid VS account access token.

Once a participant is removed from an itinerary, he/she will be disassociated from the itinerary and will not be able to access the itinerary information.