holiday-travel-app/API_RESORT_COMPARE.md

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

{
  "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

{
  "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

$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)

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

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

{
  "error": "Invalid departureDate format. Use YYYY-MM-DD"
}

Empty Resort List

{
  "error": "At least one resort required"
}

Invalid Preference Values

{
  "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)

$response | ConvertTo-Json -Depth 10 | Out-File "resort_results.json"

Filter Results (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! 🏖️✈️