The Compsets API from Beyond — 2 operation(s) for compsets.
openapi: 3.1.1
info:
title: Beyond Pricing Public Accounts Compsets API
version: 2.0.0
description: Bearer-protected API for third-party integrations. Supports OAuth2 client credentials and personal access tokens. Follows JSON:API specification.
tags:
- name: Compsets
paths:
/api/v1/compsets/:
get:
operationId: list_compsets
description: "List the comp sets visible to the authenticated client.\n\n**Required scope:** `compsets:read`\n\n**Pagination:** `page[number]` and `page[size]`.\n\n**Filtering:** `filter[owner]=<user_id>`, `filter[listing]=<id>`,\n`filter[kind]=custom|connected`. `filter[owner]` is only meaningful for\nfull-access partner tokens; user-scoped tokens already see one user.\n\n**Sorting:** `sort=created-at` (default `-created-at`) or `sort=title`;\nprefix with `-` for descending.\n\n**Compound documents (sideloading):** Use the `include` query parameter\nto embed related resources (JSON:API compound documents). Supported:\n- `owner` - the user who owns the comp set\n- `listing` - the Beyond listing the comp set is anchored to (`null` for\n `custom` comp sets)\n\n**Example:** `GET /api/v1/compsets/?include=owner,listing`\n\nEach entry is a lightweight summary (counts, title, `kind`, timestamps).\nFetch `GET /compsets/{id}/` for the full enriched comp set."
summary: List comp sets
parameters:
- name: sort
required: false
in: query
description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)'
schema:
type: array
items:
type: string
enum:
- created-at
- -created-at
- title
- -title
explode: false
- in: query
name: filter[owner]
schema:
type: number
- in: query
name: filter[listing]
schema:
type: number
- in: query
name: filter[kind]
schema:
type: string
enum:
- connected
- custom
description: '* `custom` - Custom
* `connected` - Connected'
- name: page[number]
required: false
in: query
description: A page number within the paginated result set.
schema:
type: integer
- name: page[size]
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- in: query
name: include
schema:
type: array
items:
type: string
enum:
- owner
- listing
description: include query parameter to allow the client to customize which related resources should be returned.
explode: false
- in: query
name: fields[compsets]
schema:
type: array
items:
type: string
enum:
- listing-id
- kind
- title
- member-count
- created-at
- updated-at
- owner
- listing
description: endpoint return only specific fields in the response on a per-type basis by including a fields[TYPE] query parameter.
explode: false
tags:
- Compsets
security:
- oauth2:
- compsets:read
- personalAccessToken: []
responses:
'200':
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/PaginatedCompsetSummaryList'
description: ''
'401':
description: Unauthorized - invalid or missing bearer token
'403':
description: Forbidden
'429':
description: Rate limit exceeded
'500':
description: Internal server error
/api/v1/compsets/{compset_id}/:
get:
operationId: get_compset
description: 'Return one comp set by id, fully enriched.
**Required scope:** `compsets:read`
Returns the comp set with members enriched across Airbnb, Vrbo, and
Booking.com, the comp set''s headline metrics over the next 30 and 90
days, and a `performance` block comparing the listing to the aggregated
compset benchmark over `start_date`..`end_date` (defaults: today →
today+90d, max range 180 days).
The `kind` field distinguishes `custom` and `connected` comp sets; for
`custom` comp sets some `source` fields and the main-listing
performance metrics are `null`.
Returns **404** when no comp set with that id is visible to the client.'
summary: Get a comp set by id
parameters:
- in: path
name: compset_id
schema:
type: integer
required: true
- in: query
name: start_date
schema:
type: string
description: First stay date (YYYY-MM-DD) for the performance comparison. Defaults to today.
- in: query
name: end_date
schema:
type: string
description: Last stay date (YYYY-MM-DD) for the performance comparison. Defaults to today + 90 days. Range must not exceed 180 days.
- in: query
name: fields[compsets]
schema:
type: array
items:
type: string
enum:
- id
- listing-id
- kind
- title
- matched-airbnb-id
- created-at
- updated-at
- source
- members
- performance
description: endpoint return only specific fields in the response on a per-type basis by including a fields[TYPE] query parameter.
explode: false
tags:
- Compsets
security:
- oauth2:
- compsets:read
- personalAccessToken: []
responses:
'200':
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/CompsetResponse'
description: ''
'400':
description: Validation error
'401':
description: Unauthorized - invalid or missing bearer token
'403':
description: Forbidden
'404':
description: Not found - resource does not exist
'429':
description: Rate limit exceeded
'500':
description: Internal server error
components:
schemas:
PaginatedCompsetSummaryList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/CompsetSummary'
links:
type: object
description: Pagination links for the primary data. These keys MUST be used for pagination links; each MUST be omitted or `null` when that link is unavailable. Values follow JSON:API link rules (URI string, link object, or null). https://jsonapi.org/format/#fetching-pagination https://jsonapi.org/format/#document-links
properties:
first:
type:
- string
- 'null'
format: uri
example: http://example.com/articles?page%5Bsize%5D=10&page%5Bnumber%5D=1
description: 'The first page of data. A JSON:API link: URI string, link object, or null. See https://jsonapi.org/format/#document-links.'
last:
type:
- string
- 'null'
format: uri
example: http://example.com/articles?page%5Bsize%5D=10&page%5Bnumber%5D=9
description: 'The last page of data. A JSON:API link: URI string, link object, or null. See https://jsonapi.org/format/#document-links.'
prev:
type:
- string
- 'null'
format: uri
example: http://example.com/articles?page%5Bsize%5D=10&page%5Bnumber%5D=1
description: 'The previous page of data. A JSON:API link: URI string, link object, or null. See https://jsonapi.org/format/#document-links.'
next:
type:
- string
- 'null'
format: uri
example: http://example.com/articles?page%5Bsize%5D=10&page%5Bnumber%5D=3
description: 'The next page of data. A JSON:API link: URI string, link object, or null. See https://jsonapi.org/format/#document-links.'
additionalProperties: false
meta:
type: object
description: Non-standard meta-information. Page-number stacks often nest totals under `pagination`. JSON:API does not define these keys. Servers MAY add other `meta` members; this schema documents the usual djangorestframework-json-api shape only. https://jsonapi.org/format/#document-meta
properties:
pagination:
type: object
description: Typical page-number metadata from djangorestframework-json-api; not mandated by JSON:API.
properties:
count:
type: integer
minimum: 0
example: 42
description: Total number of resources across all pages.
page:
type: integer
minimum: 1
example: 2
description: Current page number (1-based).
pages:
type: integer
minimum: 0
example: 5
description: Total number of pages.
additionalProperties: false
additionalProperties: false
required:
- data
Compset:
type: object
required:
- type
- id
additionalProperties: false
properties:
type:
allOf:
- $ref: '#/components/schemas/TypeF0bEnum'
description: The [type](https://jsonapi.org/format/#document-resource-object-identification) member is used to describe resource objects that share common attributes and relationships.
id: {}
attributes:
type: object
properties:
listing-id:
type:
- integer
- 'null'
description: Beyond listing id the comp set is anchored to (null for custom).
kind:
enum:
- custom
- connected
type: string
description: 'Comp set kind: `custom` (no Beyond listing) or `connected` (anchored to a Beyond listing). Custom comp sets have null `source.min-stay`/`base-price`/`health-score`/`market` and a null `performance.main-listing-metrics`.
* `custom` - Custom
* `connected` - Connected'
title:
type:
- string
- 'null'
description: Comp set title.
matched-airbnb-id:
type:
- string
- 'null'
description: Airbnb id Beyond matched to the base listing, when available.
created-at:
type:
- string
- 'null'
format: date-time
description: When the comp set was created.
updated-at:
type:
- string
- 'null'
format: date-time
description: When the comp set was last updated.
source:
$ref: '#/components/schemas/CompsetSource'
members:
type: array
items:
$ref: '#/components/schemas/CompsetMember'
performance:
allOf:
- $ref: '#/components/schemas/CompsetPerformance'
description: The listing's metrics vs. the aggregated compset benchmark over `start_date`..`end_date`.
required:
- kind
- source
- members
- performance
CompsetSourceMetrics:
type: object
description: Headline metrics for the base listing over the next 30 and 90 days.
properties:
thirty-day-price:
type:
- number
- 'null'
format: double
description: Average posted nightly rate, next 30 days.
ninety-day-price:
type:
- number
- 'null'
format: double
description: Average posted nightly rate, next 90 days.
thirty-day-adr:
type:
- number
- 'null'
format: double
description: Average booked rate (ADR), next 30 days.
ninety-day-adr:
type:
- number
- 'null'
format: double
description: Average booked rate (ADR), next 90 days.
thirty-day-booked:
type:
- number
- 'null'
format: double
description: Occupancy percentage, next 30 days.
ninety-day-booked:
type:
- number
- 'null'
format: double
description: Occupancy percentage, next 90 days.
thirty-day-availability:
type:
- number
- 'null'
format: double
description: Availability percentage, next 30 days.
ninety-day-availability:
type:
- number
- 'null'
format: double
description: Availability percentage, next 90 days.
thirty-day-min-stays:
type:
- integer
- 'null'
description: Minimum stay, next 30 days.
ninety-day-min-stays:
type:
- integer
- 'null'
description: Minimum stay, next 90 days.
rating:
type:
- number
- 'null'
format: double
description: Aggregate guest star rating.
reviews-count:
type:
- integer
- 'null'
description: Number of guest reviews.
average-service-fee:
type:
- number
- 'null'
format: double
description: Average service fee (Airbnb-only; null on other channels).
CompsetPerformanceAggregateMetrics:
type: object
description: The aggregated compset benchmark over the requested date range.
properties:
average-posted-rate:
type:
- number
- 'null'
format: double
description: Compset average posted nightly rate.
occupancy:
type:
- number
- 'null'
format: double
description: Compset average occupancy percentage.
average-min-stay:
type:
- number
- 'null'
format: double
description: Compset average minimum stay.
average-booked-rate:
type:
- number
- 'null'
format: double
description: Compset average booked rate (ADR).
adj-occupancy:
type:
- number
- 'null'
format: double
description: Compset average adjusted occupancy percentage.
number-of-nearby-listings:
type:
- integer
- 'null'
description: Number of members contributing to the aggregate.
CompsetMemberMetrics:
type: object
description: Metrics for a single comp-set member over the next 30 and 90 days.
properties:
thirty-day-adr:
type:
- number
- 'null'
format: double
description: Average booked rate (ADR), next 30 days.
ninety-day-adr:
type:
- number
- 'null'
format: double
description: Average booked rate (ADR), next 90 days.
thirty-day-booked:
type:
- number
- 'null'
format: double
description: Occupancy percentage, next 30 days.
ninety-day-booked:
type:
- number
- 'null'
format: double
description: Occupancy percentage, next 90 days.
thirty-day-availability:
type:
- number
- 'null'
format: double
description: Availability percentage, next 30 days.
ninety-day-availability:
type:
- number
- 'null'
format: double
description: Availability percentage, next 90 days.
thirty-day-min-stays:
type:
- integer
- 'null'
description: Minimum stay, next 30 days.
ninety-day-min-stays:
type:
- integer
- 'null'
description: Minimum stay, next 90 days.
thirty-day-adj-occupancy:
type:
- number
- 'null'
format: double
description: Adjusted occupancy percentage, next 30 days.
ninety-day-adj-occupancy:
type:
- number
- 'null'
format: double
description: Adjusted occupancy percentage, next 90 days.
thirty-day-booked-rate:
type:
- number
- 'null'
format: double
description: Booked rate, next 30 days.
ninety-day-booked-rate:
type:
- number
- 'null'
format: double
description: Booked rate, next 90 days.
base-price:
type:
- number
- 'null'
format: double
description: Average base price over the next 365 days.
currency:
type:
- string
- 'null'
description: ISO currency code for the member's prices.
rating:
type:
- number
- 'null'
format: double
description: Aggregate guest star rating.
reviews-count:
type:
- integer
- 'null'
description: Number of guest reviews.
average-service-fee:
type:
- number
- 'null'
format: double
description: Average service fee (Airbnb-only; null on other channels).
CompsetPerformanceListingMetrics:
type: object
description: The base listing's metrics over the requested date range.
properties:
average-posted-rate:
type:
- number
- 'null'
format: double
description: Average posted nightly rate over the range.
occupancy:
type:
- number
- 'null'
format: double
description: Occupancy percentage over the range.
average-min-stay:
type:
- number
- 'null'
format: double
description: Average minimum stay over the range.
average-booked-rate:
type:
- number
- 'null'
format: double
description: Average booked rate (ADR) over the range.
adj-occupancy:
type:
- number
- 'null'
format: double
description: Adjusted occupancy percentage over the range.
CompsetPerformance:
type: object
description: Date-ranged comparison of the base listing vs. the compset benchmark.
properties:
start-date:
type: string
format: date
description: First stay date in the range.
end-date:
type: string
format: date
description: Last stay date in the range.
currency:
type: string
description: ISO currency code for the figures.
main-listing-metrics:
oneOf:
- $ref: '#/components/schemas/CompsetPerformanceListingMetrics'
- type: 'null'
description: The base listing's metrics over the range. `null` for `custom` comp sets, which have no Beyond listing.
aggregated-metrics:
$ref: '#/components/schemas/CompsetPerformanceAggregateMetrics'
required:
- aggregated-metrics
- currency
- end-date
- start-date
TypeF0bEnum:
type: string
enum:
- compsets
CompsetResponse:
type: object
properties:
data:
$ref: '#/components/schemas/Compset'
required:
- data
CompsetSummary:
type: object
required:
- type
- id
additionalProperties: false
properties:
type:
allOf:
- $ref: '#/components/schemas/TypeF0bEnum'
description: The [type](https://jsonapi.org/format/#document-resource-object-identification) member is used to describe resource objects that share common attributes and relationships.
id:
type: integer
attributes:
type: object
properties:
listing-id:
type:
- integer
- 'null'
readOnly: true
description: Beyond listing id the comp set is anchored to (null for custom).
kind:
enum:
- custom
- connected
type: string
description: 'Comp set kind: `custom` or `connected`.'
readOnly: true
title:
type:
- string
- 'null'
readOnly: true
description: Comp set name.
member-count:
type: integer
readOnly: true
description: Total number of members across channels.
created-at:
type: string
format: date-time
readOnly: true
updated-at:
type: string
format: date-time
readOnly: true
relationships:
type: object
properties:
owner:
type: object
properties:
data:
type: object
properties:
id:
type: integer
type:
type: string
enum:
- users
title: Resource Type Name
description: The [type](https://jsonapi.org/format/#document-resource-object-identification) member is used to describe resource objects that share common attributes and relationships.
required:
- id
- type
required:
- data
description: The identifier of the related object.
title: Owner
readOnly: true
listing:
type: object
properties:
data:
type: object
properties:
id:
type: integer
type:
type: string
enum:
- listings
title: Resource Type Name
description: The [type](https://jsonapi.org/format/#document-resource-object-identification) member is used to describe resource objects that share common attributes and relationships.
required:
- id
- type
required:
- data
description: The identifier of the related object.
title: Listing
readOnly: true
CompsetMember:
type: object
description: One curated member of the comp set.
properties:
channel:
type: string
description: 'Source channel: `airbnb`, `vrbo`, or `bookingcom`.'
channel-listing-id:
type:
- string
- 'null'
description: Channel-native listing id of the comparable property (the id in `url`); not a Beyond listing id.
title:
type:
- string
- 'null'
url:
type:
- string
- 'null'
image:
type:
- string
- 'null'
bedrooms:
type:
- number
- 'null'
format: double
bathrooms:
type:
- number
- 'null'
format: double
description: Bathroom count (decimals denote half-baths, e.g. 1.5).
room-type:
type:
- string
- 'null'
latitude:
type:
- number
- 'null'
format: double
longitude:
type:
- number
- 'null'
format: double
distance-km:
type:
- number
- 'null'
format: double
description: Distance from the base listing in kilometers.
rating:
type:
- number
- 'null'
format: double
reviews-count:
type:
- integer
- 'null'
health-score:
type:
- number
- 'null'
format: double
metrics:
$ref: '#/components/schemas/CompsetMemberMetrics'
required:
- channel
- channel-listing-id
- metrics
CompsetSource:
type: object
description: The base listing the comp set was built around.
properties:
bedrooms:
type:
- integer
- 'null'
bathrooms:
type:
- number
- 'null'
format: double
latitude:
type:
- number
- 'null'
format: double
longitude:
type:
- number
- 'null'
format: double
address:
type:
- string
- 'null'
city:
type:
- string
- 'null'
state:
type:
- string
- 'null'
country:
type:
- string
- 'null'
market:
type:
- string
- 'null'
currency:
type:
- string
- 'null'
description: ISO currency code for the base listing.
base-price:
type:
- number
- 'null'
format: double
description: Average base price over the next 365 days.
health-score:
type:
- integer
- 'null'
min-stay:
type:
- integer
- 'null'
metrics:
$ref: '#/components/schemas/CompsetSourceMetrics'
required:
- metrics
securitySchemes:
oauth2:
type: oauth2
description: Use OAuth2 client credentials to mint an application token, or add `user_id` and optional `credential_id` in the Authorize dialog to request a user- or credential-scoped token.
flows:
clientCredentials:
tokenUrl: /o/token/
refreshUrl: /o/token/
scopes:
listings:read: Read listings
listings:write: Modify listings
reservations:read: Read reservations
accounts:read: Read account information
user:read: Read user information
user:write: Create and modify users
insights:read: Read market insights
compsets:read: Read competitive set data
neyoba:ask: Ask Neyoba
personalAccessToken:
type: http
scheme: bearer
bearerFormat: PersonalAccessToken
description: Paste a `bpat_...` personal access token. PATs use the same Bearer header as OAuth2 tokens and must still include the runtime-required scopes for each endpoint, even though OpenAPI cannot encode scopes for non-OAuth bearer schemes.