Design an HTTP API for Two‑Listing Split‑Stay Search
Context
You are building a search service for split stays: when a guest's date range cannot be covered by a single listing, find pairs of listings that together cover the entire stay with exactly one move. The client supplies a date range and a set of candidate listings along with their available day numbers within that range.
Assumptions to make the task self-contained:
-
Trip is defined by check-in date and check-out date. Nights count N = (check_out - check_in) in the requested time zone.
-
Available day numbers are 1-based indices over the trip nights: 1..N. Night i corresponds to the overnight between calendar day i and i+1 in the chosen time zone.
-
A split at day s means: Listing A covers nights 1..(s-1); Listing B covers nights s..N. The move occurs on the morning of day s.
-
Optionally, a cleaning-day gap of up to g nights may be allowed between A and B.
Requirements
-
Specify HTTP endpoint(s), request/response schemas, and query parameters (e.g., start_date, end_date, start_day, end_day, max_results, sort_by).
-
Define pagination, idempotency, and how to represent multiple valid split days per pair.
-
Describe ranking, tie-breaking, and deduplication rules.
-
Describe caching and rate limiting.
-
Explain how the service achieves low latency at scale (e.g., precomputed prefix/suffix coverage, interval indexes).
-
Handle edge cases: time zones, minimum stays, cleaning-day gaps, overlapping availability, invalid inputs.
-
Provide example success and error payloads.