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

```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! 🏖️✈️