Frequently Asked QuestionsCommonly asked questions about Traveloka Partners Network.
General API Usage
Search and Pagination
Caching and Data Refresh
Hotel and Room Information
Booking Process and Management
Error Handling and Troubleshooting
Rate Management and Optimization
Retry Logic and Timeout Handling
Best Practice
01
GetRate API
GetRate Search: Can retrieve up to 50 hotel IDs in a single request (parallel search requests are supported).
Search Criteria: • Maximum of Rooms: 8
• Maximum of Adults: 30
• Maximum length of stay: 15 days
• Check-in and Check-out must be within 1 year (Next 365 days)
Avoid Invalid Spec Combinations: Ensure search queries contain valid specifications like:Example: • Correct check-in and check-out dates (no backdated searches)
• Valid booking windows 365 days with Los = 15
• Reasonable adult and child numbers (e.g., Adults 10)
Use Accurate Guest Information: Invalid specs for guests (adults, children) can lead to failed bookings. Validate age range and number of guests to match the inventory.02
Pagination Best Practice
When retrieving large data sets through the API, it is essential to implement pagination to ensure optimal performance and to prevent overwhelming the server or your application.
Using limit and offset Parameters: • limit: Specifies the maximum number of items to be returned in the response. • offset: Specifies the number of items to skip before starting to return results.Example: GET /api/v1/hotels?limit=100&offset=200 • This query will return 100 hotels starting from the 201st hotel in the dataset.
Best Practices for Pagination: • Set a sensible default limit: If no limit is specified by the client, provide a default (e.g., 50 results per page). • Maximum limit: Impose a maximum limit (e.g., 1000 results per page) to avoid overloading the system with large data requests. • Next page links: Provide a next and previous link in the response to make it easier for clients to fetch the next or previous set of data.
Example:{
"results": [...],
"next": "/api/v1/hotels?limit=100&offset=300",
"previous": "/api/v1/hotels?limit=100&offset=100"
}
• Total count: Include the total count of items in the dataset so that clients can calculate the total number of pages.Example:{
"results": [...],
"total": 5000,
"limit": 100,
"offset": 200
}
• In this case, the client can calculate the total number of pages as 5000 / 100 = 50 pages.03
Caching and Data Refresh Best Practices
To optimize system performance and reduce the number of API calls, we recommend implementing caching for both static and dynamic data, especially when dealing with frequently changing content such as room availability and rates.
Static Data (Cache for 7 Days)Static information (e.g., hotel name, address, amenities, room descriptions) can be cached for longer periods since it doesn’t change frequently. Refresh weekly unless significant changes are expected. • Hotel Information: Cache for 7 days • Example: GET /properties/content/hotel • Room Information: Cache for 7 days • Example: GET /properties/content/room
Dynamic Data (Cache for 30 Minutes)Dynamic data like room availability and rates change frequently, so shorter caching intervals are recommended to balance accuracy and API performance. • Room Availability Cache for 30 minutes to reduce API hits while ensuring reasonable accuracy. • Example: GET /properties/getRates • Rates Cache for 30 minutes as rates fluctuate often, ensuring data freshness for customer queries. • Example: GET /properties/checkRate
Cache Based on Property Demand • High-Demand Properties: Cache room availability and rates for 15 minutes to keep data accurate for frequently booked properties. • Low-Demand Properties: Extend the cache duration to 30 minutes for properties with lower booking frequencies to reduce unnecessary API calls without sacrificing accuracy.
04
Implement Intelligent Caching
• Cache Frequent Requests: Prioritize caching results for high-demand hotels and room types with short booking windows (e.g., 1-3 days). This reduces redundant requests and improves response times. • Extend Time-to-Live (TTL) for Low-Demand Inventory: For hotels and rooms with lower demand, use longer TTLs to avoid frequent updates and reduce API calls (e.g., 12 hours).
05
Sorting
Sorting helps clients organize data according to specific fields like price, rating, or date.
Common Sorting Parameters: • sort: The field by which to sort the results (e.g., price, name, rating). • order: The order in which to sort the results. It can take the values asc (ascending) or desc (descending).
Example:GET /api/v1/hotels?sort=price&order=ascThis query will return hotels sorted by price in ascending order.
Best Practices for Sorting: • Allow multiple sort fields: Permit sorting by more than one field by using a comma-separated list. For example:
Example:GET /api/v1/hotels?sort=price,rating&order=asc,descThis query will sort the hotels first by price in ascending order and then by rating in descending order.
• Default sorting: Provide default sorting when none is specified by the client (e.g., by relevance or date). • Sorting options: Clearly document the available fields that can be sorted (e.g., price, name, rating, availability).06
Handling Error Cache
• Empty responses: When there are no items to return for a specific page, return an empty array with appropriate metadata, such as total count and pagination links.
Example:{
"results": [],
"total": 0,
"limit": 100,
"offset": 0,
"next": null,
"previous": null
}
• Invalid pagination parameters: Return an error message if the offset or limit parameters are out of bounds (e.g., offset greater than the total number of items).
Example:{
"error": "Invalid offset. There are only 50 pages available."
}
07
Best Practices for Optimizing Look-to-Book (LTB)
• Optimize Search Specifications: Ensure valid specs like check-in/out dates, booking windows (≤ 15 days), and guest details (adults ≤ 10, reasonable child count). Validate the spec combinations to avoid invalid searches that contribute to low-quality queries. • Use Intelligent Caching: Frequent Requests: Cache results for high-demand hotels/room types with a short TTL (1-3 hours). Low-Demand Inventory: For low-demand hotels, use a longer TTL (6-12 hours) to avoid redundant requests. • Focus on High-Quality Inventory: Ensure to stop searching hotels that are permanently closed or temporarily unavailable. Focus on hotels that frequently convert (e.g., hotels booked at least once in the last 3 months). • Reduce Spec Multiplier: Limit overly broad search queries with excessive combinations (LoS, adults, rooms) that produce wasteful requests. • Respect Rate Limits: Ensure search frequency does not exceed the API's rate limit (e.g., no more than 50 requests per second).
08
Mapping Recommendations
To optimize data accuracy, ensure all static data is mapped with these key components:
• Hotel Data: Address, Longitude, Latitude, Hotel Name (Note: Phone number not provided). • Room Data: Room Name, Views, Window, Smoking Preference, Area, Gender (if applicable), Bed Type.
API Endpoints for Mapping: • Hotel Data: Use GetHotel. • Room Data: Use GetRoom.Following these recommendations ensures consistent data and smooth booking operations.
09
Mapping API
Given affiliate spec of hotel, we will give them hotel ID based on similarity.