> ## 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 property-focused accommodation

> Date-specific, read-only Airbnb London, Vrbo Orlando, Agoda Bangkok, Trip.com Tokyo and Booking.com Paris stay observations. One matching platform and documented source_region per request; two adults, no children/infants/pets. Currency GBP for Airbnb; USD for Vrbo, Agoda, Trip.com and Booking.com. Stays of 1–30 nights, limit 1–50. Costs 50 credits. No booking guarantee, reviews, full availability calendar, cursor or additional filters. Booking Paris requires explicit limit1 and uses the provider-documented Paris destination ID; free-text autocomplete is not used. No unique returned hotel settles404 withzero credits.

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


## OpenAPI

````yaml POST /v1/stays/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/stays/search:
    post:
      tags:
        - stays
      summary: Search property-focused accommodation
      description: >-
        Date-specific, read-only Airbnb London, Vrbo Orlando, Agoda Bangkok,
        Trip.com Tokyo and Booking.com Paris stay observations. One matching
        platform and documented source_region per request; two adults, no
        children/infants/pets. Currency GBP for Airbnb; USD for Vrbo, Agoda,
        Trip.com and Booking.com. Stays of 1–30 nights, limit 1–50. Costs 50
        credits. No booking guarantee, reviews, full availability calendar,
        cursor or additional filters. Booking Paris requires explicit limit1 and
        uses the provider-documented Paris destination ID; free-text
        autocomplete is not used. No unique returned hotel settles404 withzero
        credits.
      operationId: searchStays
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StaySearchRequest'
      responses:
        '200':
          description: Successful response; meta discloses source completeness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/searchStaysResponse'
        default:
          description: Typed error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    StaySearchRequest:
      type: object
      properties:
        platforms:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 5
          uniqueItems: true
        location:
          $ref: '#/components/schemas/LocationSelector'
        check_in:
          type: string
          format: date
        check_out:
          type: string
          format: date
        guests:
          $ref: '#/components/schemas/Guests'
        currency:
          type: string
          pattern: ^[A-Z]{3}$
        locale:
          type: string
        accommodation_types:
          type: array
          items:
            type: string
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        cursor:
          type: string
      required:
        - platforms
        - location
        - check_in
        - check_out
        - guests
        - currency
      additionalProperties: false
    searchStaysResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Stay'
        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
    Guests:
      type: object
      properties:
        adults:
          type: integer
          minimum: 1
          maximum: 30
        children_ages:
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 17
        infants:
          type: integer
          minimum: 0
        pets:
          type: integer
          minimum: 0
      required:
        - adults
      additionalProperties: false
    Stay:
      type: object
      properties:
        id:
          type: string
        source:
          $ref: '#/components/schemas/Source'
        name:
          anyOf:
            - type: string
            - type: 'null'
        property:
          $ref: '#/components/schemas/PropertySummary'
        accommodation_type:
          type: string
          enum:
            - entire_home
            - private_room
            - shared_room
            - apartment
            - hotel
            - other
            - unknown
        guest_capacity:
          anyOf:
            - type: integer
            - type: 'null'
        extensions:
          type: object
          properties: {}
          required: []
          additionalProperties: true
      required:
        - id
        - source
        - property
        - accommodation_type
      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
    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.