Compsets¶

GET /api/v1/listings/<id>/compset/

Scope: compsets:read
Description: Get the precomputed competitive set for a listing.

Try it out

Explore schemas and make live requests in the Swagger UI.

What is a compset?¶

A compset (Competitive Set) is a group of comparable nearby listings used to benchmark a property's pricing and performance. Beyond computes one daily for every connected listing using haversine geo-distance plus Gower similarity over bedrooms, bathrooms, room/property type, and market percentile.

Get Compset for a Listing¶

Returns the precomputed compset for a listing's primary channel listing, ordered by rank ascending (rank 1 = most similar). Each member carries enough property attributes that a partner can render a side-by-side comparison in a single round trip.

Returns 404 when no compset has been computed yet (for example, a newly connected listing where the daily pipeline has not landed).

Optional enrichments — `?include=`¶

Comma-separated, repeatable:

median_curve — adds the daily median nightly price across compset members for the requested date range. Combine with start_date and end_date (defaults: today → today + 90 days, max 180-day range). Heavier query — partners running real-time UIs should cache results.
revpar — adds the listing's RevPAN compared to the compset's RevPAN (perf-vs-compset ratio). Returned with available: false if no comparison snapshot exists yet for this channel listing.

Notable Fields¶

members[].rank — 1-based ordering; rank 1 is closest to the base listing.
members[].distance — Composite Gower similarity (lower = more similar, dimensionless).
members[].haversine-km — Great-circle distance to the base listing, in kilometers.
members[].market-percentile-tag — Coarse pricing tier within the market (market_p25, market_p50, market_p75).
source — The base listing's features that anchored the similarity search.
computed-at — When the precomputed row was last refreshed by Beyond's daily pipeline.

Use cases¶

Three scenarios partners can build on top of a single call to this endpoint:

Market pricing pacing. Combine members[] with the opt-in median-price-curve.points[] to chart own nightly rates vs. the local compset median over the next 90 days — gaps where the operator is materially above/below the market are immediately visible.
Competitor comparison. Use source and members[] together to render a comparison table (bedrooms, bathrooms, star rating, amenities, distance) and highlight where the base listing is below the cluster.
Performance KPI. Use the opt-in revpar block to surface a single gauge (e.g. perf-vs-compset < 0.9 red, 0.9–1.1 amber, > 1.1 green) per listing, rolled up to a portfolio scorecard.

Compound documents¶

This endpoint does not currently sideload via JSON:API ?include= relationships. The include= query parameter is reserved for the opt-in enrichments described above; partners should not expect JSON:API sideload semantics here.

Errors¶

Status	Cause
`400`	Invalid `include` value, malformed `start_date`/`end_date`, or range > 180 days.
`401`	Missing or invalid bearer token.
`403`	Token does not have the `compsets:read` scope, or partner credential lacks privileges on the listing.
`404`	Listing not owned by the application, has no primary channel listing, or has no precomputed compset row yet.