-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathopenapi.json
10329 lines (10329 loc) · 527 KB
/
openapi.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
{
"openapi": "3.0.2",
"info": {
"title": "Viator API Documentation & Specification - Affiliate Partners",
"description": "<style type='text/css'>\ncode { white-space: nowrap; }\na { font-weight: bold; }\n\nfigure {\n width: 100%;\n text-align: center;\n font-style: italic;\n font-size: smaller;\n text-indent: 0;\n border: thin silver solid;\n margin: 0.5em;\n padding: 0.5em;\n}\n\n</style>\n\n## Updates\n\n| Date | Description |\n|------|-------------|\n| 26 May 2022 | Added advice about review authenticity: [Key concepts - Review authenticity](#section/Key-concepts/Review-authenticity) |\n| 11 Feb 2022 | Added note about no-index policy to [/attraction](#operation/attraction), [/attraction/photos](#operation/attractionPhotos), [/attraction/reviews](#operation/attractionReviews) and [/search/attractions](#operation/searchAttractions) endpoints |\n| 16 Sep 2021 | Removed `topX` and modified options for `sortOrder` request parameters in [/attraction/reviews/](#operation/attractionReviews) endpoint |\n| 6 Sep 2021 | Modified available options for `sortOrder` request parameter in [/taxonomy/attractions](#operation/taxonomyAttractions) and [/search/attractions](#operation/searchAttractions) endpoints |\n| 3 March 2021 | Added `currencyCode` request parameter to [/attraction/products](#operation/attractionProducts) |\n| 19 Feb 2021 | Removed /support/terms and /support/faq endpoints |\n| 3 Feb 2021 | Added [Special offers and on-sale pricing](#section/Key-concepts/Special-offers-and-on-sale-pricing) section |\n| 9 June 2020 | Updated [Supported currencies](#section/Appendices/Supported-currency-codes) section and [/product](http://localhost:8080/#operation/product) endpoint description to reflect multiple currencies now being enabled for all accounts by default |\n| 2 June 2020 | Updated Postman collections and [Testing](#section/Testing) section |\n| 20 May 2020 | Updated Postman collection |\n| 19 May 2020 | Recompiled with latest version of ReDoc (0.9.8) |\n| 22 Apr 2020 | Revised list of available languages |\n| 21 Apr 2020 | Regenerated all endpoint examples |\n| 20 Apr 2020 | Updated Overview section to be more specific to the Content Affiliate partner type |\n| 10 Mar 2020 | Created new [Overview](#section/Overview) section \n\n# Overview\n\nThe API exposes a variety of services that allow the retrieval of all product details, such as descriptions, pricing, terms and conditions, photos and reviews. This data can either be ingested periodically and managed on your local system, or calls can be made in real time to retrieve content in response to your users' activity on your systems.\n\nThe API provides product content and availability functionality, along with various utility services to map between yours and Viator's data taxonomy.\n\n## Who is the API for?\n\nThe Viator Partner API is designed for use by organizations and individuals partnered with Viator as a Viator Branded Affiliate (VBA).\n\n### Viator Branded Affiliates (VBAs)\n\nVBAs have full access to the areas of the API relating to content, but sales of Viator products must be carried out on the Viator site itself; therefore, access to the booking or transactional endpoints necessary to operate as the merchant of record (i.e., merchant partners) is restricted. \n\nWhen a customer wishes to book a product from a VBA partner's site, they are instead redirected to [viator.com](https://viator.com) in order to complete the purchase; whereas, merchant partners are able to process and manage bookings through the Viator API itself, allowing their customers to book products without leaving the partner's site.\n\nViator affiliates instead generate unique URLs that redirect their users to the Viator site, resulting in a cookie being set such that all transactions will accrue a commission for that partner until the cookie expires.\n\nPurchases of products originating from the VBAs site are recorded and a commission on these sales is paid periodically.\n\n## Uses of the Viator Partner API\n\nThe Viator Partner API is used to carry out the following tasks:\n\n### Product search and ingestion\n\nPartners can use the product search endpoints to retrieve lists of products from Viator’s inventory relevant to their business. The available search criteria include:\n\n- The location (destination) in which the product operates\n- Whether the product is associated with a well-known tourist attraction; e.g., Empire State Building\n- The type of product (known as its category and/or subcategory)\n- The time period during which the product operates \n- Words or phrases that occur in a product's description via a free-text search\n\nPartners who prefer to download product details periodically (instead of performing all operations in real time in response to user behavior) do so by using the product search endpoints to compile a list of products that they wish to sell on their site. They then download comprehensive product details for each via the /product endpoint.\n\n#### Product search endpoints:\n\n| Endpoint | Use |\n|-|-|\n| [/search/products](#operation/searchProducts) | Allows searching for products according to: destination / location, relationship to a known tourist attraction; category and/or subcategory; date of operation |\n| [/search/products/codes](#operation/searchProductsCodes) | Retrieves product details for products that match a list of product codes (unique identifiers for the product) |\n| [/search/freetext](#operation/searchFreetext) | Retrieves product details for products that include the search terms in the product's description and details. |\n| [/available/products](#operation/availableProducts) | Retrieves products that are identified by specific product codes, operate during a specified day range and accept a certain number of adult travelers |\n\n#### Product information endpoints:\n\nAll information about a product that must be communicated to customers prior to purchase is available via [/product](#operation/product) and its auxiliary endpoints. This content is generally used to construct product display pages and for performing local searches.\n\nImportant information about a product includes:\n\n- Product and supplier names\n- Geographic location\n- Product description\n- Category and subcategory\n- Photos (from both users and the supplier)\n- User reviews and ratings\n- Product options (variants of the tour/activity, such as starting times, passenger mix options, and inclusions/add-ons, including basic pricing information for each)\n- Which age ranges can participate\n- Booking details\n- Terms and conditions\n- Basic pricing\n- Logistics\n + Inclusions (e.g., provided meals)\n + Exclusions (e.g., entrance fees to visited attractions)\n + Health restrictions and accessibility\n + Departure times\n + Passenger pick-up\n + Duration\n + Tour routes\n\n### Auxiliary services\n\nTaxonomical data sets are required to interact meaningfully with the Viator Partner API; for example, mappings from destination (location of operation) to their respective identification codes. This information may occasionally change or be added to. Consequently, the API includes endpoints that return the most up-to-date versions of this information.\n\n#### Taxonomy endpoints\n\n| Endpoint | Use |\n|-|-|\n| [/taxonomy/destinations](#operation/taxonomyDestinations) | Retrieves a list of destination names, types and unique identifiers to be used when interacting with the Viator Partner API |\n| [/taxonomy/categories](#operation/taxonomyCategories) | Retrieves a list of product categories for a destination that can be used as a means of filtering when searching for products using the [/search/products](#operation/searchProducts) endpoint |\n| [/taxonomy/attractions](#operation/taxonomyAttractions) | Retrieves a list of tourist attractions (e.g., the Eiffel Tower or Empire State Building) and their associated identification codes to be used as a means of searching for available products; for example, in the [/search/products](#operation/searchProducts) service |\n| [/booking/hotels](#operation/bookingHotels) | Retrieves a list of hotels, including names and geographic locations, to be used when making booking requests |\n\n#### Utility endpoints\n\nThe following services are available that provide basic utility services to support the use of the API:\n\n| Endpoint | Use |\n|-|-|\n| [/util/ip2country](#operation/utilIp2country) | Returns the country-code for the country in which the IP is located. |\n| [/util/sitedetails](#operation/utilSitedetails) | Returns the site settings for your organization|\n| [/util/countrymap](#operation/countrymap) | Returns a dictionary mapping coutry-codes to their natural-language names and international dialling prefixes|\n| [/util/guid](#operation/utilGuid) | Generates and returns a GUID for general use |\n| [/util/siteBinaryData](#operation/utilSiteBinaryData) | Returns custom information for a partner, such as a logo, favicon or quick links |\n\n### Attraction services\n\nViator has a large database of attractions and traveler recommendations. These are associated with a destination and have their own photos and reviews as well as associated products that consumers can purchase.\n\nAn example Attraction is the Eiffel Tower. Viator sells a number of products that take customers to the tower and these are associated for cross selling purposes.\n\nRecommendations are authored by Viator and our customers and include recommended itineraries for visiting a city or favorite restaurants, etc.\n\nThe attraction endpoints can be used to get the attractions or recommendation lists, details and associated products, photos and reviews.\n\nAttractions and recommendations have a unique ID called the `seoId`. This is the unique identifier for an attraction and is available in the following services.\n\n| Endpoint | Use |\n|-|-|\n| [/search/attractions](#operation/searchAttractions) | Returns a list of attractions associated with the given destination |\n| [/attraction](#operation/attraction) | Returns the details of an attraction. |\n| [/attraction/reviews](#operation/attractionReviews) | Returns reviews related to an attraction. These reviews might be associated indirectly through the related products.|\n| [/attraction/photos](#operation/attractionPhotos) | Returns photos that are related to an attraction (these may be associated indirectly if they are photos of products related to the attraction) |\n\n### Customer support services\n\nThe links to the terms and conditions, FAQ and customer care page is available to VBA partners.\n\nThe following services are available:\n\n| Endpoint | Use |\n|-|-|\n| [/support/terms](#operation/supportTerms) | Returns the URL for the terms and conditions. |\n| [/support/FAQ](#operation/supportFAQ) | Returns the URL to the FAQ page that the partner can link to within their app / website |\n| [/service/support/customercare](#operation/supportCustomercare) | Returns the URL to the customer care page that the partner can link to within their app / website. |\n\n---\n\n# Authentication\n\n## API key\n\nAccess to the API is managed using an **API key** that must be included as a **header parameter** to every call made to all API endpoints described in this document.\n\n| Header parameter name | Example value |\n|-----------------------|---------------|\n| exp-api-key | bcac8986-4c33-4fa0-ad3f-75409487026c |\n\nIf you do not know the API key for your organization, please contact your business development account manager for these details.\n\nWhen using this type of key, you must also include in your request the language you wish your response localized to via the `Accept-Language` header parameter. See [Accept-Language header](#section/Appendices/Accept-Language-header) for available language codes. Please note that, at present, only the language configured for your organization's point of sale will be available.\n\n## Legacy API key\n\nPreviously, authenticating to this API was accomplished by passing an API-key as a **query parameter** appended to the URI for each call; e.g.:\n\n```html\nGET https://viatorapi.viator.com/service/taxonomy/destinations?apiKey=xxxxxxxxxxxxxxxxxx\n```\n\nWhile this method of authentication remains available for backwards-compatibility, if you are still using this method for authentication, we recommend you contact your business development account manager to ask for a new-style API key as soon as possible.\n\n# Key concepts\n\n## Content ingestion and caching strategy\n\nMuch of the information you will need to retrieve from the Viator API – such as the taxonomy, product lists and product details – do not change frequently.\n\nTherefore, we recommend implementing a caching strategy in order to eliminate unnecessary traffic to Viator’s servers and improve the operation of your site. \n\nThis section discusses the different strategies for retrieving and caching Viator’s product catalogue.\n\nYou will need to decide on how you will retrieve and manage content from Viator’s product catalogue. The two main options are as follows:\n\n### 1. API response caching\n\n*Partners retrieve content as-needed and cache responses on a service-by-service basis*\n\nIf you do not need to store product details locally, we recommend performing caching of on a service-by-service basis; i.e., storing the entire response and applying a time-to-live (TTL) of less than 24 hours.\n\n#### Benefits of API response caching\n\n* All the benefits of caching with minimal overhead\n* Minimal risk of serving stale or invalid data cached on the partner's side\n* No need to download data about products that are not selling\n* A smaller volume of local data improves cache hit performance\n* Fewer requests made of Viator's systems\n* Avoids rate limitations\n* Closer adherence to best practices\n* Removes need to manage a complex data structure locally\n\n#### Service endpoints to cache\n\nCaching should only be applied to services that yield infrequently changing data; i.e.:\n\n* [/taxonomy/destinations](](#operation/taxonomyDestinations)\n* [/taxonomy/categories](#operation/taxonomyCategories)\n* [/taxonomy/attractions](#operation/taxonomyAttractions)\n* [/search/products](#operation/searchProducts)\n* [/search/products/codes](#operation/searchProductsCodes)\n* [/search/freetext](#operation/searchFreetext)\n* [/product](#operation/product)\n* [/product/reviews](#operation/productReviews)\n* [/product/photos](#operation/productPhotos)\n* [/available/products](#operation/availableProducts)\n\n**Note**: These services should be considered cacheable even though some are POST and no Cache-Control HTTP header is included in their response.\n\n### 2. Periodic content ingestion\n\n*Partners download either the full product catalogue or a subset of the catalogue at regular intervals based on destination, linked attraction, or product category filters.*\n\n#### Who should use periodic ingestion\nThis approach may be preferable for partners whose requirements include:\n* **System agnosticism/data centralization** – i.e., partners who are simultaneously selling products from vendors other than Viator, have existing product databases or are likely to want to maintain a central product catalogue with a unified taxonomy / data structure\n* **Enhanced search capability** – i.e., the ability to apply different categorization rules, filters, exclusions or search optimizations to the product catalogue; e.g., grouping or filtering products according to criteria other than those supported directly by the Viator API (destination, attraction-link or category)\n\n#### Frequency of content ingestion\nWe recommend that you perform an ingestion of the product catalogue once every 24 hours.\n\n#### How to retrieve product codes\n\nMake a call to one of the product search services:\n\n* [/search/products](#operation/searchProducts) – to search by `destId` (destination), `catId` (category), `subCatId` (subcategory) or `seoId` (attraction)\n* [/search/freetext](#operation/searchFreetext) – free-text search across all identifying fields \n\n#### How to retrieve all products in the catalogue\n\nTo retrieve all products from the Viator catalogue:\n\n* Retrieve all available destination identifiers (`destId`) from the [/taxonomy/destinations](#operation/taxonomyDestinations) service\n* Iterate through the complete list of `destId`s you retrieved in the previous step, and call [/search/products](#operation/searchProducts) for each `destId`\n\n**Note**: As some products operate in multiple destinations, the same product code may be returned for a range of different destinations. Therefore, make sure your list of product codes only contains one copy of each code.\n\nYou may then iterate through this list of product codes to retrieve any other product details necessary in order to properly populate your local database with the information you require.\n\n#### Retrieving a subsection of the product catalogue\n\nYou may wish to retrieve only some of the products available in the Viator catalogue; for example, if your organization is only interested in selling products that operate locally.\n\nYour top level search using [/search/products](#operation/searchProducts) is restricted to one of the three main categorization methods for products; i.e., destination, category/subcategory, or attraction-link; however, you may employ your own methods to filter the selection of products based on any attribute in the product data structure.\n\n#### Dealing with pagination using `totalCount` and `topX`\n\nDue to the large number of results that can be returned by the [/search/products](#operation/searchProducts) service, the request might exceed the 30-second time-out limitation. Therefore, you will need to make multiple requests to this service including pagination information in order to retrieve all products that match your search criteria.\n\nThis is accomplished by sequentially requesting successive segments of the results using the `topX` request parameter together with the `totalCount` response field; i.e.:\n\n* For your first request, specify a `topX` of `\"1-100\"`\n - **Note**: this range is *inclusive*; i.e., `\"topX\": 1-100\"` will yield the first 100 records \n* The first response will indicate the total number of records available through the value of the `totalCount` field in the response object; e.g.: ```\"totalCount\": 13843```\n* For each subsequent request, specify the next logical 'chunk' of data via the `topX` parameter of the request; e.g.:\n - \"topX\": \"1-100\"\n - \"topX\": \"101-200\"\n - ...\n - \"topX\": \"13801-13843\"\n\n#### Rate limiting\n\nDue to the heavy load that pre-caching can place on Viator's servers and the downstream servers we connect to, we apply a rate limit of 150 requests per rolling 10 second time window.\n\nRequest rates exceeding this limit will result in a **HTTP 429 (Too Many Requests)** status code being returned.\n\n**Note**: The rate is calculated over a rolling 10-second time window.\n\n* In order to avoid running-up against rate limits:\n - insert a delay of 2s if you receive a HTTP 429 status code\n - do not run this as a multi-threaded process\n\n## Categorization of content\n\nThe products available in Viator’s catalogue are mainly categorized according to:\n\n1. **Destination**: every product in the Viator catalogue is categorized according to the destination/locale in which it operates. There are three kinds of destination:\n<table>\n <thead>\n <th>Destination type</th>\n <th>Meaning</th>\n </thead>\n <tbody>\n <tr>\n <td>“COUNTRY”</td>\n <td>A country; e.g., “Australia”, “Japan”, “USA”</td>\n </tr>\n <tr>\n <td>\"REGION\"</td>\n <td>A geographical region or state; e.g., “South Australia”, “French Riviera”, “Punjab”</td>\n </tr>\n <tr>\n <td>\"CITY\"</td>\n <td>A city within a state; e.g., “Townsville”, “Osaka”, “Singapore”</td>\n </tr>\n </tbody>\n</table>\n<table>\n <thead>\n <tr>\n <th><code>destinationName</code></th>\n <th><code>destId</code></th>\n <th><code>destinationType</code></th>\n </tr>\n </thead>\n <tbody>\n <tr>\n <td>USA</td>\n <td>77</td>\n <td>COUNTRY</td>\n </tr>\n <tr>\n <td>Wisconsin</td>\n <td>22231</td>\n <td>REGION</td>\n </tr>\n <tr>\n <td>Madison</td>\n <td>24146</td>\n <td>CITY</td>\n </tr>\n <tr>\n <td>France</td>\n <td>51</td>\n <td>COUNTRY</td>\n </tr>\n <tr>\n <td>Brittany</td>\n <td>21942</td>\n <td>REGION</td>\n </tr>\n <tr>\n <td>Rennes</td>\n <td>21943</td>\n <td>CITY</td>\n </tr>\n </tbody>\n</table>\n\n1. **Category and subcategory**: the products in the Viator catalogue are grouped according to the kind of activity they entail and may be subcategorized further to provide greater specificity; for example:\n<table>\n <thead>\n <tr>\n <th>Category</th>\n <th>Subcategories</th>\n </tr>\n </thead>\n <tbody>\n <tr>\n <td rowspan=3>Air, Helicopter & Balloon Tours</td>\n <td>Air Tours</td>\n </tr>\n <tr>\n <td>Helicopter Tours</td>\n </tr>\n <tr>\n <td>Balloon Rides</td>\n </tr>\n <tr>\n <td rowspan=2>Weddings & Honeymoons</td>\n <td>Wedding Packages</td>\n </tr>\n <tr>\n <td>Honeymoon Packages</td>\n </tr>\n </tbody>\n</table>\n1. **Attraction link** (i.e., association to a particular \"point of interest\"); e.g.:\n<table>\n <thead>\n <tr>\n <th>Attraction</th>\n <th>`seoId`</th>\n <tr>\n </thead>\n <tbody>\n <tr>\n <td>Bellagio Fountains</td>\n <td>1243</td>\n </tr>\n <tr>\n <td>Black Canyon</td>\n <td>4437</td>\n </tr>\n <tr>\n <td>Epcot Centre</td>\n <td>1141</td>\n </tr>\n </tbody>\n</table>\n\n## Localization and translation\n\n### Foreign language products\n\nThe products available through the Viator API have been created in a variety of languages, often by the suppliers of those products themselves. \n\nAlthough the majority of these have been created in English, many have been created in other languages. For example, a tour that operates in Paris might have been created in French.\n\nViator provides translation services to localize product descriptions to the language of the locale in which they are being presented. In this way, products with descriptions – for example, in French – can be displayed in English on English-language websites. Conversely, products with English-language-descriptions can be displayed in French on French-language websites.\n\n* **Note**: product descriptions are translated into the language specified in the `Locale` header parameter in the request to each endpoint.\n\n### Human and machine translation\n\nSome products have been translated by actual humans – 'human translated' – while others have been automatically translated using Google Translate – 'machine translated'.\n\nThe type of translation that has been applied to a product (if any) is indicated by its `translationLevel`, a numeric specifer with meanings as follows:\n\n| `translationLevel` | Meaning |\n|-----------------|---------|\n| `0` | The product was created by the supplier in the language you specifed using the `Locale` header parameter in the request; i.e., the natural-language text in this response has not been translated |\n| `80` | All product information has been <u>machine translated</u> |\n| `90` or `100` | All product information has been <u>human translated</u> |\n\nTherefore, any product with a non-zero `translationLevel` has been translated.\n\nThe `translationLevel` field is returned in the response objects from the following services:\n\n* [/search/products](#operation/searchProducts)\n* [/search/products/codes](#operation/searchProductsCodes)\n* [/search/freetext](#operation/searchFreetext)\n* [/product](#operation/product)\n* [/available/products](#operation/availableProducts)\n\nWhen performing a product search using any of these services, you will receive - by default - products with a `translationLevel` of:\n\n* `0` (products that are in the language you specified in `Locale`), and\n* `90` or `100` (products that have been <u>fully human translated</u>)\n\n### Accessing machine-translated products\n\nIf your implementation can support the large number of products available that are machine translated, you can.\n\nHowever, access to the considerable volume of machine-translated products (level `80`), is <u>not granted by default</u>, as there may be quality issues regarding automatically-translated text.\n\nTo access machine-translated products, you will need to request access from your business development account manager.\n\n## How to report a product issue\n\nOccasionally, a product schema in the Viator database will contain incorrect or invalid information. Usually, this occurs due to a mistake made by the supplier of the product when creating the product or updating its details.\n\nNonetheless, it's in all our best interests for product information to be accurate and up-to-date; therefore, if you discover a problem with a product, we would greatly appreciate it if you could report the error through our [product issue reporting form](https://www.tfaforms.com/433240).\n\n### How to use the product issue reporting form\n\n1. Navigate to the [product issue reporting page](https://www.tfaforms.com/433240)\n2. Fill in the **Reporter**, **Supplier ID**, **Product Code** and **Booking ID** fields:\n\n| Field | How to fill it in | Example |\n|-------|-------------------|---------|\n| Reporter | Enter your email address for tracking or correspondence | `you@emailserver.com` |\n| Supplier ID | Enter the value returned in the `supplierCode` field by the [/product](#operation/product) service for the product in question. | `3072` |\n| Product Code | Enter the value returned in the `code` field by the [/product](#operation/product) service for the product in question. | `3072LASALL` |\n| Booking ID | Leave this field blank | |\n\n3. In the **Reason** box below, choose **Content** by clicking on its radio selector. A list of categories will appear, with meanings as follows:\n\n| Category | Included issues | \n|----------|---------|\n| Additional Info | clauses in the `additionalInfo` array in the response from [/product](#operation/product); e.g., departure time or hotel pick-up information |\n| Availability & Blockouts | N/A |\n| Booking Details | N/A |\n| Highlights | `highlights` array items in the response from [/product](#operation/product) |\n| Inclusions / Exclusions | `inclusions` or `exclusions` array items in the response from [/product](#operation/product) |\n| Images | `productPhotos` and `userPhotos` returned by [/product](#operation/product) or [/product/photos](#operation/productPhotos) |\n| Product Title | `title` in the response from [/product](#operation/product), [/search/products](#operation/searchProducts), [/search/products/codes](#operation/searchProductsCodes) and [/search/products/freetext](#operation/searchProductsFreetext) |\n| Product Descriptions | `description` and `shortDescription` in the response from [/product](#operation/product)|\n| SAPI | N/A |\n| Tour Options & Pricing | pricing issues; e.g. when the value of `merchantNetPrice` is `0`; or, if `merchantNetPrice` > `price` |\n| Taxonomy | <ul><li>destination issues in response from [/taxonomy/destination](#operation/taxonomyDestination)</li><li>category / subcategory issues in response from [/taxonomy/categories](#operation/taxonomyCategories)</li></ul> |\n| Translation Incorrect | mistakes in any natural-language field in the response from any service where `translationLevel` is non-zero |\n| TVRM | N/A |\n| VUC incorrect | N/A |\n\n4. After selecting the category of issue from the options shown, fill-in the **Description / Action Required** box with a good, clear description of the problem and any specific additional actions you would like us to take\n5. Click **Submit** to send the report\n\n<figure>\n <img src=\"/partner-api/resources/affiliate/technical/img/tae-report-a-product-issue.jpg\" alt=\"Tripadvisor experiences report a product form\"/>\n <figcaption>Example Report a Product Issue form</figcaption>\n</figure>\n\nOnce your report has been submitted, a member of our Supplier Support Team will contact the supplier of the product in question to resolve any problems with their listing.\n\n## Special offers and on-sale pricing\n\nSuppliers have the option of setting special pricing deals for their products. When a product is 'on sale'; i.e., has a temporarily lowered price, it will be reflected in the product content response, as follows:\n\n| Field name | Standard pricing | Special offer / on-sale pricing |\n|------------|----------------|-------------------------|\n| `specialOfferAvailable` | `false` | `true` |\n| `specialOffer` | `\"\"` (empty string) | e.g.: `\"Book by February 28 to save 10%\"` |\n| `rrp` | `0.0` | pre-discount price |\n| `rrpFormatted` | `\"\"` (empty string) | currency-formatted pre-discount price |\n| `onSale` | `false` | `true` |\n| `price` | standard price | special offer price |\n| `priceFormatted` | currency-formatted **standard price** | currency-formatted **special-offer price** |\n| `priceFrom` (in `tourgrades`) | standard price | special-offer price |\n| `priceFromFormatted` (in `tourgrades`) | currency-formatted **standard price** | currency-formatted **special-offer price** |\n| `savingAmount` | `0.0` | (`rrp` - `priceFrom`) |\n| `savingAmountFormated` | `\"\"` (empty string) | (`rrp` - `priceFrom`) currency formatted |\n\nYou can use this information to highlight which products are on special and provide details to the user about the special offer.\n\n\n## Making a booking\n\nAffiliate partners do not manage any aspect of the booking process. Instead, users on the affiliate's site click the link to the tour, which is provided in the `webURL` field in the product details in the responses from:\n\n- [/search/products](#operation/searchProducts)\n- [/search/products/codes](#operation/searchProductsCodes)\n- [/search/freetext](#operation/searchFreetext)\n- [/product](#operation/products)\n\n## Review authenticity\n\n### Viator performs checks on reviews\n\nYou can only submit a review or rating of an experience to Viator if you were the person who made the booking through Viator. Before publication, each review goes through an automated tracking system, which collects information for each of the following criteria: who, what, how, and when. \n\nIf the system detects something that contradicts our publication criteria, the review is not published. When the system detects a problem with a review, it may be automatically rejected, sent to the reviewer for validation, or manually reviewed by our team of content specialists who work 24/7 to maintain the quality of the reviews on our site. In some cases, we will also send Viator customers an email asking them to validate their review before it is published. <br /><br />All Viator customers need to do is click on the link provided in the email. \n\nAfter publication, our team checks each review reported to it as not meeting our publication criteria. Tripadvisor reviews that appear on the Viator site are subject to the same checks and moderation processes as set out above. It is not necessary to have booked an experience through Viator (or Tripadvisor) to submit a review of an experience to the Tripadvisor site.\n\n\n# Testing\n\n## Postman collection for testing\n\n<PullRight>\nTo facilitate your testing of the APIs functionality, please use the following collection, which can be loaded into the [Postman](https://www.getpostman.com/) API development environment via its **import** function.\n</PullRight>\n\n- [Viator affiliate partner API Postman collection](/partner-api/resources/affiliate/technical/postman/viator-content-partner-api.postman_collection.json)\n\n### Setting up API-key authentication in Postman\n\nBefore you start using the linked Postman collection for testing, you will need to set up the authorization method you wish to use. This can be either the new method (the `exp-api-key` <u>header</u> parameter) or, the legacy method (the `apiKey` <u>query</u> parameter).\n\nWhile both methods remain available, we strongly recommend that you use the new method, as it:\n\n1. Provides access to all languages available for your organization with a single API-key as opposed to one API-key per language\n2. Allows access to the new [booking cancellation endpoints](#section/Common-workflows-and-data-validation/Cancellation-API-workflow), as well as all newly-created endpoints in future\n \nPlease speak to your account manager if you are still using the legacy apiKey and would like to switch to our new authentication mechanism.\n\n#### How to set up the new exp-api-key header parameter\n\n1. Select **Edit** from the collection menu:\n\n\n\n2. Set the following values:\n\n* **Key**: `exp-api-key`\n* **Value**: Your organization's single exp-api-key, which will have an identical format to that shown in the image below\n* **Add to**: Header\n\n\n\n3. Click **Update**\n\n#### How to set up the legacy apiKey query parameter\n\n1. Select **Edit** from the collection menu:\n\n\n\n2. Set the following values:\n\n* **Key**: `apiKey`\n* **Value**: One of your organization's legacy apiKeys, which will have an identical format to that shown in the image below\n* **Add to**: Query Params\n\n\n\n3. Click **Update**\n\n# Appendices\n\n## Accept-Language header\n\nThe `Accept-Language` header parameter controls which language the natural language fields in the response from each endpoint will be translated into.\n\nNote that you can only specify languages that have been configured for your API-key. Therefore, if you wish to access additional languages, you will need to contact your business development account manager.\n\n| Language | Accept-Language parameter value |\n|----------|-------|\n| English | `en`, `en-US` |\n| Danish | `da`, `da-DK` |\n| Dutch | `nl`, `nl-NL` |\n| Norwegian | `no`, `no-NO` |\n| Spanish | `es`, `es-ES` |\n| Swedish | `sv`, `sv-SE` |\n| French | `fr`, `fr-FR` |\n| Italian | `it`, `it-IT` |\n| German | `de`, `de-DE` |\n| Portuguese | `pt`, `pt-PT` |\n| Japanese | `ja`, `ja-JP` |\n\n## Standard JSON fields\n\nEvery service returns a standard set of JSON fields at the end of the JSON response, which indicates if it was processed successfully by the API.\n\nIn addition to the success flag, you will also need to check the `errorMessage` values for the status of the response. Success: `true` and `errorType` / `errorMessage` `null` indicates that there were no errors.\n\n### Example JSON - successful:\n\n```javascript\n{\n \"data\": [],\n \"vmid\": \"321001\",\n \"errorMessage\": null,\n \"errorType\": null,\n \"dateStamp\": \"2013-03-06T19:45:10+0000\",\n \"errorReference\": null,\n \"errorMessageText\": null,\n \"success\": true,\n \"totalCount\": 114,\n \"errorName\": null\n}\n```\n\n### Example JSON - unsuccessful:\n\n```javascript\n{\n \"errorReference\": \"~5793740141815885188840666\",\n \"data\": null,\n \"dateStamp\": \"2013-09-09T11:29:48+0000\",\n \"errorType\": \"EXCEPTION\",\n \"errorMessage\": [\"* Additional questions missing\\n\"],\n \"errorName\": \"ValidationException\",\n \"success\": false,\n \"totalCount\": 1,\n \"vmid\": \"221001\",\n \"errorMessageText\": [\"* Additional questions missing\" ]\n}\n```\n\n| Element | Type | Comments | To be viewed by customer | Required |\n|---------|------|----------|:------------------------:|:--------:|\n| `vmid` | varchar | The server id that processed the service | ❌ | ✅ |\n| `errorMessage` | varchar | The error message in HTML | ❌ | ✅ |\n| `errorType` | varchar | Type of error: EXCEPTION | ❌ | ✅ |\n| `dateStamp` | datetime | timestamp of the response | ❌ | ✅ |\n| `errorReference` | varchar | The error reference is logged for future reference | ❌ | ✅ |\n| `errorMessageText` | varchar | The textual version of the error message | ✅<br /> (if an error has occurred) | ✅ |\n| `success` | boolean | <ul><li>`true` if the API request was successful with no errors</li><li>`false` if an error was encountered</li></ul> | ❌ | ✅ |\n| `totalCount` | smallint | The number of results returned (minimum = `1`) | ✅<br /> (if displaying the number of results found in a search etc.) | ✅ |\n| `errorName` | varchar | The name of the error type | ❌ | ✅ |\n\n## Country codes\n| Country code | Country |\n|--------------|---------|\n| AF | Afghanistan |\n| AL | Albania |\n| DZ | Algeria |\n| AS | American Samoa |\n| AD | Andorra |\n| AO | Angola |\n| AI | Anguilla |\n| AQ | Antarctica |\n| AG | Antigua and Barbuda |\n| AR | Argentina |\n| AM | Armenia |\n| AW | Aruba |\n| AU | Australia |\n| AT | Austria |\n| AZ | Azerbaijan |\n| BS | Bahamas |\n| BH | Bahrain |\n| BD | Bangladesh |\n| BB | Barbados |\n| BY | Belarus |\n| BE | Belgium |\n| BZ | Belize |\n| BJ | Benin |\n| BM | Bermuda |\n| BT | Bhutan |\n| BO | Bolivia |\n| BA | Bosnia Herzegovina |\n| BW | Botswana |\n| BR | Brazil |\n| BN | Brunei |\n| BG | Bulgaria |\n| BF | Burkina Faso |\n| BI | Burundi |\n| KH | Cambodia |\n| CM | Cameroon |\n| CA | Canada |\n| CV | Cape Verde |\n| KY | Cayman Islands |\n| CF | Central Africa |\n| TD | Chad |\n| CL | Chile |\n| CN | China |\n| CX | Christmas Island |\n| CC | Cocos (Keeling) Islands |\n| CO | Colombia |\n| KM | Comoros |\n| CK | Cook Islands |\n| CR | Costa Rica |\n| CI | Cote D'Ivoire |\n| HR | Croatia |\n| CY | Cyprus |\n| CZ | Czech Republic |\n| DK | Denmark |\n| DJ | Djibouti |\n| DM | Dominica |\n| DO | Dominican Republic |\n| EC | Ecuador |\n| EG | Egypt |\n| SV | El Salvador |\n| GQ | Equatorial Guinea |\n| ER | Eritrea |\n| EE | Estonia |\n| ET | Ethiopia |\n| FK | Falkland Island |\n| FO | Faroe Islands |\n| FJ | Fiji |\n| FI | Finland |\n| FR | France |\n| GF | French Guiana |\n| PF | French Polynesia |\n| GA | Gabon |\n| GM | Gambia |\n| GE | Georgia |\n| DE | Germany |\n| GH | Ghana |\n| GI | Gibraltar |\n| GR | Greece |\n| GL | Greenland |\n| GD | Grenada |\n| GP | Guadeloupe |\n| GU | Guam |\n| GT | Guatemala |\n| GN | Guinea |\n| GW | Guinea Bissau |\n| GY | Guyana |\n| HT | Haiti |\n| HN | Honduras |\n| HK | Hong Kong |\n| HU | Hungary |\n| IS | Iceland |\n| IN | India |\n| ID | Indonesia |\n| IQ | Iraq |\n| IE | Ireland |\n| IL | Israel |\n| IT | Italy |\n| JM | Jamaica |\n| JP | Japan |\n| JO | Jordan |\n| KZ | Kazakhstan |\n| KE | Kenya |\n| KI | Kiribati |\n| KW | Kuwait |\n| KG | Kyrgyzstan |\n| LA | Lao People's Democratic Republic |\n| LV | Latvia |\n| LB | Lebanon |\n| LS | Lesotho |\n| LR | Liberia |\n| LY | Libyan Arab Jamahiriya |\n| LI | Liechtenstein |\n| LT | Lithuania |\n| LU | Luxembourg |\n| MO | Macau |\n| MK | Macedonia |\n| MG | Madagascar |\n| MW | Malawi |\n| MY | Malaysia |\n| MV | Maldives |\n| ML | Mali |\n| MT | Malta |\n| MQ | Martinique |\n| MR | Mauritania |\n| MU | Mauritius |\n| YT | Mayotte |\n| MX | Mexico |\n| FM | Micronesia |\n| MD | Moldova |\n| MC | Monaco |\n| MN | Mongolia |\n| MS | Monserrat |\n| MA | Morocco |\n| MZ | Mozambique |\n| NA | Namibia |\n| NR | Nauru |\n| NP | Nepal |\n| NL | Netherlands |\n| AN | Netherlands Antilles |\n| KN | Nevis- St Kitts |\n| NC | New Caledonia |\n| NZ | New Zealand |\n| NI | Nicaragua |\n| NE | Niger |\n| NG | Nigeria |\n| NU | Niue |\n| NF | Norfolk Island |\n| KP | North Korea |\n| MP | Northern Mariana Islands |\n| NO | Norway |\n| OM | Oman |\n| PK | Pakistan |\n| PW | Palau |\n| PS | Palestinian Territory, Occupied |\n| PA | Panama |\n| PG | Papua New Guinea |\n| PY | Paraguay |\n| PE | Peru |\n| PH | Philippines |\n| PN | Pitcairn |\n| PL | Poland |\n| PT | Portugal |\n| PR | Puerto Rico |\n| QA | Qatar |\n| RE | Reunion |\n| RO | Romania |\n| RU | Russian Federation |\n| RW | Rwanda |\n| SH | Saint Helena |\n| LC | Saint Lucia |\n| SM | San Marino |\n| ST | Sao Tome and Principe |\n| SA | Saudi Arabia |\n| SN | Senegal |\n| YU | Serbia and Montenegro |\n| SC | Seychelles |\n| SL | Sierra Leone |\n| SG | Singapore |\n| SK | Slovakia |\n| SI | Slovenia |\n| SB | Solomon Islands |\n| SO | Somalia |\n| ZA | South Africa |\n| KR | South Korea |\n| ES | Spain |\n| LK | Sri Lanka |\n| PM | St Pierre Miquelon |\n| VC | St Vincent and Grenadines |\n| SR | Suriname |\n| SZ | Swaziland |\n| SE | Sweden |\n| CH | Switzerland |\n| SY | Syria |\n| TW | Taiwan |\n| TJ | Tajikistan |\n| TZ | Tanzania |\n| TH | Thailand |\n| TL | Timor-Leste |\n| TG | Togo |\n| TK | Tokelau |\n| TO | Tonga |\n| TT | Trinidad and Tobago |\n| TN | Tunisia |\n| TR | Turkey |\n| TM | Turkmenistan |\n| TC | Turks and Caicos Islands |\n| TV | Tuvalu |\n| UG | Uganda |\n| UA | Ukraine |\n| AE | United Arab Emirates |\n| GB | United Kingdom |\n| UY | Uruguay |\n| UM | US Minor Outlying Islands |\n| US | United States of America |\n| UZ | Uzbekistan |\n| VU | Vanuatu |\n| VE | Venezuela |\n| VN | Vietnam |\n| VG | Virgin Islands-British |\n| VI | Virgin Islands-US |\n| WF | Wallis and Futuna Islands |\n| WS | Western Samoa |\n| YE | Yemen Republic |\n| ZM | Zambia |\n| ZW | Zimbabwe |\n\n## US state codes\n| State code | State |\n|------------|-------|\n| AL | Alabama |\n| AK | Alaska |\n| AZ | Arizona |\n| AR | Arkansas |\n| CA | California |\n| CO | Colorado |\n| CT | Connecticut |\n| DE | Delaware |\n| DC | District of Columbia |\n| FL | Florida |\n| GA | Georgia |\n| HI | Hawaii |\n| ID | Idaho |\n| IL | Illinois |\n| IN | Indiana |\n| IA | Iowa |\n| KS | Kansas |\n| KY | Kentucky |\n| LA | Louisiana |\n| ME | Maine |\n| MD | Maryland |\n| MA | Massachusetts |\n| MI | Michigan |\n| MN | Minnesota |\n| MS | Mississippi |\n| MO | Missouri |\n| MT | Montana |\n| NE | Nebraska |\n| NV | Nevada |\n| NH | New Hampshire |\n| NJ | New Jersey |\n| NM | New Mexico |\n| NY | New York |\n| NC | North Carolina |\n| ND | North Dakota |\n| OH | Ohio |\n| OK | Oklahoma |\n| OR | Oregon |\n| PA | Pennsylvania |\n| RI | Rhode Island |\n| SC | South Carolina |\n| SD | South Dakota |\n| TN | Tennessee |\n| TX | Texas |\n| UT | Utah |\n| VT | Vermont |\n| VA | Virginia |\n| WA | Washington |\n| WV | West Virginia |\n| WI | Wisconsin |\n| WY | Wyoming |\n\n## Canadian provinces\n\n| Code | Province |\n|------|----------|\n| Alberta | Alberta |\n| British Columbia | British Columbia |\n| Manitoba | Manitoba |\n| New Brunswick | New Brunswick |\n| Newfoundland and Labrador | Newfoundland |\n| Northwest Territories | Northwest Territories |\n| Nova Scotia | Nova Scotia |\n| Nunavut | Nunavut |\n| Ontario | Ontario |\n| Prince Edward Island | Prince Edward Island |\n| Quebec | Quebec |\n| Saskatchewan | Saskatchewan |\n| Yukon | Yukon Territory |\n\n## Australian states\n\n| Code | State |\n|------|-------|\n| ACT | Australian Capital Territory |\n| NSW | New South Wales |\n| NT | Northern Territory |\n| QLD | Queensland |\n| SA | South Australia |\n| TAS | Tasmania |\n| VIC | Victoria |\n| WA | Western Australia |\n\n## Supported currency codes\n\nSupported currency codes for affiliate partners:\n\n| Currency code | Currency |\n|---------------|----------|\n| USD | US dollar |\n| GBP | British pound |\n| EUR | Euro |\n| AUD | Australian dollar |\n| HKD | Hong Kong Dollar |\n| SGD | Singapore Dollar |\n| CHF | Swiss Franc |\n| JPY | Japanese Yen |\n| NOK | Norwegian Krone |\n| CAD | Canadian Dollar |\n| NZD | New Zealand Dollar |\n| INR | Indian Rupee |\n| BRL | Brazillian Lire |\n| ZAR | South African Rand |\n| DKK | Danish Krone |\n| SEK | Swedish Krona |\n\n## Exception error codes\n\n| Error code | Services | Error message | Description |\n|------------|----------|---------------|-------------|\n| ATTRIBUTE_NOT_FOUND | [/product](#operation/product) | | |\n| TOUR_GONE | [/product](#operation/product) | \"We're sorry, we cannot find the tour, activity r attraction you are looking for\" | no product corresponding to the supplied details was found |\n| TOUR_NOT_FOUND | [/product](#operation/product) | \"We're sorry, we cannot find the tour, activity or attraction you are looking for\" | no product corresponding to the supplied details was found |\n| UNKNOWN_ERROR | *any* | *any* | the API reports this error when the exception from the underlying system (e.g. booking server) is not recognized |",
"version": "1.0",
"license": {
"name": "CC BY 4.0",
"url": "https://creativecommons.org/licenses/by/4.0/au"
},
"contact": {
"name": "Viator Partner Support Team",
"email": "affiliateapi@tripadvisor.com"
}
},
"servers": [
{
"url": "https://viatorapi.viator.com/service",
"description": "Production server"
}
],
"security": [
{
"API-key": []
},
{
"Legacy-API-key": []
}
],
"tags": [
{
"name": "Utility services",
"description": "Utility services"
},
{
"name": "Taxonomy services",
"description": "Taxonomy services"
},
{
"name": "Product services",
"description": "Product services"
},
{
"name": "Attraction services",
"description": "Attraction services"
},
{
"name": "Support services",
"description": "Support services"
}
],
"paths": {
"/util/sitedetails": {
"get": {
"tags": [
"Utility services"
],
"summary": "/util/sitedetails",
"operationId": "utilSitedetails",
"description": "Get site details – show the site settings for your organization",
"parameters": [
{
"$ref": "#/components/parameters/acceptLanguage"
},
{
"$ref": "#/components/parameters/defaultCurrencyCode"
},
{
"in": "query",
"name": "centralURL",
"description": "**URL** for multi-URL sites that have a central URL for processing etc like www.alllasvegastours.com has content.allsightseeingtours.com",
"example": "alllasvegastours.com"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/basicErrorModel"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"showLogo": {
"type": "boolean"
},
"showFavicon": {
"type": "boolean"
},
"hasCustomHeaderHtml": {
"type": "boolean"
},
"hasCustomFooterHtml": {
"type": "boolean"
},
"hasCustomCss": {
"type": "boolean"
},
"homepageDestIds": {
"type": "boolean"
},
"piiSetting": {
"type": "boolean"
},
"partnerPrivacyPolicyUrl": {
"type": "boolean"
},
"pointsProgram": {
"type": "boolean"
},
"pointsProgramName": {
"type": "boolean"
},
"pointsProgramUserType": {
"type": "boolean"
},
"pointsProgramHelpText": {
"type": "boolean"
},
"puid": {
"type": "boolean"
},
"retailSiteId": {
"type": "boolean"
},
"companyName": {
"type": "boolean"
},
"defaultCurrency": {
"type": "boolean"
},
"centralURL": {
"type": "boolean"
},
"permissionsDenied": {
"type": "array",
"items": {
"type": "integer"
}
},
"allowMultiCurrency": {
"type": "boolean"
},
"mobileSiteDomain": {
"type": "string",
"description": "ignore (Viator only)"
},
"showSupplierName": {
"type": "boolean"
},
"showAllLangServices": {
"type": "boolean"
},
"showPassbook": {
"type": "boolean"
},
"urlPostFixedValue": {
"type": "string",
"description": "ignore (Viator only)"
},
"canDisableBookEmail": {
"type": "boolean"
},
"clientId": {
"type": "string"
},
"locale": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"url": {
"type": "string"
},
"id": {
"type": "integer"
},
"channel": {
"type": "string"
}
}
}
}
}
]
},
"examples": {
"1": {
"$ref": "#/components/examples/util-sitedetails-example"
}
}
}
}
}
}
}
},
"/util/countrymap": {
"get": {
"tags": [
"Utility services"
],
"summary": "/util/countrymap",
"operationId": "utilCountrymap",
"description": "Get a dictionary mapping coutry-codes to their natural-language names and international dialling prefixes",
"parameters": [
{
"$ref": "#/components/parameters/acceptLanguage"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/basicErrorModel"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"AF": {
"type": "object",
"properties": {
"countryName": {
"type": "string",
"description": "**natural-language name** of the country that the country-code identifies"
},
"phoneCode": {
"type": "string",
"description": "**[International Direct Dialling (IDD)](https://en.wikipedia.org/wiki/International_direct_dialing) prefix** for the country in question"
},
"countryId": {
"type": "string",
"description": "**country-code** for the country in question"
}
}
},
"AX": {
"type": "object",
"properties": {
"countryName": {
"type": "string",
"description": "**natural-language name** of the country that the country-code identifies"
},
"phoneCode": {
"type": "string",
"description": "**[International Direct Dialling (IDD)](https://en.wikipedia.org/wiki/International_direct_dialing) prefix** for the country in question"
},
"countryId": {
"type": "string",
"description": "**country-code** for the country in question"
}
}
}
}
}
}
}
]
},
"examples": {
"1": {
"$ref": "#/components/examples/util-countrymap-example"
}
}
}
}
}
}
}
},
"/util/guid": {
"get": {
"tags": [
"Utility services"
],
"summary": "/util/guid",
"operationId": "utilGuid",
"description": "This service can be used to generate a GUID if necessary",
"parameters": [
{
"$ref": "#/components/parameters/acceptLanguage"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/basicErrorModel"
},
{
"type": "object",
"properties": {
"data": {
"type": "string",
"description": "**[GUID (globally unique identifier)](https://en.wikipedia.org/wiki/Universally_unique_identifier)** for the request"
}
}
}
]
},
"examples": {
"1": {
"$ref": "#/components/examples/util-guid-example"
}
}
}
}
}
}
}
},
"/util/siteBinaryData": {
"post": {
"tags": [
"Utility services"
],
"summary": "/util/siteBinaryData",
"operationId": "utilSiteBinaryData",
"description": "Get partner custom information, such as Logo, Favicon or quick links (only necessary for some partners)",
"parameters": [
{
"$ref": "#/components/parameters/acceptLanguage"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"partnerCustomTypes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"LOGO",
"LOGO_URL",
"FAVICON",
"HEADER_HTML",
"FOOTER_HTML",
"CSS"
]
},
"description": "- `LOGO` - show base64-encoded data of partner's logo\n- `LOGO_URL` - show base64-encoded data of partner's logo URL\n- `FAVICON` - show base64-encoded data of partner's favicon\n- `HEADER_HTML` - show base64-encoded data of the partner's header HTML\n- `FOOTER_HTML` - show base64-encoded data of the partner's footer HTML\n- `CSS` - show base64 based data of partner Site CSS\n",
"example": [
"LOGO",
"LOGO_URL",
"FAVICON",
"HEADER_HTML",
"FOOTER_HTML",
"CSS"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/basicErrorModel"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"favicon": {
"type": "string",
"description": "**base64-encoded image** of the partner's favicon"
},
"logo": {
"type": "string",
"description": "**base64-encoded image** of the partner's logo"
},
"logoUrl": {
"type": "string",
"description": "**base64-encoded data** of the partner's logo URL"
},
"headerHtml": {
"type": "string",
"description": "**base64-encoded data** of the partner sites header HTML"
},
"footerHtml": {
"type": "string",
"description": "**base64-encoded data** of the partner site's footer HTMl"
},
"css": {
"type": "string",
"description": "**base64-encoded image** of the partner's site's CSS"
}
}
}
}
}
]
},
"examples": {
"1": {
"$ref": "#/components/examples/util-siteBinaryData-example"
}
}
}
}
}
}
}
},
"/taxonomy/destinations": {
"get": {
"tags": [
"Taxonomy services"
],
"summary": "/taxonomy/destinations",
"operationId": "taxonomyDestinations",
"description": "- Retrieves all the country taxonomy/city nodes as a flat list\n- Returns a complete list of Viator destinations, including destination names and parent identifiers\n- Used to provide navigation through drill down lists or combo boxes\n",
"parameters": [
{
"$ref": "#/components/parameters/acceptLanguage"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/basicErrorModel"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "**array** of destination objects",
"items": {
"type": "object",
"properties": {
"sortOrder": {
"type": "integer",
"description": "**sort order** for this response"
},
"selectable": {
"type": "boolean",
"description": "ignore - (Viator only)"
},
"destinationUrlName": {
"type": "string",
"description": "ignore - (Viator only)"
},
"defaultCurrencyCode": {
"$ref": "#/components/schemas/defaultCurrencyCode"
},
"lookupId": {
"description": "**hierarchy location specifier** for the destination that is a concatenation of all `parentId` and `destinationId` codes\n- e.g. `'8.77.673'` for Chicago\n- format: [top level `parentId`].[any additional `parentId`].[`destinationId`]\n",
"type": "string"
},
"parentId": {
"type": "integer",
"description": "**unique numeric identifier** of the destination's parent destination"
},
"timeZone": {
"type": "string",
"description": "**time zone** of the destination"
},
"iataCode": {
"$ref": "#/components/schemas/iataCode"
},
"destinationId": {
"type": "integer",
"description": "**unique numeric identifier** of the destination\n- use this value as the `destId` input field for other Viator API services\n"
},
"destinationType": {
"$ref": "#/components/schemas/destinationType"
},
"destinationName": {
"type": "string",
"description": "**natural-language name** of the destination"
},
"latitude": {
"type": "number",
"description": "**latitude component** of the destination's geolocation"
},
"longitude": {
"type": "number",
"description": "**longitude component** of the destination's geolocation"
}
}
}
}
}
}
]
},
"examples": {
"1": {
"$ref": "#/components/examples/taxonomy-destinations-example"
}
}
}
}
}
}
}
},
"/taxonomy/categories": {
"get": {
"tags": [
"Taxonomy services"
],
"summary": "/taxonomy/categories",
"operationId": "taxonomyCategories",
"description": "- Retrieves a list of product categories for a destination that can be used as a means of filtering when searching for products using the [/search/products](#operation/searchProducts) service\n- This service can be used to get a list of all categories and subcategories for a destination by including its `destId`, or you can omit the `destId` to get a list of all categories and subcategories\n- **Note:** If no `destId` is passed, `productCount` and `thumbnailURL` will be `null` as they are destination-specific fields\n",
"parameters": [
{
"$ref": "#/components/parameters/acceptLanguage"
},
{
"in": "query",
"name": "destId",
"schema": {
"type": "integer"
},
"description": "**unique numeric identifier** of the destination to enquire about (optional)\n- `destinationId` is returned by [/taxonomy/destinations](#operation/taxonomyDestination)\n",
"example": 684
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/basicErrorModel"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "**array** of category data objects",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "**unique numeric identifier** for the category"
},
"productCount": {
"type": "integer",
"description": "**number** of products in this category in the destination specified by `destId`\n- **note**: will be `null` if no `destId` is included in the query\n"
},
"thumbnailURL": {
"type": "string",
"description": "**URL** for this category's thumbnail image, selected from the most popular product within the category\n- **note:** will be `null` if no `destId` is included in the query\n"
},
"groupName": {
"type": "string",
"description": "**natural-language name** of *this* product category"
},
"groupUrlName": {
"type": "string",
"description": "**URL-formatted name** of *this* product category"
},
"subcategories": {
"type": "array",
"description": "**array** of subcategory objects",
"items": {
"type": "object",
"properties": {
"sortorder": {
"type": "integer",
"description": "**sort order** (suggested) of the subcategory within the category"
},
"categoryId": {
"type": "integer",
"description": "**unique numeric identifier** of *this* product category"
},
"subcategoryId": {
"type": "integer",
"description": "**unique numeric identifier** of *this* product subcategory"
},
"subcategoryName": {
"type": "string",
"description": "**natural-language name** of *this* product subcategory"
},
"subCategoryUrlName": {
"type": "string",
"description": "**URL-formatted name** of *this* product subcategory"
}
}
}
}
}
}
}
}
}
]
},
"examples": {
"1": {
"$ref": "#/components/examples/taxonomy-categories-example"
}
}
}
}
}
}
}
},
"/taxonomy/attractions": {
"post": {
"tags": [
"Taxonomy services"
],
"summary": "/taxonomy/attractions",
"operationId": "taxonomyAttractions",
"description": "- Retrieves a list of attractions (things like the Eiffel Tower or Empire State Building) and their associated unique numeric identifiers\n- The attraction's identifier (`seoId`) can be used as a means of searching for available products; for example, in the [/search/products](#operation/searchProducts) service.\n",
"parameters": [
{
"$ref": "#/components/parameters/acceptLanguage"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"destId": {
"type": "integer",
"description": "**unique numeric identifier** of the destination in which to search for attractions"
},
"topX": {
"$ref": "#/components/schemas/topX"
},
"sortOrder": {
"type": "string",
"description": "Sort order for the results; one of:\n- `'RECOMMENDED'` – sorted in order of recommendation (**Note**: What Viator gets paid impacts this sort order)\n- `'SEO_ALPHABETICAL'` – Alphabetical (A->Z)\n"
}
}
},
"example": {
"destId": 684,
"topX": "1-3",
"sortOrder": "RECOMMENDED"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/basicErrorModel"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"sortOrder": {
"type": "integer",
"description": "**sort order** of *this* listing"
},
"webURL": {
"$ref": "#/components/schemas/webURL"
},
"pageUrlName": {
"description": "**URL-formatted title** of the attraction page",
"type": "string"
},
"primaryDestinationUrlName": {
"description": "**URL-formatted name** of the destination associated with *this* attraction",
"type": "string"
},
"publishedDate": {
"description": "**conventionally-formatted date** on which the attraction was listed",
"type": "string"
},
"title": {
"description": "**natural-language title** of the attraction",
"type": "string"
},
"attractionLatitude": {
"description": "**latitude component** of the attraction's location",
"type": "number"
},
"attractionLongitude": {
"description": "**longitude component** of the attraction's location",
"type": "number"
},
"attractionStreetAddress": {
"description": "**street address** of the attraction",
"type": "string"
},
"attractionCity": {
"description": "**name** of the city in which the attraction is located",
"type": "string"
},
"attractionState": {
"description": "**name** of the state in which the attraction is located",
"type": "string"
},
"destinationId": {
"description": "**unique numeric identifier** of the the destination associated with the attraction",
"type": "integer"
},
"thumbnailHiResURL": {
"description": "**URL** for the attraction's high-resolution thumbnail image",
"type": "string"
},
"photoCount": {
"description": "**number** of user photos published for the attraction",
"type": "integer"
},
"primaryDestinationId": {
"description": "**unique numeric identifier** of the attraction's primary destination",
"type": "integer"
},
"seoId": {
"description": "**unique numeric identifier** of the attraction\n- use as an input for [/search/products](#operation/searchProducts)\n",
"type": "integer"
},
"productCount": {
"description": "**number** of products associated with the attraction",
"type": "integer"
},
"primaryDestinationName": {
"description": "**natural-language name** of the attraction's primary destination",
"type": "string"
},
"thumbnailURL": {
"description": "**URL** the attraction's thumbnail image",
"type": "string"
},
"rating": {
"description": "**average user rating** of the attraction",
"type": "number"
}
}
}
}
}
}
]
},
"examples": {
"1": {
"$ref": "#/components/examples/taxonomy-attractions-example"
}
}
}
}
}
}
}
},
"/search/products": {
"post": {
"tags": [
"Product services"
],
"summary": "/search/products",
"operationId": "searchProducts",
"description": "\nThis service is used to search for products based on various criteria; such as:\n* the destination (locale) in which it operates\n* its association with a tourist attraction\n* its category and/or subcategory\n* the time period during which it operates\n\nThe fields you include in the request body for this service determine the kind of search that will be performed.\n\n**<u>Note</u>**: \n\n* You can search **EITHER** by destination (`destId`) **OR** by attraction-link (`seoId`), but not both.\n* The destination identifier (`destId`) can be retrieved from the [/taxonomy/destinations](#operation/taxonomyDestinations) service.\n* The category (`catId`) and subcategory (`subCatId`) identifiers can be retrieved from the [/taxonomy/categories](#operation/taxonomyCategories) service.\n* The attraction identifier (`seoId`) can be retrieved from the [/taxonomy/attractions](#operation/taxonomyAttractions) service.\n\n**<u>Examples</u>**:\n\n**Search by destination**:\n\n* E.g., \"Top ten highest-rated yoga classes operating in Las Vegas:\n```javascript\n{\n \"destId\": 684,\n \"subCatId\": 26052,\n \"sortOrder\": \"REVIEW_AVG_RATING_D\",\n \"topX\": \"1-3\"\n}\n```\n\n**Search by attraction-link**:\n\n* E.g., \"Products related to Everglades National Park operating 21-26 May 2019 in order of descending price\":\n```javascript\n{\n \"seoId\": 1115,\n \"startDate\": \"2019-05-21\",\n \"endDate\": \"2019-05-26\",\n \"sortOrder\": \"PRICE_FROM_D\"\n \"topX\": \"1-3\"\n}\n```\n",
"parameters": [
{
"$ref": "#/components/parameters/acceptLanguage"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"destId": {
"type": "integer",
"description": "**unique numeric identifier** of the destination in which to search for products\n- `destinationId` is available from the [/taxonomy/destinations](#operation/taxonomyDestinations) service\n- use **EITHER** `destId` **OR** `seoId`, but not both\n"
},
"seoId": {
"type": "string",
"description": "**search restriction specifier** for products associated with an attraction uniquely identified by `seoId`\n- use **EITHER** `destId` **OR** `seoId`, but not both\n"
},
"catId": {
"type": "integer",
"description": "**unique numeric identifier** of *this* product category to search within\n- `categoryId` can be retrieved from the [/taxonomy/categories](#operation/taxonomyCategories) service\n- at present, it is not possible to use `catId` in conjunction with `seoId`\n"
},
"subCatId": {
"type": "integer",
"description": "**unique numeric identifier** of *this* product subcategory to search within\n- `subcategoryId` can be retrieved from the [/taxonomy/categories](#operation/taxonomyCategories) service\n- at present, it is not possible to use `subCatId` in conjunction with `seoId`\n"
},
"startDate": {
"type": "string",
"description": "**start date delimiter** for the search (must be in the future)\n- e.g., `'2018-10-21'`\n"
},
"endDate": {
"type": "string",
"description": "**end date delimiter** for the search (must be in the future)\n- e.g., `'2019-10-21'`\n"
},
"currencyCode": {
"type": "string",
"description": "**currency** in which to display product prices"
},
"topX": {
"$ref": "#/components/schemas/topX"
},
"sortOrder": {
"$ref": "#/components/schemas/sortOrder"
}
}
},
"examples": {
"By destination": {
"value": {
"destId": 684,
"subCatId": 26052,
"sortOrder": "REVIEW_AVG_RATING_A",
"topX": "1-3"
}
},
"By attraction link": {
"value": {
"seoId": 1115,
"startDate": "2020-12-21",
"endDate": "2020-12-31",
"sortOrder": "PRICE_FROM_D",
"topX": "1-3"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/basicErrorModel"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "**array** of product objects",
"items": {
"type": "object",
"properties": {
"sortOrder": {
"type": "integer",
"description": "**sort order** for *this* product"
},
"supplierName": {
"type": "string",
"description": "**natural-language name** of *this* product's supplier"
},
"currencyCode": {
"$ref": "#/components/schemas/currencyCode"
},
"catIds": {
"type": "array",
"description": "**list** of unique numeric category identifiers for *this* product\n- the `categoryId` for the destination is available from the [/taxonomy/categories](#operation/taxonomyCategories) service\n",
"items": {
"type": "integer"
}
},
"subCatIds": {
"type": "array",
"description": "**list** of unique numeric subcategory identifiers for *this* product\n- the `subcategoryId` for the destination is available from the [/taxonomy/categories](#operation/taxonomyCategories) service\n",
"items": {
"type": "integer"
}
},
"webURL": {
"$ref": "#/components/schemas/webURL"
},
"specialReservationDetails": {
"type": "string",
"description": "ignore (Viator only)"
},
"sslSupported": {
"description": "ignore (Viator only)"
},
"panoramaCount": {
"type": "integer",
"description": "**number** of panoramic images available for *this* product"
},
"merchantCancellable": {
"type": "boolean",
"description": "ignore (Viator only)\n\n \nFor cancellation information regarding the booking, please refer to the `merchantTermsAndConditions` object\n"
},
"bookingEngineId": {
"$ref": "#/components/schemas/bookingEngineId"
},
"onRequestPeriod": {
"$ref": "#/components/schemas/onRequestPeriod"
},
"primaryGroupId": {
"type": "integer",
"description": "ignore (Viator only)"
},
"pas": {
"type": "object",
"description": "**object** detailing product availability\n- `pas` stands for Product Availability Schema\n"
},
"available": {
"type": "boolean",
"description": "ignore (Viator only)"
},
"productUrlName": {
"type": "string",
"description": "**URL-formatted name** of *this* product"
},
"primaryDestinationUrlName": {
"type": "string",
"description": "**URL-formatted name** of *this* product's primary destination"
},
"title": {
"type": "string",
"description": "**natural-language title** of *this* product"
},
"shortDescription": {
"type": "string",
"description": "**HTML-formatted natural-language description** of *this* product"
},
"supplierCode": {
"type": "string",
"description": "**unique identifier** of *this* product's supplier in text string format"
},
"uniqueShortDescription": {
"type": "string",
"description": "ignore (Viator only)"
},
"merchantNetPriceFrom": {
"type": "number",
"description": "ignore (Viator only)"
},
"merchantNetPriceFromFormatted": {
"type": "string",
"description": "ignore (Viator only)"
},
"essential": {
"type": "string",
"description": "ignore (Viator only)"
},
"admission": {
"type": "string",
"description": "ignore (Viator only)"
},
"translationLevel": {
"$ref": "#/components/schemas/translationLevel"
},
"thumbnailHiResURL": {
"type": "string",
"description": "**URL** for the high resolution thumbnail for *this* product"
},