TRAVLR Search APIs – Partner Integration Guide (v1.0)
This guide describes the TRAVLR Search APIs for building custom search modules on partner sites. Current product types: Accommodation, Deals, Activities, and Flights. Flights endpoints will be published separately when stable.
1. Base access
Base URL
Your partner domain, e.g. https://book.yourURL.com
Authentication
Header: x-tkey: <tenant-api-key>
Obtain the key from TRAVLR Support.
Content type
All requests and responses are JSON unless specified.
Environment
Production only. Staging environments available on request.
2. Conventions
Pagination: request page.size and page.current where supported. Responses include meta.page with current, totalPages, totalResults, size.
Sorting: where supported, pass sort with one of the values returned in meta.availableSorts.
Currency: provide availabilityRequest.currency (e.g. AUD).
Dates: ISO 8601 YYYY-MM-DD.
Coordinates: decimal degrees. Example: { "latitude": -8.781028, "longitude": 115.22485 }.
Errors: standard HTTP codes with JSON body { code, message, requestId }.
Idempotency: search endpoints are safe to retry on 5xx.
3. Endpoints by product
3.1 Accommodation
Purpose: search properties by name, destination, or coordinates. Destination and geo searches return pricing when availabilityRequest is supplied.
Endpoints
POST /api/search/accommodations/suggestions
Search by hotel/property name. Returns basic property info. No pricing.
POST /api/search/accommodations/destination
Search by destination. Returns properties with pricing based on availabilityRequest.
POST /api/search/accommodations/geo
Search by coordinates. Returns properties with pricing. Sorted by distance.
Validation rules
Max 8 adults per room
Min 1 adult per room
Max 8 children per room
Max 8 rooms per search
Check-in must be earlier than check-out
Check-in cannot be earlier than today
Max stay 28 days (inclusive)
Minimal examples
POST /api/search/accommodations/suggestions
{
"query": "Conrad",
"count": 5
}POST /api/search/accommodations/destination
{
"destinationFullName": "Bali, Indonesia",
"page": { "size": 10, "current": 1 },
"includeFacets": true,
"availabilityRequest": {
"checkInDate": "2025-10-03",
"checkOutDate": "2025-10-04",
"currency": "AUD",
"guestsCount": { "adult": 2, "child": 0, "infant": 0 },
"roomsCount": 1
}
}POST /api/search/accommodations/geo
{
"centerCoordinate": { "latitude": -8.781028, "longitude": 115.22485 },
"distance": 10000,
"page": { "size": 10, "current": 1 },
"includeFacets": true,
"availabilityRequest": {
"checkInDate": "2025-09-03",
"checkOutDate": "2025-09-04",
"currency": "AUD",
"guestsCount": { "adult": 2, "child": 0, "infant": 0 },
"roomsCount": 1
},
"filters": { "alwaysShowFirstGeoMatch": true }
}3.2 Deals
Purpose: surface deal products and destinations, with pricing.
Endpoints
GET /deals-and-offers/suggestion/autocomplete?q=<query>
Returns destination suggestions and deal product suggestions. No pricing.
POST /deals-and-offers/search
Search by destination or product name. Returns pricing and filter metadata.
Minimal examples
GET /deals-and-offers/suggestion/autocomplete?q=Bali
POST /deals-and-offers/search
{
"keyword": "Bali, Indonesia",
"page": 1,
"limit": 30,
"type": "Destination"
}3.3 Activities
Purpose: suggest and search activity listings with pricing.
Endpoints
GET /activities/suggestion?q=<query>
Returns destination and activity suggestions. No pricing.
POST /activities/search
Search by destination or listing name. Returns pricing and filters.
Minimal examples
GET /activities/suggestion?q=Bali
POST /activities/search
{
"keyword": "Sustainable Dolphin Watching in Pemuteran",
"searchType": "listing",
"page": 1,
"limit": 30,
"sort": "recommended"
}3.4 Destinations
Purpose: support destination discovery and search inputs.
Endpoints
GET /api/search/destinations/popular
Returns curated popular destinations with availability flags.
POST /api/search/destinations/suggestions
Returns destination suggestions matching query and optional filters.
Minimal examples
GET /api/search/destinations/popular
POST /api/search/destinations/suggestions
{
"query": "Bali",
"count": 3,
"filters": { "hasAccommodation": true }
}4. Response shape (abridged)
Responses include meta with requestId, page, and optional availableSorts. Result arrays vary by endpoint and include identifiers, names, destinations, amenities, images, location, pricing, refundability, and facet collections when includeFacets is true.
5. Error handling
HTTP status codes
400 Validation error (date range, occupancy rules)
401 Missing or invalid x-tkey
404 Resource not found
429 Rate limit exceeded
5xx Transient server error
Error body
{ "code": "VALIDATION_ERROR", "message": "Check-in must be before check-out", "requestId": "..." }6. Rate limits and performance
Rate limits may apply at tenant level. Contact TRAVLR Support for allocations.
Use pagination rather than very large page.size values.
Cache suggestions and popular destinations where possible.
Reuse requestId when raising support tickets.
7. Versioning and stability
This guide covers current production endpoints. Breaking changes will be versioned and announced in release notes. Non-breaking additions may appear without version bumps.
8. Contact
TRAVLR Support: partners@travlr.com
Include the requestId from meta when contacting support.
9. Postman Starter Collection
The starter example is available as a downloadable Postman collection. Use this collection as a base and extend it as needed.
Download the Postman collections
10. Full example payloads
Below are full examples mirrored from production responses for quick reference.
10.1 POST /api/search/accommodations/suggestions
Request
{
"query": "Bali",
"count": 3
}Response
{
"meta": {
"requestId": "Wp2n6ZwWTjeLwvGnjcnGmQ",
"page": { "current": 1, "totalPages": 10, "totalResults": 30, "size": 3 },
"engineName": "trv-app-prd-meta-accommodations",
"availableSorts": ["Popularity", "GuestRating"]
},
"result": [
{
"id": "Expedia-1056661",
"productType": "Accommodation",
"name": "Conrad Bali",
"city": "Nusa Dua",
"country": "Indonesia",
"starRating": 5.0,
"guestRating": 90.0,
"destinations": ["Nusa Dua", "Bali"],
"hotelAmenities": ["Free WiFi", "Spa services on site"],
"roomAmenities": ["Non-Smoking", "Television", "Minibar"],
"propertyType": "Resort",
"images": ["https://i.travelapi.com/lodging/.../683c4317_z.jpg"],
"location": { "latitude": -8.781028, "longitude": 115.22485 }
}
]
}10.2 POST /api/search/accommodations/destination
Request
{
"destinationFullName": "Bali, Indonesia",
"page": { "size": 10, "current": 1 },
"includeFacets": true,
"availabilityRequest": {
"checkInDate": "2025-10-03",
"checkOutDate": "2025-10-04",
"currency": "AUD",
"guestsCount": { "adult": 2, "child": 0, "infant": 0 },
"roomsCount": 1
}
}Response
{
"meta": {
"requestId": "j4iyyTxVQkS1NdscDLK-7w",
"page": { "current": 1, "totalPages": 3334, "totalResults": 10000, "size": 3 },
"engineName": "trv-app-prd-meta-accommodations",
"availableSorts": ["Popularity", "GuestRating", "StarRating"]
},
"result": [
{
"id": "trv-app-prd-accommodations-20250821-022036|Expedia-17591",
"productType": "Accommodation",
"productId": "Expedia-17591",
"name": "The Westin Resort Nusa Dua, Bali",
"city": "Nusa Dua",
"country": "Indonesia",
"popularity": 99.9994,
"starRating": 5.0,
"guestRating": 90.0,
"guestRatingCount": 1000,
"destinations": ["BTDC", "Nusa Dua", "Bali"],
"currentCheapestPrice": 886.51,
"comparisonCheapestPrice": 842.62,
"currency": "AUD",
"hotelAmenities": ["Full-service spa", "Yoga classes/instruction on site"],
"roomAmenities": ["Premium bedding", "Blackout drapes/curtains"],
"propertyType": "Resort",
"images": ["https://i.travelapi.com/lodging/.../ee730c8c_z.jpg"],
"hasRoomAvailability": true,
"location": { "latitude": -8.79601, "longitude": 115.22901 },
"provider": "Expedia",
"providerPropertyId": "17591",
"isRefundable": true,
"isPromoted": false
}
],
"facets": {
"DestinationCountry": [{ "value": "Indonesia", "count": 23469 }]
}
}10.3 POST /api/search/accommodations/geo
Request
{
"centerCoordinate": { "latitude": -8.781028, "longitude": 115.22485 },
"distance": 10000,
"page": { "size": 10, "current": 1 },
"includeFacets": true,
"availabilityRequest": {
"checkInDate": "2025-09-03",
"checkOutDate": "2025-09-04",
"currency": "AUD",
"guestsCount": { "adult": 2, "child": 0, "infant": 0 },
"roomsCount": 1
},
"filters": { "alwaysShowFirstGeoMatch": true }
}Response
{
"meta": {
"requestId": "QNLhh9feTSK1sFh-tZQHSg",
"page": { "current": 1, "totalPages": 1999, "totalResults": 3997, "size": 2 },
"engineName": "trv-app-prd-meta-accommodations",
"availableSorts": ["Popularity", "GuestRating", "StarRating", "Location"]
},
"result": [
{
"id": "trv-app-prd-accommodations-20250821-022036|Expedia-1056661",
"productType": "Accommodation",
"productId": "Expedia-1056661",
"name": "Conrad Bali",
"city": "Nusa Dua",
"country": "Indonesia",
"starRating": 5.0,
"guestRating": 90.0,
"destinations": ["Tanjung Benoa", "Nusa Dua", "Bali"],
"currentCheapestPrice": 364.75,
"currentStrikeThroughPrice": 375.26,
"comparisonCheapestPrice": 322.2,
"currency": "AUD",
"hotelAmenities": ["Beach volleyball on site"],
"roomAmenities": ["Non-Smoking", "Furnished balcony or patio", "Television"],
"propertyType": "Resort",
"images": ["https://i.travelapi.com/lodging/.../683c4317_z.jpg"],
"hasRoomAvailability": true,
"location": { "latitude": -8.781028, "longitude": 115.22485 },
"provider": "HotelBeds",
"providerPropertyId": "24221",
"contentProviderPropertyId": "1056661",
"isRefundable": false,
"isPromoted": false
}
]
}10.4 GET /deals-and-offers/suggestion/autocomplete
Request
Response
[
{ "title": "Bali, Indonesia", "type": "Destination" },
{ "title": "Seminyak, Bali, Indonesia", "type": "Destination" },
{ "title": "Ubud, Bali, Indonesia", "type": "Destination" },
{ "title": "A Luxe Legian Getaway at Away Bali Legian Camakila", "type": "Product" }
]10.5 POST /deals-and-offers/search
Request
{
"keyword": "Bali, Indonesia",
"page": 1,
"limit": 30,
"type": "Destination"
}Response
{
"searchResult": {
"meta": { "engine": "trv-app-prd-meta-deals", "requestId": "wM5Sff5aS5uKGCT0cEdVnw" },
"items": [
{
"id": 2169,
"name": "An Exclusive Five-Star Stay at Double-Six Luxury Hotel",
"label": "Daily breakfast",
"valueAddLabel": "Save up to 48%",
"image": "https://s3.ap-southeast-2.amazonaws.com/travlr.com/cms/prod/.../DoubleSix_5DJ_7063nosunset-bright_17.jpg",
"destinations": [{ "id": 0, "name": "Double Six" }, { "id": 0, "name": "Seminyak" }],
"category": { "id": 0, "name": "Accommodation" },
"placeName": "Double-Six Luxury Hotel - Flash Sale",
"customerPrice": { "amount": 1319.0, "currency": { "isoCode": "AUD", "symbol": "$" }, "formattedString": "AU$1,319.00" },
"rrp": { "amount": 1319.0, "currency": { "isoCode": "AUD" }, "formattedString": "AU$1,319.00" },
"discount": 0.0,
"currency": "AUD",
"priceInfo": "2 adults from",
"isTransactable": true,
"dynamicPrice": false,
"duration": "Min. 5 nights",
"isRefundable": true
}
],
"total": 35
}
}10.6 GET /activities/suggestion
Request
Response
{
"destinations": ["Bali, Indonesia", "Badung, Bali, Indonesia", "Ubud, Bali, Indonesia"],
"categories": [],
"listings": [
{ "text": "Sustainable Dolphin Watching in Pemuteran", "url": "/activities/detail/sustainable-dolphin-watching-in-pemuteran?p=1&c=431051P4" },
{ "text": "3 Days PADI Open Water Course in Pemuteran", "url": "/activities/detail/3-days-padi-open-water-course-in-pemuteran?p=1&c=212334P20" }
]
}10.7 POST /activities/search
Request
{
"keyword": "Sustainable Dolphin Watching in Pemuteran",
"searchType": "listing",
"page": 1,
"limit": 30,
"sort": "recommended"
}Response
{
"searchResult": {
"items": [
{
"documentId": "trv-app-prd-activities-20250827-060025|Viator-442187",
"id": 100627841,
"name": "Sustainable Dolphin Watching in Pemuteran",
"rating": 0.0,
"destinations": [{ "id": 0, "name": "Pemuteran" }],
"photo": "https://media-cdn.tripadvisor.com/media/attractions-splice-spp-720x480/15/7f/33/e4.jpg",
"sellPrice": { "amount": 76.39, "currency": { "isoCode": "AUD" }, "formattedString": "AU$76.39" },
"strikeThroughPrice": { "amount": 93.9618, "currency": { "isoCode": "AUD" }, "formattedString": "AU$93.96" },
"comparisonPrice": { "amount": 70.03, "currency": "AUD", "symbol": "$", "formatted": "AUD AU$70.03" },
"isAvailable": true
}
],
"total": 3343,
"searchEngineName": "trv-app-prd-meta-activities",
"searchRequestId": "ylUeAzC3QgqHXma4jca1WA"
}
}10.8 GET /api/search/destinations/popular
Request
Response
{
"meta": { "requestId": "cJBW-MrOR4a0FQSRRkokkg", "page": { "current": 1, "totalPages": 1, "totalResults": 4, "size": 4 }, "engineName": "trv-app-prd-meta-destinations" },
"result": [
{
"destinationId": "new-zealand-133",
"name": "New Zealand",
"level": "country",
"hasAccommodation": true,
"hasActivity": true,
"hasDeal": true
}
]
}10.9 POST /api/search/destinations/suggestions
Request
{
"query": "Bali",
"count": 3,
"filters": { "hasAccommodation": true }
}Response
{
"meta": { "requestId": "Lj7ZmimjTnK8sYW1EECnXA", "page": { "current": 1, "totalPages": 245, "totalResults": 735, "size": 3 } },
"result": [
{
"destinationId": "602651",
"name": "Bali",
"fullName": "Bali, Indonesia",
"level": "province_state",
"hasAccommodation": true,
"hasActivity": true,
"hasDeal": true
}
]
}Appendix A. UI widgets
Typical search UI elements used with these endpoints:
Accommodation: Destination or Property input, Check-in/Check-out, Rooms and Occupancy.
Deals: Destination or Deal input.
Activities: Destination or Activity input.
Appendix B. Support process
When raising a ticket, include:
Endpoint called
Full request body (sanitised)
requestId from the response meta
Timestamp and partner host