Search selected listing platforms

curl --request POST \
  --url https://realtycrawl.dev/v1/listings/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "platforms": [
    "<string>"
  ],
  "location": {
    "kind": "text",
    "query": "<string>",
    "country": "<string>"
  }
}
'

import requests

url = "https://realtycrawl.dev/v1/listings/search"

payload = {
    "platforms": ["<string>"],
    "location": {
        "kind": "text",
        "query": "<string>",
        "country": "<string>"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    platforms: ['<string>'],
    location: {kind: 'text', query: '<string>', country: '<string>'}
  })
};

fetch('https://realtycrawl.dev/v1/listings/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "id": "<string>",
      "source": {
        "platform": "<string>",
        "provider": "<string>",
        "observed_at": "2023-11-07T05:31:56Z",
        "access_class": "public_portal",
        "country": "<string>",
        "native_id": "<string>",
        "url": "<string>",
        "source_updated_at": "2023-11-07T05:31:56Z",
        "retrieved_at": "2023-11-07T05:31:56Z"
      },
      "transaction": "sale",
      "status": "active",
      "property": {
        "id": "<string>",
        "address": {
          "country": "<string>",
          "formatted": "<string>",
          "line1": "<string>",
          "unit": "<string>",
          "city": "<string>",
          "region": "<string>",
          "postal_code": "<string>",
          "original_text": "<string>"
        },
        "property_type": "<string>",
        "geometry": {
          "latitude": 0,
          "longitude": 0,
          "precision": "exact",
          "crs": "EPSG:4326"
        },
        "bedrooms": 123,
        "rooms": 123,
        "bathrooms": 123,
        "areas": [
          {
            "value": 123,
            "unit": "sqm",
            "basis": "living",
            "original_text": "<string>",
            "normalized_sqm": 123
          }
        ],
        "layout": "<string>",
        "year_built": 123
      },
      "price": {
        "amount": "<string>",
        "currency": "<string>",
        "kind": "asking",
        "min": "<string>",
        "max": "<string>",
        "unit_code": "<string>",
        "period": "night",
        "per_area_unit": "<string>",
        "display_text": "<string>"
      },
      "observed_at": "2023-11-07T05:31:56Z",
      "native_id": "<string>",
      "source_status": "<string>",
      "title": "<string>",
      "url": "<string>",
      "agent": {
        "id": "<string>",
        "source": {
          "platform": "<string>",
          "provider": "<string>",
          "observed_at": "2023-11-07T05:31:56Z",
          "access_class": "public_portal",
          "country": "<string>",
          "native_id": "<string>",
          "url": "<string>",
          "source_updated_at": "2023-11-07T05:31:56Z",
          "retrieved_at": "2023-11-07T05:31:56Z"
        },
        "name": "<string>",
        "agency_id": "<string>",
        "profile_url": "<string>",
        "professional_contacts": [
          {
            "kind": "business_phone",
            "value": "<string>"
          }
        ],
        "extensions": {}
      },
      "agency": {
        "id": "<string>",
        "source": {
          "platform": "<string>",
          "provider": "<string>",
          "observed_at": "2023-11-07T05:31:56Z",
          "access_class": "public_portal",
          "country": "<string>",
          "native_id": "<string>",
          "url": "<string>",
          "source_updated_at": "2023-11-07T05:31:56Z",
          "retrieved_at": "2023-11-07T05:31:56Z"
        },
        "name": "<string>",
        "address": {
          "country": "<string>",
          "formatted": "<string>",
          "line1": "<string>",
          "unit": "<string>",
          "city": "<string>",
          "region": "<string>",
          "postal_code": "<string>",
          "original_text": "<string>"
        },
        "website": "<string>"
      },
      "media": [
        {
          "url": "<string>",
          "type": "photo",
          "caption": "<string>",
          "position": 123,
          "source": {
            "platform": "<string>",
            "provider": "<string>",
            "observed_at": "2023-11-07T05:31:56Z",
            "access_class": "public_portal",
            "country": "<string>",
            "native_id": "<string>",
            "url": "<string>",
            "source_updated_at": "2023-11-07T05:31:56Z",
            "retrieved_at": "2023-11-07T05:31:56Z"
          }
        }
      ],
      "source_updated_at": "2023-11-07T05:31:56Z",
      "extensions": {},
      "field_status": {}
    }
  ],
  "meta": {
    "request_id": "<string>",
    "schema_version": "<string>",
    "generated_at": "2023-11-07T05:31:56Z",
    "completeness": "complete",
    "sources": [
      {
        "platform": "<string>",
        "status": "success",
        "provider": "<string>",
        "error_code": "<string>",
        "truncated": true,
        "observed_at": "2023-11-07T05:31:56Z"
      }
    ],
    "warnings": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>"
      }
    ],
    "pagination": {
      "next_cursor": "<string>",
      "has_more": true,
      "returned": 123,
      "total": 123,
      "total_relation": "exact"
    },
    "property_groups": [
      {
        "property_id": "<string>",
        "listing_ids": [
          "<string>"
        ],
        "match_method": "<string>",
        "status": "matched",
        "confidence": 123
      }
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "details": [
      {
        "platform": "<string>",
        "status": "success",
        "provider": "<string>",
        "error_code": "<string>",
        "truncated": true,
        "observed_at": "2023-11-07T05:31:56Z"
      }
    ]
  },
  "request_id": "<string>"
}

