Sample 2 - Product search

This sample document is designed to provide you with a sample journey that would allow you to use the API to find, price and store product in a basket.
Please note the products defined in the journey are imaginary products and will not work in the test system, this journey is for illustrative purposes only.

A typical pricing journey


Diagram of Sample 2 flow - Product search

This sample is designed to show you how you can use the API to search for and identify product to buy.

We will start off by doing a geographic hierarchy search to find a country, area, region or resort. You could, as an alternative, use one of these messages instead:

  • /api/country/listReturn a set of countries to search for product against
  • /api/country/area/listReturn a set of country areas to search for product against
  • /api/country/region/listReturn a set of regions to search for product against
  • /api/resort/listReturn a set of resorts to search for product against

Then we will search for product at that resort, price it and add it to the basket.

Finally, we will search for products identified as being extras, either at resort level or contract level and add one of them to the basket.

The process of converting a basket into a booking is documented here

From a performance perspective, we would suggest that you cache the responses from any list function for 24 hours as the response data is unlikely to change materially in that time.

Example messaging

In the example flow set out below we have not shown the booking process you will find an example of that in Sample 1 by clicking here. Please click on any of the messages below to expand them and view sample JSON requests and responses.

In the first instance we have to identify a geographic area to search against, the hierarchy is perfect for this in that it returns a structure showing all the places that the system has product

{
    "timeStamp": "2022-07-06T12:44:06",
    "channel": 1,
}

You can then use the results to search for product in a given geographic area

{
  "timeStamp": "2022-07-06T12:44:06",
  "success": true,
  "countryHierarchyDetails": [
    {
      "id": 23,
      "name": "Brazil",
      "areas": [
        {
          "id": 33,
          "name": "Amazonas",
          "regions": []
        },
        {
          "id": 34,
          "name": "Baha",
          "regions": []
        },
        {
          "id": 35,
          "name": "Piaui",
          "regions": [
            {
              "id": 30,
              "name": "Parnaiba River",
              "resorts": [
                {
                  "id": 57,
                  "name": "Floriano",
                  "latitude": "-6.7726534",
                  "longitude": "-43.0070616"
                },
                {
                  "id": 59,
                  "name": "Piaui",
                  "latitude": "-7.7183",
                  "longitude": "-42.7289"
                },
                {
                  "id": 58,
                  "name": "Teresina",
                  "latitude": "-5.092011",
                  "longitude": "-42.803760"
                }
              ]
            },
            {
              "id": 29,
              "name": "Tocantes River",
              "resorts": []
            }
          ]
        }
      ]
    }
  ]
}

This next request is used to dive deeper into the system to get possible accommodations in the area, obviously if you search at country level you will get a bigger response set than you would at Resort level, the choice though is yours

In truth most of our clients cache this level of response in their systems and only hit our pricing and availability messages in real time

{
  "timeStamp": "2022-10-20T16:27:30",
  "channel": 0,
  "divisionId": 1,
  "searchType": "ACCOMMODATION",
  "geographicArea": "COUNTRY",
  "geographicalId": 30
}

The response is to get a list of stock item ids which you can then feed into a price request to get physical availability for each

{
  "timeStamp": "2022-10-20T16:27:30",
  "success": true,
  "stockItemIds": [
    7552,
    6402,
    5252,
  ]
}

This message is the first message that should never be cached, or not for more than a few minutes. It returns realtime availability for the requested products along with pricing data

{
  "timeStamp": "2022-11-08T14:03:19.065Z",
  "channel": 0,
  "currencyCode": "GBP",
  "language": "DE",
  "stockItemIds": [ 7552, 6402, 5252],
  "dateValue": "2024-11-08",
  "duration": 7,
  "noAdults": 2,
}

The response is obviously determinate on real world availability and pricing setup in the system

{
                                Please add a sample response in here that gives the reader a reasonable understanding of the response
}

As you can see this is where passenger details are added. passengerRPH is used so that the items in the basket can be assigned to specific passengers

{
    "timeStamp": "2022-07-06T12:44:06",
    "channel": 1,
    "basketDetails": {
        "quote": false,
        "passengers": [
            {
                "lead": true,
                "passengerRph": 1,
                "title" : "Mr",
                "givenName" : "TBC",
                "familyName" : "TBC",
                "dateOfBirth" : "1970-01-01",
                "gender" : "Male",
                "type" : "ADULT",
                "email" : "tbc@gmail.com"
            }
        ],
        "items": [
            {
                "sortOrder": 1,
                "stockItemId": 4318,
                "identifier": 392839972,
                "encodedSearchRequest": "eyJzZWFyY2hUeXBlIjoiR0VORVJBTCIsImxhbmd1YWdlIjoiRU4iLCJjaGFubmVsIjo5LCJnZW9ncmFwaGljYWxJZCI6bnVsbCwiZ2VvZ3JhcGhpY0FyZWEiOm51bGwsInN1cHBsaWVyQ29udHJhY3RTdG9ja0l0ZW1JZCI6NDMxOCwiZnJvbSI6WzIwMjIsOSwxMF0sInRvIjpudWxsLCJwaWNrdXBUaW1lIjpudWxsLCJkcm9wT2ZmVGltZSI6bnVsbCwiZHVyYXRpb25zIjpbN10sImR1cmF0aW9uT2ZFeHRyYSI6bnVsbCwibWF0Y2hTdGFydERhdGUiOm51bGwsIm5vQWR1bHRzIjoyLCJub0NoaWxkcmVuIjpudWxsLCJub0luZmFudHMiOm51bGwsInBlcm1pdEFwaURldGFpbCI6ZmFsc2UsInN1cHBsaWVySWQiOm51bGwsImNhclNpemUiOm51bGwsImNhclR5cGUiOm51bGx9",
                "passengerRphs": [
                    1
                ],
                "totalPrice" :2238.19,
                "totalSupplements" : 0.0,
                "totalDiscount" : 0.0
            }
        ]
    }
}

This will return you the id of basket that has been created, if you are adding items to the basket one at a time you will use this id in subsequent requests to ensure that the purchases are all in the same basket, alternatively you can manage this process yourself and fir all the items you wish to purchase in one go.

It is worth noting that the creation of a basket does not do any checks on the content they are only done once a basket is priced, validated or converted into a booking

{
    "timeStamp": "2022-07-06T13:47:22",
    "success": true,
    "affectedIds": [
        39393
    ]
}

This message takes an accommodation id and returns associated extras, for a villa for instance it might return 'Pool Heating' or a 'Stair Gate'

{
  "timeStamp": "2022-11-08T14:29:00.889Z",
  "channel": 0,
  "currencyCode": "GBP",
  "language": "EN",
  "stockItemId": 7552,
  "stockType": "string",
  "dateValue": "2022-11-08",
  "duration": 7,
  "durationOfExtra": 1,
  "matchStartDate": true,
  "noAdults": 2,
  "useResortAssociations": true,
  "searchThirdPartySystems": true,
}

The response will of course be more products you can add to the basket using add to basket message detailed above

{
                                    Please add in a response
}