Search Product#

The following page describes how the Search Product information endpoint works. This endpoint is built to retrieve products that match the search criteria entered by the user.

There must be at least 1 valid search criteria entered as a field value (title/description), this is a mandatory input parameter. And the user can also filter the search by taxonomy, following the below structure:

Search query (field:value [ AND/OR field:value]

Search by a field (title/description) AND/OR Search by taxonomy

Search by taxonomy should be an exact match, more details about this below.

Output of the query should be a list of products that contain the search terms within the title/description AND/OR Taxonomy. If there are no element that match the criteria for the search query, then there should be NO results as a return. The list of products is ordered by Language: first products shown are the same as the Organization country of the account performing the request, then they are ordered alphabetically.

Taxonomy#

As part of this endpoint and search by taxonomy filter, when searching by taxonomy, we will query the catalogue on DB based on the slugs created for taxonomy. So when the user is searching by taxonomy, we will query the catalogue and show the results only belonging to the specific slugs used in the search.

How slug is defined

The current taxonomy is defined to have 3 different levels, although only 2 levels have been implemented so far.

Level 1 taxonomy e.g.: “Culture”, “Food & drink”, “Nature & outdoors”,… Level 2 e.g.: “Shows & events”, “Restaurants & bars”, “Land activities”,…

Taxonomy Slug is the combination of the fields: family + level1 + level2 (e.g.: activities-culture-shows-events)

Please note that family field is referring to the “Activities” taxonomy in this case.

For the search by taxonomy we will use slugs for the query, terms should be an exact match, e.g.:

Search Term

Slug Term

Output

activities-action-entertainment-land

activities-action-entertainment-land

All products that match the search criteria

activities-culture-tickets-passes

activities-culture-tickets-passes

All products that match the search criteria

Path

GET /api/consumer/products


Input parameters

Field

Mandatory

Type

Format

Description

Example

Accept-Language

N

String

ISO 639-1

Default value : en

en

Search

Y

String

field:value [ AND/OR field:value]

Search query. This will search any information based on products fields, supplierExternalId and taxonomy

Cannes by night

resultsPerPage

N

integer

N/A

number of result per page (default value : 100)

100

pageNumber

N

integer

N/A

number of page

3

sortingField

N

string

N/A

sorting field ( default value : title)

title

sortingOrder

N

string

asc, desc

sorting order

asc

externalClientId

N

string

255 alphanumeric characters maximum

Identifier that is appended to the Booking URL to allow Consumer Systems to track traveler bookings

ABCDEF

Output

Field

Type

Format

Description

Example

resultsPerPage

integer

N/A

number of result per page (default value : 0)

100

pageNumber

integer

N/A

number of page

3

totalResults

integer

N/A

number of product in the result

15

Items

object

N/A

list of product

N/A

Items/id

integer

N/A

id of the product

2259173

Items/externalId

string

N/A

external id of the product

e729d8fa-4885-4bf6-b1da-6260b7caaf7b

Items/title

string

N/A

title of the product

Fondation Maeght entrance tickets

Items/creationDate

date

DateTime

date of creation of the product

2022-05-09T12:20:53.483+00:00

Items/updateDate

date

DateTime

date of the last update of the product

2022-07-20T03:31:52.399+00:00

items/internalName

string

N/A

internal name of the product

Fondation Maeght entrance tickets

items/reference

string

N/A

reference of the product

5615_fondation

items/instantConfirmation

boolean

true, false

if the product has an instant confirmation of booking

TRUE

items/instantDelivery

boolean

true, false

TRUE

TRUE

items/availabilityType

string

START_TIME, OPENING_HOURS

availability type

contact

items/redemptionMethod

string

MANIFEST, DIGITAL,PRINT

manifest method

PRINT

items/subtitle

string

N/A

subtitle of the product

Fondation Maeght entrance tickets

items/short description

string

N/A

short description of the product

The Fondation Maeguerite et Aimé Maeght is one of the world's leading cultural institutions. Inaugurated on July 28th, 1964 by André Malraux, the foundation was born of the friendship of Aimé Maeght and his wife Marguerite with some of the most important artists of the 20th century

items/description

string

N/A

description of the product

<div><p><p>The Fondation Maeguerite et Aimé Maeght is one of the world's leading cultural institutions. Inaugurated on July 28th, 1964 by André Malraux, the foundation was born of the friendship of Aimé Maeght and his wife Marguerite with some of the most important artists of the 20th century.</p><p>The museum has one of the most important collections of paintings, sculptures, drawings and graphic works of modern and contemporary artists in Europe with more than 13,000 references: an exceptional collection of sculptures by Alberto Giacometti and works by Joan Miró, masterpieces by Pierre Bonnard, Marc Chagall, Alexander Calder, Georges Braque and many others.</p></p></div>

items/thumbnailImage

string

URL

URL of the thumbnail image for this product

http://static.apidae-tourisme.com/filestore/objets-touristiques/images/225/17/11538913.jpg

Items/bookingEngine

string

Restricted string from a list of booking engines

Booking engine that will be used to book the activity

HOLIBOB

items/bookingURL

string

URL

url to book the product

https://alentour.booking.holibob.tech/product/e729d8fa-4885-4bf6-b1da-6260b7caaf7b&externalClientId=ABCDEF

items/minPrice

double

N/A

price minimum for this product

16

items/maxPrice

double

N/A

price maximum for this product

16

items/priceCurrency

string

ISO 4217

currency to book the product

EUR

items/pricingUnit

string

PER_PERSON, PER_VEHICLE, GROUP, FAMILY, PER_EQUIPMENT, PACKAGE, PER_BOAT, NONE

unit for the price

NONE

items/minParticipants

integer

N/A

minimum number of person for this product

5

items/maxParticipants

integer

N/A

maximum number of person for this product

30

items/address

string

N/A

adress of the product

150 promenade des Anglais, Nice, France

items/placeId

integer

string

google id of the address

dswfef15dq

items/website

string

URL

website url of the product

https://www.fondation.com

items/geolocation

object

N/A

geolocation of the product

items/geolocation/latitude

float

decimal degrees format from -90 to 90

latitude

45.27986

items/geolocation/longitude

float

decimal degrees format from -180 to 180

longitude

6.813755

items/geolocation/geoHash

string

N/A

hash of the coordinate

ds5cdc84fe

items/duration

string

ISO 8601

duration of the product

PT30M

items/galleryImage

object

N/A

list of images

items/galleryImage/title

string

N/A

title of the image

fondation

items/galleryImage/url

string

URL

url of the image

https://images.holibob.tech/eyJrZXkiOiJwcm9kdWN0SW1hZ2VzLzMwYzBlMDZjLTgzZmYtNGRhZS04YmFhLTgwYmNhNDcxZjgxZCIsImVkaXRzIjp7InJlc2l6ZSI6eyJmaXQiOiJjb3ZlciIsIndpZHRoIjoxOTIwLCJoZWlnaHQiOjEwODB9fX0=

items/galleryImage/order

integer

N/A

order of appearance in the gallery

1

items/categories

object

N/A

list of categories of the product

items/categories/level

integer

N/A

level of the category

1

items/categories/code

string

N/A

code of the category

asbyj25dw

items/categories/name

string

N/A

name of the category

items/categories/description

string

N/A

description of the category

items/supplier

object

N/A

Object containing informations about the supplier

N/A

items/supplier/id

int

N/A

Supplier id

55648

items/supplier/name

string

N/A

Supplier name

Amazing tours

items/supplier/externalId

string

N/A

Supplier external id

d15247898

items/supplier/creationDate

date

datetime

Supplier  date of creation

2022-02-22T00:46:40.663Z

items/supplier/updateDate

date

datetime

Supplier last update date

2022-02-22T00:46:40.663Z

items/supplier/contact

object

N/A

Containing information about supplier points of contact

N/A

items/supplier/contact/website

string

url

Supplier website url

https://google.com

items/supplier/contact/email

string

N/A

Supplier mail of contact

supplier@email.com

items/supplier/contact/telephone

string

N/A

Supplier phone number

3.31E+11

items/supplier/contact/address

string

N/A

Supplier address

34 avenue du Mistral,  06200 Nice, France

items/supplier/countryCode

string

iso 3166-1 alpha-2

Supplier country code

FR

items/supplier/countryName

string

N/A

supplier country name

France

items/supplier/onlineBookable

boolean

true or false

Defines if the product is bookable online (true) or not (false)

TRUE

items/descriptors

array

N/A

array containing information about product descriptors

N/A

items/descriptors/type

string

string from a restricted list

type of descriptor. Can be can EXCLUDED, PROMOTED, etc

PROMOTED

items/descriptors/reason

string

string from a restricted list

reason of why the product type (PROMOTED, EXCLUDED), can be DEPRECATED, etc

PROMOTED

items/availableLanguages

array

N/A

Array displaying the languages supported by the product

[“en”,”es”, “fr”]

items/taxonomies

List

N/A

List of the taxonomies linked to this product
[
[
{

“id”: “activities-tours-by-theme”, “name”: “Tours by theme”, “level”: 1

}, {

“id”: “activities-tours-by-theme-walking-tours”, “name”: “Walking tours”, “level”: 2

}

], [

{

“id”: “activities-nature-outdoors”, “name”: “Nature & outdoors”, “level”: 1

}, {

“id”: “activities-nature-outdoors-land-activities”, “name”: “Land activities”, “level”: 2

}

]

]

items/taxonomies/Id

string

N/A

slug term of the taxonomy

activities-tours-by-theme

items/taxonomies/name

string

N/A

name of the taxonomy

Tours by theme

items/taxonomies/level

integer

N/A

level of the taxonomy

1

aiGenerated

Object

N/A

Object containing a list of domain generated by ai

{ “translation”: true}

aiGenerated/translation

boolean

N/A

Flag to indicate if the recommendation is AI generated or not for translation

true
Response Body
{
  "pageNumber": 0,
  "resultsPerPage": 0,
  "totalResults": 0,
  "items": [
  {
      "id": 2259173,
      "externalId": "e729d8fa-4885-4bf6-b1da-6260b7caaf7b",
      "title": "Fondation Maeght entrance tickets",
      "creationDate": "2022-05-09T12:20:53.483+00:00",
      "updateDate": "2022-07-20T03:31:52.399+00:00",
      "availabilityType": "OPENING_HOURS",
      "shortDescription": "<div><p><p>The Fondation Maeguerite et Aimé Maeght is one of the world&#39;s leading cultural institutions. Inaugurated on July 28th, 1964 by André Malraux, the foundation was born of the friendship of Aimé Maeght and his wife Marguerite with some of the most important artists of the 20th century.</p><p>The museum has one of the most important collections of paintings, sculptures, drawings and graphic works of modern and contemporary artists in Europe with more than 13,000 references: an exceptional collection of sculptures by Alberto Giacometti and works by Joan Miró, masterpieces by Pierre Bonnard, Marc Chagall, Alexander Calder, Georges Braque and many others.</p></p></div>",
      "description": "<div><p><p>The Fondation Maeguerite et Aimé Maeght is one of the world&#39;s leading cultural institutions. Inaugurated on July 28th, 1964 by André Malraux, the foundation was born of the friendship of Aimé Maeght and his wife Marguerite with some of the most important artists of the 20th century.</p><p>The museum has one of the most important collections of paintings, sculptures, drawings and graphic works of modern and contemporary artists in Europe with more than 13,000 references: an exceptional collection of sculptures by Alberto Giacometti and works by Joan Miró, masterpieces by Pierre Bonnard, Marc Chagall, Alexander Calder, Georges Braque and many others.</p></p></div>",
      "thumbnailImage": "0c273ac4-4ca6-47a4-92fe-dfea5aa9b9a2",
      "bookingEngine": "HOLIBOB",
      "bookingUrl": "https://alentour.booking.holibob.tech/product/e729d8fa-4885-4bf6-b1da-6260b7caaf7b",
      "minPrice": 16,
      "maxPrice": 16,
      "priceCurrency": "EUR",
      "pricingUnit": "NONE",
      "address": "Nice, France",
      "geoLocation": {
        "latitude": 43.7005544,
        "longitude": 7.1156865,
        "geoHash": "spv09gmqp"
      },
      "duration": "",
      "galleryImages": [
        {
          "url": "https://images.holibob.tech/eyJrZXkiOiJwcm9kdWN0SW1hZ2VzLzMwYzBlMDZjLTgzZmYtNGRhZS04YmFhLTgwYmNhNDcxZjgxZCIsImVkaXRzIjp7InJlc2l6ZSI6eyJmaXQiOiJjb3ZlciIsIndpZHRoIjoxOTIwLCJoZWlnaHQiOjEwODB9fX0=",
          "order": 0
        }
      ],
      "categories": [
        {
          "level": 1,
          "code": "fun_games"
        }
      ],
      "supplier": {
        "id": 2258545,
        "name": "Fondation Marguerite et Aimé Maeght",
        "externalId": "a39bbecb-d030-44fb-a45a-5e79aa21d1bb",
        "creationDate": "2022-05-08T03:33:34.075+00:00",
        "updateDate": "2022-07-20T03:31:09.171+00:00",
        "contact": {},
        "countryCode": "FR",
        "countryName": "France"
      },
      "onlineBookable": true,
      "descriptors": [
        {
          "type": "PROMOTED",
          "reason": "PROMOTED"
        }
      ],
      "availableLanguages": [
        "en",
        "es",
        "fr"
      ],
          "taxonomies": [
        [
          {
              "id": "activities-tours-by-theme",
              "name": "Tours by theme",
              "level": 1
          },
          {
              "id": "activities-tours-by-theme-walking-tours",
              "name": "Walking tours",
              "level": 2
          }
        ],
        [
          {
              "id": "activities-nature-outdoors",
              "name": "Nature & outdoors",
              "level": 1
          },
          {
              "id": "activities-nature-outdoors-land-activities",
              "name": "Land activities",
              "level": 2
          }
        ]
      ]
    }
  }
}

Status code

List of HTTP codes#

HTTP code

Code description

200

Successful search of products

400

Results per page can’t be negative or equals to zero

400

Offset can’t be negative or equals to zero

400

Invalid value for sorting field

400

Invalid value for sorting order

400

Search parameter must contain at least 1 valid criteria: . Valid operators are : ^ < > ~

401

Unauthorized

403

Forbidden

404

Non existing products

500

Internal server error