Listings

Search selected listing platforms

Verified for the platforms listed in x-live-verified-platforms. Consult /v1/meta/capabilities for current enablement and accepted selectors. Supported transactions depend on the platform; consult capabilities and coverage for accepted selectors. Stored listing, media and history observations expire after 24 hours; they do not trigger a fresh crawl. Billing: 50 credits per successful source crawl. Unified searches reserve 50 credits per requested platform and refund failed platforms.

POST

listings

curl --request POST \
  --url https://realtycrawl.dev/v1/listings/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "platforms": [
    "<string>"
  ],
  "location": {
    "kind": "text",
    "query": "<string>",
    "country": "<string>"
  }
}
'

import requests

url = "https://realtycrawl.dev/v1/listings/search"

payload = {
    "platforms": ["<string>"],
    "location": {
        "kind": "text",
        "query": "<string>",
        "country": "<string>"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    platforms: ['<string>'],
    location: {kind: 'text', query: '<string>', country: '<string>'}
  })
};

fetch('https://realtycrawl.dev/v1/listings/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "id": "<string>",
      "source": {
        "platform": "<string>",
        "provider": "<string>",
        "observed_at": "2023-11-07T05:31:56Z",
        "access_class": "public_portal",
        "country": "<string>",
        "native_id": "<string>",
        "url": "<string>",
        "source_updated_at": "2023-11-07T05:31:56Z",
        "retrieved_at": "2023-11-07T05:31:56Z"
      },
      "transaction": "sale",
      "status": "active",
      "property": {
        "id": "<string>",
        "address": {
          "country": "<string>",
          "formatted": "<string>",
          "line1": "<string>",
          "unit": "<string>",
          "city": "<string>",
          "region": "<string>",
          "postal_code": "<string>",
          "original_text": "<string>"
        },
        "property_type": "<string>",
        "geometry": {
          "latitude": 0,
          "longitude": 0,
          "precision": "exact",
          "crs": "EPSG:4326"
        },
        "bedrooms": 123,
        "rooms": 123,
        "bathrooms": 123,
        "areas": [
          {
            "value": 123,
            "unit": "sqm",
            "basis": "living",
            "original_text": "<string>",
            "normalized_sqm": 123
          }
        ],
        "layout": "<string>",
        "year_built": 123
      },
      "price": {
        "amount": "<string>",
        "currency": "<string>",
        "kind": "asking",
        "min": "<string>",
        "max": "<string>",
        "unit_code": "<string>",
        "period": "night",
        "per_area_unit": "<string>",
        "display_text": "<string>"
      },
      "observed_at": "2023-11-07T05:31:56Z",
      "native_id": "<string>",
      "source_status": "<string>",
      "title": "<string>",
      "url": "<string>",
      "agent": {
        "id": "<string>",
        "source": {
          "platform": "<string>",
          "provider": "<string>",
          "observed_at": "2023-11-07T05:31:56Z",
          "access_class": "public_portal",
          "country": "<string>",
          "native_id": "<string>",
          "url": "<string>",
          "source_updated_at": "2023-11-07T05:31:56Z",
          "retrieved_at": "2023-11-07T05:31:56Z"
        },
        "name": "<string>",
        "agency_id": "<string>",
        "profile_url": "<string>",
        "professional_contacts": [
          {
            "kind": "business_phone",
            "value": "<string>"
          }
        ],
        "extensions": {}
      },
      "agency": {
        "id": "<string>",
        "source": {
          "platform": "<string>",
          "provider": "<string>",
          "observed_at": "2023-11-07T05:31:56Z",
          "access_class": "public_portal",
          "country": "<string>",
          "native_id": "<string>",
          "url": "<string>",
          "source_updated_at": "2023-11-07T05:31:56Z",
          "retrieved_at": "2023-11-07T05:31:56Z"
        },
        "name": "<string>",
        "address": {
          "country": "<string>",
          "formatted": "<string>",
          "line1": "<string>",
          "unit": "<string>",
          "city": "<string>",
          "region": "<string>",
          "postal_code": "<string>",
          "original_text": "<string>"
        },
        "website": "<string>"
      },
      "media": [
        {
          "url": "<string>",
          "type": "photo",
          "caption": "<string>",
          "position": 123,
          "source": {
            "platform": "<string>",
            "provider": "<string>",
            "observed_at": "2023-11-07T05:31:56Z",
            "access_class": "public_portal",
            "country": "<string>",
            "native_id": "<string>",
            "url": "<string>",
            "source_updated_at": "2023-11-07T05:31:56Z",
            "retrieved_at": "2023-11-07T05:31:56Z"
          }
        }
      ],
      "source_updated_at": "2023-11-07T05:31:56Z",
      "extensions": {},
      "field_status": {}
    }
  ],
  "meta": {
    "request_id": "<string>",
    "schema_version": "<string>",
    "generated_at": "2023-11-07T05:31:56Z",
    "completeness": "complete",
    "sources": [
      {
        "platform": "<string>",
        "status": "success",
        "provider": "<string>",
        "error_code": "<string>",
        "truncated": true,
        "observed_at": "2023-11-07T05:31:56Z"
      }
    ],
    "warnings": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>"
      }
    ],
    "pagination": {
      "next_cursor": "<string>",
      "has_more": true,
      "returned": 123,
      "total": 123,
      "total_relation": "exact"
    },
    "property_groups": [
      {
        "property_id": "<string>",
        "listing_ids": [
          "<string>"
        ],
        "match_method": "<string>",
        "status": "matched",
        "confidence": 123
      }
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "details": [
      {
        "platform": "<string>",
        "status": "success",
        "provider": "<string>",
        "error_code": "<string>",
        "truncated": true,
        "observed_at": "2023-11-07T05:31:56Z"
      }
    ]
  },
  "request_id": "<string>"
}

