mirror of
https://github.com/mblanke/holiday-travel-app.git
synced 2026-03-01 05:20:22 -05:00
Initial commit: Holiday Travel App with resort comparison, trip management, and multi-provider search
This commit is contained in:
270
API_RESORT_COMPARE.md
Normal file
270
API_RESORT_COMPARE.md
Normal file
@@ -0,0 +1,270 @@
|
||||
# Resort Comparison API - Direct Usage Examples
|
||||
|
||||
If you want to call the API directly (without PowerShell scripts), here are examples.
|
||||
|
||||
## API Endpoint
|
||||
|
||||
```
|
||||
POST http://localhost:4000/api/resort-compare
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## Request Format
|
||||
|
||||
```json
|
||||
{
|
||||
"resorts": [
|
||||
"Bahia Principe Luxury Sian Ka'an",
|
||||
"Secrets Akumal Riviera Maya",
|
||||
"Hyatt Zilara Cap Cana"
|
||||
],
|
||||
"departureDate": "2026-01-15",
|
||||
"origin": "YOW",
|
||||
"tripLength": 7,
|
||||
"preferences": {
|
||||
"beach": 10,
|
||||
"pool": 8,
|
||||
"golf": 3,
|
||||
"spa": 9,
|
||||
"food": 10,
|
||||
"nightlife": 6,
|
||||
"shopping": 4,
|
||||
"culture": 5,
|
||||
"outdoor": 8,
|
||||
"family": 7
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
```json
|
||||
{
|
||||
"comparisons": [
|
||||
{
|
||||
"resort": {
|
||||
"name": "Secrets Akumal Riviera Maya",
|
||||
"destination": "Akumal",
|
||||
"country": "Mexico",
|
||||
"airportCode": "CUN",
|
||||
"features": {
|
||||
"beach": 10,
|
||||
"pool": 9,
|
||||
"golf": 5,
|
||||
"spa": 9,
|
||||
"food": 9,
|
||||
"nightlife": 7,
|
||||
"shopping": 5,
|
||||
"culture": 6,
|
||||
"outdoor": 9,
|
||||
"family": 6
|
||||
},
|
||||
"tripAdvisorRating": 4.5,
|
||||
"tripAdvisorReviews": 9127,
|
||||
"priceRange": "$$$$$",
|
||||
"allInclusive": true
|
||||
},
|
||||
"matchScore": 938,
|
||||
"flightLinks": {
|
||||
"skyscanner": "https://www.skyscanner.ca/transport/flights/yow/cun/20260115/20260122/",
|
||||
"googleFlights": "https://www.google.com/travel/flights?q=flights%20from%20YOW%20to%20CUN%202026-01-15%20to%202026-01-22",
|
||||
"airCanada": "https://www.aircanada.com/ca/en/aco/home/book/travel.html?org1=YOW&dest1=CUN&departureDate1=2026-01-15&returnDate1=2026-01-22&tripType=2&lang=en-CA"
|
||||
},
|
||||
"estimatedFlightPrice": "$500-$800"
|
||||
}
|
||||
],
|
||||
"notFound": [],
|
||||
"flightInfo": {
|
||||
"origin": "YOW",
|
||||
"departureDate": "2026-01-15",
|
||||
"returnDate": "2026-01-22",
|
||||
"tripLength": 7
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## PowerShell Example
|
||||
|
||||
```powershell
|
||||
$data = @{
|
||||
resorts = @(
|
||||
"UNICO 20°87° Hotel Riviera Maya",
|
||||
"Hyatt Zilara Cap Cana"
|
||||
)
|
||||
departureDate = "2026-01-15"
|
||||
origin = "YOW"
|
||||
tripLength = 7
|
||||
preferences = @{
|
||||
beach = 10
|
||||
pool = 9
|
||||
spa = 9
|
||||
food = 10
|
||||
}
|
||||
} | ConvertTo-Json -Depth 3
|
||||
|
||||
$response = Invoke-RestMethod `
|
||||
-Uri "http://localhost:4000/api/resort-compare" `
|
||||
-Method POST `
|
||||
-Body $data `
|
||||
-ContentType "application/json"
|
||||
|
||||
# View results
|
||||
$response.comparisons | ForEach-Object {
|
||||
Write-Host "$($_.resort.name) - Score: $($_.matchScore)"
|
||||
Write-Host " Rating: $($_.resort.tripAdvisorRating)/5.0"
|
||||
Write-Host " Flights: $($_.flightLinks.skyscanner)"
|
||||
Write-Host ""
|
||||
}
|
||||
```
|
||||
|
||||
## cURL Example (Windows)
|
||||
|
||||
```bash
|
||||
curl.exe -X POST "http://localhost:4000/api/resort-compare" ^
|
||||
-H "Content-Type: application/json" ^
|
||||
-d "{\"resorts\":[\"Secrets Akumal Riviera Maya\"],\"departureDate\":\"2026-01-15\",\"origin\":\"YOW\",\"tripLength\":7,\"preferences\":{\"beach\":10,\"pool\":8}}"
|
||||
```
|
||||
|
||||
## Python Example
|
||||
|
||||
```python
|
||||
import requests
|
||||
import json
|
||||
|
||||
data = {
|
||||
"resorts": [
|
||||
"Bahia Principe Luxury Sian Ka'an",
|
||||
"Dreams Tulum Resort & Spa"
|
||||
],
|
||||
"departureDate": "2026-01-15",
|
||||
"origin": "YOW",
|
||||
"tripLength": 7,
|
||||
"preferences": {
|
||||
"beach": 10,
|
||||
"pool": 8,
|
||||
"spa": 9,
|
||||
"food": 10
|
||||
}
|
||||
}
|
||||
|
||||
response = requests.post(
|
||||
"http://localhost:4000/api/resort-compare",
|
||||
json=data
|
||||
)
|
||||
|
||||
results = response.json()
|
||||
|
||||
for comparison in results['comparisons']:
|
||||
resort = comparison['resort']
|
||||
print(f"{resort['name']} - Score: {comparison['matchScore']}")
|
||||
print(f" Rating: {resort['tripAdvisorRating']}/5.0 ({resort['tripAdvisorReviews']} reviews)")
|
||||
print(f" Flights: {comparison['flightLinks']['skyscanner']}")
|
||||
print()
|
||||
```
|
||||
|
||||
## Available Resorts in Database
|
||||
|
||||
### Mexico (CUN - Cancun Airport)
|
||||
- Bahia Principe Luxury Sian Ka'an
|
||||
- Catalonia Royal Tulum
|
||||
- Secrets Akumal Riviera Maya
|
||||
- UNICO 20°87° Hotel Riviera Maya
|
||||
- TRS Yucatán Hotel
|
||||
- Barcelo Maya Riviera
|
||||
- Valentin Imperial Riviera Maya
|
||||
- Grand Sirenis Riviera Maya
|
||||
- Dreams Tulum Resort & Spa
|
||||
|
||||
### Dominican Republic (PUJ - Punta Cana Airport)
|
||||
- Hyatt Zilara Cap Cana
|
||||
- Secrets Cap Cana
|
||||
- Dreams Onyx Resort & Spa
|
||||
- Royalton CHIC Punta Cana
|
||||
- Iberostar Grand Bávaro
|
||||
|
||||
## Field Descriptions
|
||||
|
||||
### Request Fields
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| resorts | string[] | Yes | Array of resort names (case-insensitive) |
|
||||
| departureDate | string | Yes | Date in YYYY-MM-DD format |
|
||||
| origin | string | No | IATA airport code (default: "YOW") |
|
||||
| tripLength | number | No | Number of nights (default: 7) |
|
||||
| preferences | object | No | Feature ratings 0-10 |
|
||||
|
||||
### Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| comparisons | array | Sorted by match score (highest first) |
|
||||
| notFound | string[] | Resorts not in database |
|
||||
| flightInfo | object | Summary of flight search parameters |
|
||||
|
||||
### Resort Object
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| name | string | Full resort name |
|
||||
| destination | string | City/area name |
|
||||
| country | string | Country name |
|
||||
| airportCode | string | 3-letter IATA code |
|
||||
| features | object | Ratings 0-10 for each feature |
|
||||
| tripAdvisorRating | number | Rating out of 5.0 |
|
||||
| tripAdvisorReviews | number | Number of reviews |
|
||||
| priceRange | string | $$$ to $$$$$ |
|
||||
| allInclusive | boolean | All-inclusive resort? |
|
||||
|
||||
## Error Responses
|
||||
|
||||
### Invalid Date Format
|
||||
```json
|
||||
{
|
||||
"error": "Invalid departureDate format. Use YYYY-MM-DD"
|
||||
}
|
||||
```
|
||||
|
||||
### Empty Resort List
|
||||
```json
|
||||
{
|
||||
"error": "At least one resort required"
|
||||
}
|
||||
```
|
||||
|
||||
### Invalid Preference Values
|
||||
```json
|
||||
{
|
||||
"error": "Preference values must be between 0 and 10"
|
||||
}
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Case-Insensitive**: Resort names are matched case-insensitively
|
||||
2. **Partial Matches**: Use exact names from the database
|
||||
3. **Multiple Requests**: You can make multiple requests with different preferences
|
||||
4. **Caching**: Results are not cached; each request is fresh
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Save to File (PowerShell)
|
||||
```powershell
|
||||
$response | ConvertTo-Json -Depth 10 | Out-File "resort_results.json"
|
||||
```
|
||||
|
||||
### Filter Results (PowerShell)
|
||||
```powershell
|
||||
# Only 5-star resorts
|
||||
$response.comparisons | Where-Object { $_.resort.tripAdvisorRating -eq 5.0 }
|
||||
|
||||
# Only high match scores
|
||||
$response.comparisons | Where-Object { $_.matchScore -gt 900 }
|
||||
|
||||
# Only Mexico resorts
|
||||
$response.comparisons | Where-Object { $_.resort.country -eq "Mexico" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Happy coding! 🏖️✈️
|
||||
Reference in New Issue
Block a user