Extrae hoteles de Booking.com con precios, calendario de disponibilidad (61 días), búsqueda multi-destino y detección incremental de cambios de precio.

Precio base: $0.0025 por hotel (17% más barato que el incumbente a $0.003). Diferenciador principal: calendario diario de precios + modo monitor delta para Revenue Management.

---

Modos de operación

SEARCH (modo por defecto)

Extrae hoteles para uno o varios destinos con paginación automática. Emite un item hotel por propiedad encontrada.

{
  "destinations": ["Barcelona", "Madrid"],
  "checkin": "2026-09-01",
  "checkout": "2026-09-03",
  "adults": 2,
  "mode": "SEARCH",
  "maxResults": 100
}

CALENDAR

Para una lista de hotelIds (del output de SEARCH), extrae precio y disponibilidad día por día para los próximos 61 días. Ideal para Revenue Management.

{
  "mode": "CALENDAR",
  "hotelIds": ["es/arts-barcelona", "es/hotel-w-barcelona"],
  "calendarDays": 61,
  "currency": "USD"
}

Formato de hotelIds recomendado: "cc/pageName" (ej: "es/arts-barcelona"). Los valores de countryCode y pageName están disponibles en cada item del dataset de SEARCH.

MONITOR

Combina SEARCH + CALENDAR + detección de cambios vs snapshot anterior. Emite solo los cambios detectados (delta-event). Ideal para programar runs diarios.

{
  "destinations": ["Barcelona"],
  "mode": "MONITOR",
  "kvStoreName": "booking-monitor-bcn",
  "deltaThreshold": 5
}

---

Output — tipos de item en el dataset

El dataset mezcla tres tipos de item diferenciados por el campo _type.

hotel — datos del hotel

Campo	Tipo	Descripción
hotelId	integer	ID interno de Booking.com
pageName	string	Slug de URL (ej: "arts-barcelona")
countryCode	string	ISO 2 letras
url	string	URL canónica del hotel
name	string	Nombre del hotel
starRating	float	1.0-5.0 (null si no aplica)
reviewScore	float	0-10
reviewCount	integer	Número de reseñas
priceTotal	float	Precio total de la estadía en currency
pricePerNight	float	Calculado: priceTotal / nights
priceBeforeDiscount	float	Precio antes del descuento (null si sin descuento)
discountPercent	float	Porcentaje de descuento calculado
currency	string	ISO 4217
freeCancellation	boolean	Tiene cancelación gratuita
freeCancellationUntil	string	ISO 8601 deadline
isSoldOut	boolean	Sin disponibilidad para las fechas
city, country	string	Ubicación
distanceFromCenter	string	Texto: "1.2 km from centre"
isPreferred, isPreferredPlus	boolean	Badges de partner preferido
isSustainable	boolean	Certificado ecológico
mealPlan	string	Ej: "Breakfast included" (null si sin plan)
bedTypes	array	[{type: string, count: integer}]

calendar-row — precio por día

Campo	Tipo	Descripción
hotelId	integer	ID del hotel
date	string	YYYY-MM-DD (fecha de checkin)
available	boolean	Disponibilidad para ese día
price	float	Precio promedio por noche (null si no disponible)
currency	string	ISO 4217 del input
minLengthOfStay	integer	Noches mínimas requeridas

delta-event — cambio detectado (solo modo MONITOR)

Campo	Tipo	Descripción
changeType	string	PRICE_CHANGE, AVAILABILITY_CHANGE, NEW_HOTEL, HOTEL_REMOVED, FREE_CANCELLATION_EXPIRING
previousPrice	float	Precio en snapshot anterior
currentPrice	float	Precio actual
priceDeltaPercent	float	Cambio porcentual
hoursUntilCancellationDeadline	float	Solo en FREE_CANCELLATION_EXPIRING

---

Precios (Pay per Event)

Evento	Precio	Cuándo se cobra
Actor start	$0.001	Una vez por run (automático)
hotel-scraped	$0.0025	Por hotel extraído en modo SEARCH/MONITOR
calendar-row	$0.003	Por fila de día de calendario
delta-event	$0.001	Por cambio detectado en modo MONITOR

Ejemplos de costo:

• 100 hoteles en SEARCH: $0.001 + (100 × $0.0025) = $0.251 (vs $0.301 del incumbente)
• 100 hoteles con calendario 61 días: $0.251 + (100 × 61 × $0.003) = $18.55
• Run diario de MONITOR sin cambios: $0.001 (solo el actor-start)

---

Requisitos técnicos

Proxies residenciales (obligatorios)

Booking.com usa AWS WAF con JS challenge. Las IPs de datacenter reciben HTTP 202 y no obtienen datos.

Configuración recomendada en el input:

{
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}

Sin proxies residenciales, el actor retornará 0 resultados. No es un bug del actor — es una restricción de la fuente.

Memoria mínima

512 MB (el bootstrap de Playwright requiere al menos 512 MB).

---

Arquitectura técnica

Flujo en dos fases:

1. Session Bootstrap (Playwright, 1 vez por run): Navega a booking.com/searchresults.html con proxy residencial, resuelve el JS challenge de AWS WAF, extrae el cookie aws-waf-token y el X-Booking-CSRF-Token.

2. Data Collection (HTTP puro con fetch): Pagina POST /dml/graphql → FullSearch (25 resultados/página). Para el calendario: POST /dml/graphql → AvailabilityCalendar (61 días). Reutiliza la cookie y el token de la Fase 1.

El token se refresca automáticamente cada 25 minutos en runs largos.

---

Límites conocidos

• Booking.com limita los resultados de búsqueda a ~1000 propiedades por destino independientemente de la paginación. Para cobertura completa de ciudades grandes (Londres, París), correr con diferentes valores de sortBy (POPULARITY, PRICE, REVIEW_SCORE) y combinar los datasets.
• El calendario de precios devuelve máximo 61 días hacia adelante (límite de la API de Booking.com).
• El campo photoUrl está en null — las fotos no están disponibles en el response de FullSearch GQL. Para fotos se requiere una request adicional de detalle de hotel (no implementado en v1.0).

---

Tasa de éxito y mantenimiento

Tasa de éxito esperada: 90-95% en runs normales con proxies residenciales. El 5-10% restante corresponde a refrescos de WAF token (automáticos) o IPs del pool que Booking.com bloquea temporalmente.

Mantenimiento: El actor es monitoreado mensualmente. Los cambios de schema GQL de Booking.com ocurren 1-2 veces por año. Si el actor retorna campos vacíos o falla con "schema validation failed", abrir un issue en el repositorio.

---

---

Booking.com Hotels Scraper — Calendar + Delta Monitor (English)

Extracts Booking.com hotels with pricing, 61-day availability calendar, multi-destination search, and incremental price change monitoring.

Base price: $0.0025 per hotel — 17% cheaper than the leading competitor at $0.003. Key differentiator: daily calendar pricing + delta monitor mode for Revenue Management workflows.

Quick start

{
  "destinations": ["Barcelona"],
  "checkin": "2026-09-01",
  "checkout": "2026-09-03",
  "adults": 2,
  "mode": "SEARCH",
  "maxResults": 100,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}

Requirements

• Residential proxies are required. Booking.com blocks datacenter IPs with an AWS WAF JavaScript challenge. Configure proxyConfiguration with "apifyProxyGroups": ["RESIDENTIAL"].
• Minimum memory: 512 MB (Playwright session bootstrap).

Known limits

• Booking.com caps search results at approximately 1,000 properties per destination.
• Availability calendar returns a maximum of 61 days ahead.
• photoUrl field is null in v1.0 — hotel photos require an additional detail request not yet implemented.