> ## Documentation Index
> Fetch the complete documentation index at: https://realtycrawl.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>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.</Note>

## 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:

```json theme={null}
{
  "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.


## OpenAPI

````yaml POST /v1/listings/search
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: []
paths:
  /v1/listings/search:
    post:
      tags:
        - listings
      summary: Search selected listing platforms
      description: >-
        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.
      operationId: searchListings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListingSearchRequest'
      responses:
        '200':
          description: Successful response; meta discloses source completeness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/searchListingsResponse'
        default:
          description: Typed error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ListingSearchRequest:
      type: object
      properties:
        platforms:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 5
          uniqueItems: true
        location:
          $ref: '#/components/schemas/LocationSelector'
        transaction:
          type: string
          enum:
            - sale
            - rent
            - lease
            - auction
        property_types:
          type: array
          items:
            type: string
        status:
          type: array
          items:
            type: string
        price:
          $ref: '#/components/schemas/PriceFilter'
        bedrooms:
          $ref: '#/components/schemas/Bounds'
        bathrooms:
          $ref: '#/components/schemas/Bounds'
        area:
          type: object
          properties:
            min:
              type: number
            max:
              type: number
            unit:
              type: string
              enum:
                - sqm
                - sqft
                - acre
                - hectare
            basis:
              type: string
              enum:
                - living
                - built
                - gross
                - carpet
                - land
                - unknown
          required:
            - unit
            - basis
          additionalProperties: false
        listed_since:
          type: string
          format: date-time
        sort:
          type: string
          enum:
            - source_order
            - price_asc
            - price_desc
            - newest
        include:
          type: array
          items:
            type: string
            enum:
              - media
              - history
              - agent
              - agency
              - units
              - open_houses
              - source_fields
        source_filters:
          type: object
          additionalProperties:
            type: object
            properties: {}
            required: []
            additionalProperties: true
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        cursor:
          type: string
        allow_partial:
          type: boolean
          default: false
        group_by_property:
          type: boolean
          default: false
      required:
        - platforms
        - location
        - transaction
      additionalProperties: false
    searchListingsResponse:
      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
    LocationSelector:
      oneOf:
        - type: object
          properties:
            kind:
              const: text
            query:
              type: string
            country:
              type: string
          required:
            - kind
            - query
            - country
          additionalProperties: false
        - type: object
          properties:
            kind:
              const: postal_code
            postal_code:
              type: string
            country:
              type: string
          required:
            - kind
            - postal_code
            - country
          additionalProperties: false
        - type: object
          properties:
            kind:
              const: bbox
            bbox:
              type: array
              items:
                type: number
              minItems: 4
              maxItems: 4
          required:
            - kind
            - bbox
          additionalProperties: false
          description: >-
            west,south,east,north in WGS84; bounds and antimeridian handling
            validated at runtime.
        - type: object
          properties:
            kind:
              const: radius
            latitude:
              type: number
              minimum: -90
              maximum: 90
            longitude:
              type: number
              minimum: -180
              maximum: 180
            radius_meters:
              type: number
              exclusiveMinimum: 0
              maximum: 100000
          required:
            - kind
            - latitude
            - longitude
            - radius_meters
          additionalProperties: false
        - type: object
          properties:
            kind:
              const: polygon
            geometry:
              type: object
              properties:
                type:
                  const: Polygon
                coordinates:
                  type: array
                  items:
                    type: array
                    minItems: 4
                    items:
                      type: array
                      items:
                        type: number
                      minItems: 2
                      maxItems: 2
              required:
                - type
                - coordinates
              additionalProperties: false
          required:
            - kind
            - geometry
          additionalProperties: false
          description: >-
            GeoJSON WGS84 polygon with closed rings. Ring closure and coordinate
            bounds validated at runtime.
        - type: object
          properties:
            kind:
              const: source_region
            platform:
              type: string
            region_id:
              type: string
            country:
              type: string
          required:
            - kind
            - platform
            - region_id
            - country
          additionalProperties: false
    PriceFilter:
      type: object
      properties:
        min:
          type: number
        max:
          type: number
        currency:
          type: string
        unit_code:
          type: string
        period:
          type: string
          enum:
            - night
            - week
            - month
            - year
            - one_time
      required:
        - currency
      additionalProperties: false
      anyOf:
        - required:
            - min
        - required:
            - max
    Bounds:
      type: object
      properties:
        min:
          type: number
        max:
          type: number
      required: []
      additionalProperties: false
      description: At least one bound is required; min <= max when both supplied.
      anyOf:
        - required:
            - min
        - required:
            - max
    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.