Changelog
All notable changes to the Expedia Hotels API research project.
[2025-01-29] - Rooms Configuration Feature
New Feature: Multi-Room and Family Search Support
Added comprehensive rooms configuration support, enabling users to search for:
- Single rooms with customized occupancy
- Family accommodations with children of specific ages
- Multi-room bookings for group travel (up to 8 rooms)
Implementation
- File:
.actor/input_schema.json
- Added:
rooms parameter with full validation
- Schema: Array of room objects with adults (1-8) and children (0-6 per room, ages 0-17)
- Default:
[{"adults": 2, "children": []}] maintains backward compatibility
2. Validation Module
- File:
utils/validation.py
- Function:
validate_rooms() with comprehensive validation
- Features:
- Room count validation (1-8 rooms)
- Adults count validation (1-8 per room)
- Children structure validation
- Age validation (0-17)
- Clear, actionable error messages
3. Main Logic Integration
- File:
src/main.py
- Changes:
- Added rooms parameter to
call_search() function
- Integrated validation in main execution flow
- Added rooms logging with guest count summary
- Passes validated rooms to payload builder
4. Comprehensive Documentation
- File:
.actor/README.md
- Content:
- Complete rooms configuration guide
- Multiple real-world examples
- Rules and limits documentation
- Impact explanation (pricing, availability, room types)
- Common use cases for different scenarios
Technical Details
Room Object Structure
{
"adults": 2,
"children": [
{"age": 5},
{"age": 10}
]
}
API Integration
- Rooms parameter already supported by
build_search_variables() in payload builder
- No changes needed to existing API infrastructure
- Seamless integration with existing search flow
Validation Rules
- Rooms: 1-8 per search
- Adults: 1-8 per room (required field)
- Children: 0-6 per room (optional)
- Ages: 0-17 years old (required for each child)
Use Cases
Family Vacation
{
"rooms": [{
"adults": 2,
"children": [{"age": 5}, {"age": 8}, {"age": 12}]
}]
}
Group Travel
{
"rooms": [
{"adults": 2, "children": []},
{"adults": 2, "children": [{"age": 10}]},
{"adults": 1, "children": []}
]
}
Breaking Changes
None - This is additive functionality. Existing implementations without rooms parameter use the default configuration and continue to work unchanged.
Testing Status
- ✅ Input schema validated
- ✅ Validation logic implemented
- ✅ Main integration complete
- ✅ Documentation complete
- ⏳ End-to-end testing pending
Impact
- Users: Can now search for family accommodations and multi-room bookings
- Pricing: Results reflect accurate pricing for specified occupancy
- Availability: Filters hotels based on room availability for party size
- Compatibility: Fully backward compatible with existing implementations
[2025-01-28] - Multi-Region Support Breakthrough
Major Discoveries
1. Universal siteId (siteId=1)
- Discovery: All Expedia domains work with
siteId=1
- Testing: Systematically tested 35+ regional domains
- Impact: Eliminates need for region-specific siteId discovery
- File:
region_config.py - Production configuration with all regions
2. Domain Significance
- Discovery: Domains are separate marketplaces, not just localization
- Testing: Compared www.expedia.com vs www.expedia.de for same location
- Finding: Only 20% hotel overlap - different inventory per domain
- Impact: MUST use correct regional domain, cannot substitute with .com
3. Multi-Locale Support
- Discovery: Single domain serves multiple locales seamlessly
- Testing: www.expedia.de with de_DE, en_US, en_GB locales
- Finding: Locale controls language only, not hotel availability
- Impact: Support international users on same regional domain
4. Currency Behavior
- Discovery: Currency parameter is ignored by API
- Testing: www.expedia.de with EUR/USD/GBP requests
- Finding: Domain determines currency, not request parameter
- Impact: Currency in request is decorative, actual value from domain
Deliverables
Production Configuration
- File:
region_config.py
- Regions: 35 confirmed and production-ready
- Features:
- Universal
siteId=1 for all regions
- Complete domain/locale/currency mappings
- Multi-locale support for 6 regions
- Region grouping (by geography, currency)
- Helper functions for easy access
Comprehensive Documentation
- File:
docs/2501-multi-region-configuration.md
- Content:
- 4 systematic test findings with results
- Complete 35-region reference table
- Implementation guide with code examples
- Domain significance explanation
- Common mistakes to avoid
- Migration guide from old approaches
Testing Infrastructure
-
File: tests/test-region-flexibility.py
- Multi-locale support validation
- Currency override testing
-
File: tests/test-deep-comparison.py
- siteId=1 vs siteId=6 comparison
- Domain significance validation
- Full response analysis
-
File: tests/discover-regions.py
- Systematic region discovery script
- Tested 10 domains in 9 seconds
Technical Details
Configuration Architecture
@dataclass
class RegionConfig:
code: str
name: str
domain: str
site_id: int
locale: str
currency: str
alternate_locales: List
confirmed: bool
Supported Regions
- North America: US, CA, MX (3)
- Europe: UK, IE, FR, DE, AT, CH, BE, NL, IT, ES, SE, NO, DK, FI (14)
- Asia: JP, KR, CN, TW, HK, SG, MY, TH, ID, PH, VN, IN (12)
- Oceania: AU, NZ (2)
- South America: BR, AR (2)
- Total: 35 regions
Multi-Locale Regions
- Canada: en_CA, fr_CA
- Switzerland: de_CH, fr_CH
- Belgium: fr_BE, nl_BE
- Spain: es_ES, ca_ES
- Hong Kong: zh_HK, en_HK
- Malaysia: en_MY, ms_MY
Breaking Changes
None - This is additive functionality. Existing implementations using hardcoded US configuration continue to work.
Migration Path
For those using region-specific siteIds:
- Replace with
from region_config import REGIONS
- Change all
siteId values to 1
- Keep domain-specific logic (still required)
- Remove siteId discovery code
- Positive: No siteId discovery needed (eliminates testing overhead)
- Neutral: Still need correct domain (no shortcuts possible)
- Caching: Can simplify cache keys (siteId no longer distinguishes regions)
Next Steps
- ✅ Production configuration complete
- ✅ Documentation complete
- ⏳ Integrate into main search script
- ⏳ Add region parameter to Apify Actor input
- ⏳ Test all 35 regions end-to-end
[2025-01-28] - Initial Research
Reverse Engineering
- Decompiled Android app v2024.16.1 using JADX-GUI
- Extracted HMAC authentication algorithm
- Discovered PointOfSaleId enum (120+ entries)
- Mapped typeahead API and parameters
Documentation Created
2501-hmac-authorization.md - Complete HMAC implementation2501-regionid-siteid-typeahead-api.md - Typeahead API documentation2501-api-parameters-reference.md - Complete parameter reference2501-pagination-pattern.md - Pagination strategies2501-sorting-and-filtering.md - Sort and filter options2501-id-mappings-reference.md - ID mapping strategies
Working Implementation
hmac_auth.py - Production-ready HMAC authenticationtests/test-search.py - End-to-end hotel search testtransformers/lodging_card.py - Hotel data transformation
Status
Successfully built working hotel search implementation for US market (www.expedia.com). All API requests authenticated and functional.
