Fix Google competitor pricing lookup and starting-rate parsing

DATA_ACCURACY_REVIEW.md

@@ -0,0 +1,29 @@
+# Hotel Rate Radar: accuracy review
+
+Reviewed 21 September 2026. This is a code and provider-documentation review, not a certification of live hotel prices.
+
+## Why the previous output could mislead
+
+The previous parser could count Google's lowest aggregate as an additional seller and combine unrelated property details. Its competitor benchmark used weights while calling the result an average. Room current prices could be derived from a base-price ladder, and assumed occupancy/pickup looked like actual inputs. Those paths are corrected. The model still applies heuristic recommendation adjustments; suggestions are clearly distinct from observed prices.
+
+## Public data route
+
+SerpApi documents hotel-search parameters and a property-token detail endpoint. Detail responses can contain sellers, nested rooms and nested rate options; per-night amounts and stay totals are separate. This update uses nested room offers with an explicit before-tax nightly amount, verifies the echoed stay parameters and checks property identity/location again after detail lookup. The fresh option requests no_cache=true; ordinary provider caching may last an hour.
+
+Sources: [Hotel search API](https://serpapi.com/google-hotels-api), [Property details schema](https://serpapi.com/google-hotels-property-details).
+
+Each seller contributes once, using its lowest accepted quote. Their arithmetic mean is an advertised-rate indicator. Competitor averages use each hotel's seller average with equal weight. Unavailable observations do not enter the denominator. Known member/mobile/package/breakfast/nonrefundable inclusions are excluded; absent cancellation data remains explicitly unverified, so this is not a fully normalized refundable-rate comparison.
+
+## Why there is no promised scraping fallback
+
+Earlier access checks encountered a Cloudflare challenge on Surf City's website and a challenge on Booking.com. Loading an Expedia homepage does not establish access to a date-specific shopping feed. No reliable independent direct scraper was demonstrated. This package uses provider-returned seller offers, which may include an official booking link, and does not bypass challenges. It will return unavailable rather than substitute an unrelated or incomplete quote.
+
+Booking.com's Demand pricing endpoints and Expedia Rapid Shopping provide structured rate data through authenticated integrations. These would require a separate authorized integration; this ZIP does not claim to implement them. [Booking.com pricing](https://developers.booking.com/demand/docs/accommodations/prices-accommodations), [Expedia Shopping](https://developers.expediagroup.com/rapid/lodging/shopping/about-shopping-api).
+
+Google's ARI integration accepts hotel-supplied rates and inventory; it is not a general free competitor price-reading endpoint. [Google ARI overview](https://developers.google.com/hotels/hotel-prices/dev-guide/ari-overview).
+
+## Verification and remaining limits
+
+Offline regression checks cover nested room rates, duplicate aliases, aggregate exclusion, missing tax/room rejection, wrong location, echoed query mismatch, empty-market handling, neutral missing demand inputs, no invented current room prices and the bulk-request gate. The complete Gradio application imports successfully with the pinned version.
+
+No live response was tested with the Space's API secret. Strict validation can leave many prices unavailable, including properties that advertise bed types differently. Advertised 1 Queen matches do not establish identical amenities or cancellation conditions. Prices may change after retrieval; confirm final totals at the seller. This build does not access ASI, infer sold-out status, or measure exact remaining rooms from public pages. Manual fallback prices remain estimates entered by the operator.