Princess Cruises Scraper

Apify actor for scraping cruise data from Princess Cruises website.

Features

• Fetches cruise itineraries and pricing data from Princess Cruises API
• Supports multiple regions: USA, UK
• Handles pagination and batch pricing requests
• Extracts lowest available prices (prioritizes Interior cabins)
• Includes cabin availability information
• Retry logic with exponential backoff

API Structure

The scraper makes two main API calls. Note: Different endpoints and formats for different regions!

1. Itineraries API

US Market:

• GET https://gw.api.princess.com/pcl-web/api/cruisesearch/v1/product?pageSize=500

UK Market:

• GET https://gw.api.princess.com/pcl-web/internal/resdb/p1.0/products?agencyCountry=GB&cruiseType=C&voyageStatus=A&webDisplay=Y&promoFilter=all&light=false

Returns:

• Product/itinerary IDs
• Cruise IDs (individual sailings)
• Ship information
• Port details
• Sailing dates and durations

2. Pricing API

All Markets (same endpoint):

• POST https://gw.api.princess.com/pcl-web/internal/caps/pc/pricing/v1/cruises

Returns:

• Prices per cabin category
• Availability status
• Guest pricing details
• Promotional information

Pricing Format Differences:

• US: Uses averageGuestPrice field directly
• UK: Uses guests[0].fare field (no averageGuestPrice)
• US: Has igvtIncluded and rcfeIncluded flags
• UK: Has tfpeIncluded flag instead

Data Mapping

• itineraryId = products.id (from first API)
• cruiseId = cruises.id (from both APIs)
• price.amount = Lowest categories[].averageGuestPrice (prioritizes "IB" Interior category)
• stateroomPricing = ALL categories[] with prices (IB, O5, DH, C2, S9, etc.)

Cabin Categories Extracted

The scraper extracts all available cabin types with their prices, availability, and cabin counts:

US Market Codes:

• IB, IF, IE - Interior (Inside cabins)
• O5, OB, OC - Oceanview
• DH - Deluxe Balcony
• BA, BB - Balcony
• C2 - Club Class Mini-Suite
• MC - Mini-Suite
• S9, S8, S7 - Suite

UK Market Codes:

• IF - Interior
• OF - Oceanview
• BF, BE - Balcony
• ME - Mini-Suite
• S6, S4 - Suite

Each cabin type includes:

• Price per person
• Currency
• Availability (e.g., "9+", "2", "1")
• Number of available cabins

Note: Pricing is extracted from averageGuestPrice (US/AUS) or guests[0].fare (UK).

Configuration

Input Parameters

• region (required): Locale to scrape - en_US or en_GB
• maxRows (optional): Maximum number of results (default: 500)
• maxRequestRetries (optional): Number of retries for failed requests (default: 5)
• requestHandlerTimeoutSecs (optional): Request timeout in seconds (default: 30)
• useApifyProxy (optional): Use Apify proxy (default: false)
• proxyUrl (optional): Custom proxy URL (format: http://user:pass@proxy.com:port)
• apifyProxyGroups (optional): Apify proxy groups (default: ["RESIDENTIAL"])
• apifyProxyCountryCode (optional): Proxy country code (e.g., US, GB, AU) - auto-matches region if not set

Output Schema

Output format matches Royal Caribbean and NCL standard for compatibility with unified data handlers:

{
  "cruiseId": "1542",
  "itineraryId": "MLR070",
  "title": "Mexican Riviera",
  "description": "Mexican Riviera",
  "shipName": "Royal Princess",
  "shipId": "RP",
  "departurePort": {
    "name": "Los Angeles, California",
    "code": "LAX"
  },
  "arrivalPort": {
    "name": "Los Angeles, California",
    "code": "LAX"
  },
  "departureDate": "2025-11-29",
  "arrivalDate": "2025-12-06",
  "duration": "7 nights",
  "price": {
    "amount": "229",
    "currency": "USD"
  },
  "portsOfCall": [
    { "name": "Los Angeles, California", "day": "Day 1" },
    { "name": "Cabo San Lucas, Mexico", "day": "Day 2" }
  ],
  "availabilityStatus": "9+",
  "destinationNames": ["Los Angeles, California", "Cabo San Lucas, Mexico", ...],

  // Dynamic pricing fields for all cabin categories
  "price_USD_IB": "229",
  "classification_USD_IB": "Interior",
  "roomTypeId_USD_IB": "IB",
  "availability_USD_IB": "9+",
  "availableCabins_USD_IB": "13",

  "price_USD_O5": "569",
  "classification_USD_O5": "Oceanview",
  "roomTypeId_USD_O5": "O5",
  "availability_USD_O5": "9+",
  "availableCabins_USD_O5": "11",

  "price_USD_DH": "799",
  "classification_USD_DH": "Deluxe Balcony",
  "roomTypeId_USD_DH": "DH",
  "availability_USD_DH": "9+",
  "availableCabins_USD_DH": "13",

  "price_USD_C2": "699",
  "classification_USD_C2": "Club Class Mini-Suite",
  "roomTypeId_USD_C2": "C2",
  "availability_USD_C2": "9+",
  "availableCabins_USD_C2": "14",

  "price_USD_S9": "2629",
  "classification_USD_S9": "Suite",
  "roomTypeId_USD_S9": "S9",
  "availability_USD_S9": "1",
  "availableCabins_USD_S9": "1",

  // ... (more dynamic fields as available)
  "platform": "princess-en-US",
  "company": "princess",
  "region": "US",
  "locale": "en-US",
  "currency": "USD",
  "date": "2025-11-24T...",
  "source_url": "https://www.princess.com/itinerary-details/?voyageCode=1542"
}

Development

Local Setup

# Install dependencies
npm install

# Run locally
npm run start:dev

# Build
npm run build

# Lint
npm run lint

Deploy to Apify

# Login to Apify
apify login

# Push to Apify
apify push

Implementation Details

Region-Specific Configuration

US Market (USA):

• Itineraries: /pcl-web/api/cruisesearch/v1/product
• Booking Company: PC
• Home City: LAX
• Border Countries: CA, PR, MX, VI, BM, UN
• DSM Region: 09, District: 0D
• Pricing uses averageGuestPrice

UK Market (GBR):

• Itineraries: /pcl-web/internal/resdb/p1.0/products?agencyCountry=GB...
• Booking Company: PO (not PC!)
• Home City: LON
• Border Countries: GB, GI, MT, IE
• DSM Region: R0, District: 00
• Pricing uses guests[0].fare
• Has creditCardChargeFeesFlag and internationalFaxFlag

Price Selection Logic

The scraper prioritizes Interior cabin categories (IB for US, IF for UK) as they typically offer the lowest price. If not available, it selects the category with the lowest price across all cabin types. Supports both US pricing format (averageGuestPrice) and UK format (guests[0].fare).

Batch Processing

• Fetches all itineraries in one request (up to 500)
• Fetches pricing in batches of 50 cruises at a time
• Implements delays between batches to avoid rate limiting

Error Handling

• Retry logic with exponential backoff for failed requests
• Skips cruises without pricing data
• Continues processing on partial failures
• Detailed error logging for debugging

Notes

• Princess Cruises API uses YYYYMMDD date format, converted to ISO format in output
• Session ID is generated for each scraper run
• Ship names are mapped from ship codes
• Port names are mapped from port codes