TransMékong
Mekong-delta.com

The welcoming rice bowl of Vietnam

Services API

We are developing a services API to serve products definitions, an availability calendar, allow for searching for specific vacancies and eventually book through an agent. The first effort concerns the Bassac, daytime services will follow.

Part of this API is public and part will require an API key. Please contact us for an API key.

We expect TransMékong's API v1 to follow the lines of the OCTO API specification, which might well be emerging as a standard.

This API is under development, functionalities and capabilities shall be added in the future, among which pricing and direct setting of options or even booking.

Some capabilities are described here as a development target, and may not be completely implemented.

Public API

All requests should be JSON. HTTP POST and GET are accepted for the public API.

All responses are JSON, they may be a superset of the API specification, typically with a pointer to human-readable information.

The base URL for the API is https://transmekong.com/api/v1/, to which one appends the endpoint name, as in: https://transmekong.com/api/v1/supplier.

Where the API expects input, such as a product ID or a date, and is not supplied such, it will return an informative error as to what it expects to be able to fulfill the request.

Endpoints

/supplier

The supplier and associated contact details. ref. / try it

/products

A list of products. ref. / try it

/product

Details of a product ref. / try it

Expects:

  • id, the id of a product as returned in the list; then returns the details of one product.
    id may be passed as data in a JSON call, or in the URI, as in /product/{id} 1)

/availability/calendar

A calendar of the availability per product or service. ref. / try it

Expects:

  • productId* the id of the service whose calendar to return
  • localDateStart* and localDateEnd*, the extent of the calendar, now limited to 50 dates

The response lists for each day the maximum availability we hold on that day for a cruise matching the productId, regardless of boat and specific cabins available.

So a request for “productId”: “bassac-cruise_1-night_cantho-” (over 1 night and departing from Cần Thơ) will return availability on each date departing along cantho-cantho or cantho-caibe.

For each day, the response only states the maximum vacancies as a number of passengers; and states as productId the id of the cruise for that exact itinerary.

openingHours lists departure time and expected arrival time, and lists as duration the duration of the trip.

/availability (WIP)

A more detailed availability of a given product for a given party, with:

  • an availabilityId unique to this availability
  • options available
  • the id of the specific services available on these dates.

expects:

  • productId* the id of the service whose availability to return, and
  • units*, a list of passengers,
    as in [{“ADULT”: 2},{“CHILD”: 1}];
  • one optionId* (typically DEFAULT, to get all rooming options)
    and either of:
    • localDate, the date of the beginning of the service
    • localDateStart and localDateEnd, the span of dates over which to return availability, limited to 7 dates
The OCTO API specification accepts in the request a list availabilityIds to filter the current search with. This is obscure and we do not implement this at this time.

Services definition

productId

The services are cruises over one or more nights, between 2 ports.

To allow flexibility in mapping availability, we define services (productIds) with 3 levels of precision.

  1. number of nights
    • bassac-cruise_1-night: all cruises over 1 night (try it)
    • bassac-cruise_2-night: all cruises over 2 nights (try it)
  2. specific itinerary
    • bassac-cruise_1-night_cantho-caibe: all cruises over one night along a specific itinerary (here: from Cần Thơ to Cái Bè). (try it)
    • bassac-cruise_2-night_caibe-cantho-caibe: all cruises over two nights along a specific itinerary (here: from Cái Bè to Cần Thơ and back). (try it)
  3. specific port of departure or arrival
    • bassac-cruise_1-night_cantho-: all cruises departing from a specific port (here: over one night from Cần Thơ). (try it)
    • bassac-cruise_2-night_-cantho: all cruises arriving to a specific port (here: over two nights to Cần Thơ). (try it)

options

The definition of options may vary over time and with the API specification.

This is our interpretation.

optionId identifies the cabins:

  • CABIN: cabin, double-occupancy
  • SINGLE: cabin, single-occupancy
  • DBL: cabin, twin-bedded, double-occupancy
  • TWIN: cabin, twin-bedded, double-occupancy
1)
quirky, but part of the specification
Last modified: 2024/12/04 16:01 [benoit] Copyright (c) 2014-2024 TransMékong 144 Hai Bà Trưng, QNK, Cần Thơ - 0903 033 148