> ## Documentation Index
> Fetch the complete documentation index at: https://docs.realtycrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Property Listings
> Proposed interface. Enable only for documented and verified source/country capabilities. Explicitly matched source advertisements
This operation is defined in the API contract but is not currently enabled.
Check [live capabilities](https://realtycrawl.dev/v1/meta/capabilities) before calling this operation. A documented contract does not imply active coverage for every source or country.
## OpenAPI
````yaml GET /v1/properties/{property_id}/listings
openapi: 3.1.0
info:
title: RealtyCrawl proposed unified API
version: 0.1.0
description: >-
Research draft dated 2026-10-13. No production server or enabled platform
coverage is implied. Country and operation capabilities must be checked.
servers:
- url: https://realtycrawl.dev
security:
- ApiKeyAuth: []
externalDocs:
url: https://docs.realtycrawl.dev
paths:
/v1/properties/{property_id}/listings:
get:
tags:
- properties
summary: getPropertyListings
description: >-
Proposed interface. Enable only for documented and verified
source/country capabilities. Explicitly matched source advertisements
operationId: getPropertyListings
parameters:
- name: property_id
in: path
required: true
schema:
type: string
minLength: 1
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: cursor
in: query
schema:
type: string
responses:
'200':
description: Successful response; meta discloses source completeness
content:
application/json:
schema:
$ref: '#/components/schemas/getPropertyListingsResponse'
default:
description: Typed error response
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
getPropertyListingsResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Listing'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
additionalProperties: false
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
retryable:
type: boolean
details:
type: array
items:
$ref: '#/components/schemas/SourceOutcome'
required:
- code
- message
- retryable
additionalProperties: false
request_id:
type: string
required:
- error
- request_id
additionalProperties: false
Listing:
type: object
properties:
id:
type: string
source:
$ref: '#/components/schemas/Source'
native_id:
anyOf:
- type: string
- type: 'null'
transaction:
type: string
enum:
- sale
- rent
- lease
- auction
status:
type: string
enum:
- active
- pending
- contingent
- sold
- rented
- withdrawn
- expired
- off_market
- unknown
source_status:
anyOf:
- type: string
- type: 'null'
title:
anyOf:
- type: string
- type: 'null'
url:
anyOf:
- type: string
- type: 'null'
property:
$ref: '#/components/schemas/PropertySummary'
price:
$ref: '#/components/schemas/Money'
agent:
anyOf:
- $ref: '#/components/schemas/Agent'
- type: 'null'
agency:
anyOf:
- $ref: '#/components/schemas/Agency'
- type: 'null'
media:
type: array
items:
$ref: '#/components/schemas/Media'
observed_at:
type: string
format: date-time
source_updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
extensions:
type: object
properties: {}
required: []
additionalProperties: true
field_status:
type: object
additionalProperties:
type: string
enum:
- present
- not_published
- not_requested
- unsupported
- restricted
- temporarily_unavailable
required:
- id
- source
- transaction
- status
- property
- price
- observed_at
additionalProperties: false
Meta:
type: object
properties:
request_id:
type: string
schema_version:
type: string
generated_at:
type: string
format: date-time
completeness:
type: string
enum:
- complete
- partial
- unknown
sources:
type: array
items:
$ref: '#/components/schemas/SourceOutcome'
warnings:
type: array
items:
type: object
properties:
code:
type: string
message:
type: string
field:
type: string
required:
- code
- message
additionalProperties: false
pagination:
type: object
properties:
next_cursor:
anyOf:
- type: string
- type: 'null'
has_more:
type: boolean
returned:
type: integer
total:
anyOf:
- type: integer
- type: 'null'
total_relation:
type: string
enum:
- exact
- lower_bound
- unknown
required:
- next_cursor
- has_more
- returned
- total
- total_relation
additionalProperties: false
property_groups:
type: array
items:
$ref: '#/components/schemas/PropertyGroup'
required:
- request_id
- schema_version
- generated_at
- completeness
- sources
additionalProperties: false
SourceOutcome:
type: object
properties:
platform:
type: string
provider:
anyOf:
- type: string
- type: 'null'
status:
type: string
enum:
- success
- partial
- failed
- unsupported
error_code:
anyOf:
- type: string
- type: 'null'
truncated:
type: boolean
observed_at:
anyOf:
- type: string
format: date-time
- type: 'null'
required:
- platform
- status
additionalProperties: false
Source:
type: object
properties:
platform:
type: string
country:
type: string
native_id:
anyOf:
- type: string
- type: 'null'
url:
anyOf:
- type: string
format: uri
- type: 'null'
provider:
type: string
observed_at:
type: string
format: date-time
source_updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
access_class:
type: string
enum:
- public_portal
- licensed_feed
- public_record
- modeled
retrieved_at:
type: string
format: date-time
required:
- platform
- provider
- observed_at
- access_class
additionalProperties: false
PropertySummary:
type: object
properties:
id:
anyOf:
- type: string
- type: 'null'
address:
$ref: '#/components/schemas/Address'
geometry:
anyOf:
- $ref: '#/components/schemas/Geometry'
- type: 'null'
property_type:
type: string
bedrooms:
anyOf:
- type: number
- type: 'null'
rooms:
anyOf:
- type: number
- type: 'null'
bathrooms:
anyOf:
- type: number
- type: 'null'
areas:
type: array
items:
$ref: '#/components/schemas/Area'
layout:
anyOf:
- type: string
- type: 'null'
year_built:
anyOf:
- type: integer
- type: 'null'
required:
- id
- address
- property_type
additionalProperties: false
Money:
type: object
properties:
amount:
anyOf:
- type: string
pattern: ^-?\d+(\.\d+)?$
- type: 'null'
min:
anyOf:
- type: string
- type: 'null'
max:
anyOf:
- type: string
- type: 'null'
currency:
anyOf:
- type: string
pattern: ^[A-Z]{3}$
- type: 'null'
unit_code:
anyOf:
- type: string
- type: 'null'
kind:
type: string
enum:
- asking
- sold
- rent
- lease_rate
- starting_bid
- deposit
- fee
- estimate
- unknown
period:
anyOf:
- type: string
enum:
- night
- week
- month
- year
- one_time
- type: 'null'
per_area_unit:
anyOf:
- type: string
- type: 'null'
display_text:
anyOf:
- type: string
- type: 'null'
required:
- amount
- currency
- kind
additionalProperties: false
Agent:
type: object
properties:
id:
type: string
source:
$ref: '#/components/schemas/Source'
name:
anyOf:
- type: string
- type: 'null'
agency_id:
anyOf:
- type: string
- type: 'null'
profile_url:
anyOf:
- type: string
- type: 'null'
professional_contacts:
type: array
items:
type: object
properties:
kind:
type: string
enum:
- business_phone
- business_email
- website
value:
type: string
required:
- kind
- value
additionalProperties: false
extensions:
type: object
properties: {}
required: []
additionalProperties: true
required:
- id
- source
additionalProperties: false
Agency:
type: object
properties:
id:
type: string
source:
$ref: '#/components/schemas/Source'
name:
anyOf:
- type: string
- type: 'null'
address:
anyOf:
- $ref: '#/components/schemas/Address'
- type: 'null'
website:
anyOf:
- type: string
- type: 'null'
required:
- id
- source
additionalProperties: false
Media:
type: object
properties:
url:
type: string
format: uri
type:
type: string
enum:
- photo
- floor_plan
- video
- virtual_tour
- document
caption:
anyOf:
- type: string
- type: 'null'
position:
type: integer
source:
$ref: '#/components/schemas/Source'
required:
- url
- type
additionalProperties: false
PropertyGroup:
type: object
properties:
property_id:
anyOf:
- type: string
- type: 'null'
listing_ids:
type: array
items:
type: string
match_method:
type: string
confidence:
anyOf:
- type: number
- type: 'null'
status:
type: string
enum:
- matched
- ambiguous
required:
- property_id
- listing_ids
- match_method
- status
additionalProperties: false
Address:
type: object
properties:
formatted:
anyOf:
- type: string
- type: 'null'
line1:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
city:
anyOf:
- type: string
- type: 'null'
region:
anyOf:
- type: string
- type: 'null'
postal_code:
anyOf:
- type: string
- type: 'null'
country:
type: string
pattern: ^[A-Z]{2}$
original_text:
anyOf:
- type: string
- type: 'null'
required:
- country
additionalProperties: false
Geometry:
type: object
properties:
latitude:
type: number
minimum: -90
maximum: 90
longitude:
type: number
minimum: -180
maximum: 180
precision:
type: string
enum:
- exact
- approximate
- centroid
- obfuscated
- unknown
crs:
type: string
const: EPSG:4326
required:
- latitude
- longitude
- precision
- crs
additionalProperties: false
Area:
type: object
properties:
value:
type: number
unit:
type: string
enum:
- sqm
- sqft
- acre
- hectare
- ping
- tsubo
- other
basis:
type: string
enum:
- living
- built
- gross
- carpet
- saleable
- land
- unknown
original_text:
anyOf:
- type: string
- type: 'null'
normalized_sqm:
anyOf:
- type: number
- type: 'null'
required:
- value
- unit
- basis
additionalProperties: false
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.