Check live capabilities before calling this operation. A documented contract does not imply active coverage for every source or country.

Marketplace apartment observations

Facebook Marketplace supports one source-order apartment rental advertisement in a fixed 10 km circle centered on 40.75, -73.98. Cities may be in New York or New Jersey. Use this request body for platform search:

{
  "transaction": "rent",
  "location": {
    "kind": "source_region",
    "platform": "facebook_marketplace",
    "country": "US",
    "region_id": "manhattan-centered-10km-apartment-rental-advertisements"
  },
  "limit": 1
}

For unified search, add "platforms": ["facebook_marketplace"]. The provider query uses fixed raw amount bounds of 500–6,000 USD. These do not establish recurring rent and are not supported customer price filters. Unsupported filters, sale, cursors or larger pages fail before source access. Source property category, unit details/counts, canonical listing/share identity and actual item distance must agree. Numeric prices, billing period, deposit basis, availability, exact item location, contacts, photos and source update time are unknown or omitted. A source product ID is not assumed to be the native listing ID. This observation does not establish complete inventory or housing availability. The four accepted source operations are platform search, unified search, retained account-owned listing and stored media. Media is an empty array for this source. Native-ID detail, resolution and listing history remain unavailable. Fresh searches cost 50 credits, retained reads 1, errors and prior-response replay 0. Account selectors expire after 24 hours; existing seven-day replay snapshots can outlive selector retention.

Authorizations

x-api-key

string

header

required

Body

application/json

platforms

string[]

required

Required array length: 1 - 5 elements

location

object

required

Show child attributes

transaction

enum<string>

required

Available options:

sale,

rent,

lease,

auction

property_types

string[]

status

string[]

price

object

Option 1
Option 2

Show child attributes

bedrooms

object

At least one bound is required; min <= max when both supplied.

Option 1
Option 2

Show child attributes

bathrooms

object

At least one bound is required; min <= max when both supplied.

Option 1
Option 2

Show child attributes

area

object

Show child attributes

listed_since

string<date-time>

sort

enum<string>

Available options:

source_order,

price_asc,

price_desc,

newest

include

enum<string>[]

Available options:

media,

history,

agent,

agency,

units,

open_houses,

source_fields

source_filters

object

Show child attributes

limit

integer

default:20

Required range: 1 <= x <= 100

cursor

string

allow_partial

boolean

default:false

group_by_property

boolean

default:false

Response

Successful response; meta discloses source completeness

data

object[]

required

Show child attributes

Overview

Meta

Listings

Platform listings

Properties

Buildings

Developments

Agents

Agencies

Auctions

Markets

Stays

Locations

Jobs

Search selected listing platforms

Marketplace apartment observations

Authorizations

Body

Response

​Marketplace apartment observations

Authorizations

Body

Response

Marketplace apartment observations