openapi: 3.0.0
info:
  title: Zillow Property API
  description: |
    Get detailed information about a specific Zillow property or apartment building.

    Accepts a numeric Zillow property ID (zpid) or a full Zillow URL. Returns comprehensive property details including pricing, descriptions, photos, schools, price/tax history, walk scores, Zestimate comparables, and facts & features.

    For individual properties (for sale, sold, for rent), the response contains a `property` object. For apartment buildings, the response contains a `building` object with floor plans, amenities, and pet policies.

    **Related API:** Use the [Zillow Search API](https://www.searchapi.io/docs/zillow) to find properties by location. The `zpid` from search results can be passed directly to this API.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Zillow Property Details
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine identifier
          schema:
            type: string
            enum: ["zillow_property"]
            default: "zillow_property"
        - name: zpid
          in: query
          required: true
          description: 'Zillow property ID or full Zillow URL. Pass a numeric zpid from Zillow Search API results (e.g., "69817587") or a full Zillow URL for apartment buildings (e.g., "https://www.zillow.com/apartments/..."). Use the link field from search results for buildings.'
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PropertyResponse'
                  - $ref: '#/components/schemas/BuildingResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    PropertyResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        property:
          $ref: '#/components/schemas/Property'
        attribution:
          $ref: '#/components/schemas/Attribution'
        mortgage_rates:
          $ref: '#/components/schemas/MortgageRates'
        comparables:
          type: array
          description: Zestimate comparable properties used for valuation
          items:
            $ref: '#/components/schemas/Comparable'
        nearby_schools:
          type: array
          description: Nearby schools with ratings
          items:
            $ref: '#/components/schemas/School'
        nearby_homes:
          type: array
          description: Nearby properties
          items:
            $ref: '#/components/schemas/NearbyItem'
        nearby_buildings:
          type: array
          description: Nearby apartment buildings
          items:
            $ref: '#/components/schemas/NearbyItem'
        nearby_cities:
          type: array
          items:
            $ref: '#/components/schemas/NearbyItem'
        nearby_neighborhoods:
          type: array
          items:
            $ref: '#/components/schemas/NearbyItem'
        nearby_zipcodes:
          type: array
          items:
            $ref: '#/components/schemas/NearbyItem'

    BuildingResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        building:
          $ref: '#/components/schemas/Building'
        seo:
          $ref: '#/components/schemas/Seo'
        attribution:
          $ref: '#/components/schemas/ContactInfo'
        market_insights:
          $ref: '#/components/schemas/MarketInsights'
        housing_connector_link:
          type: string
          description: Housing Connector affiliate URL for renter applications
        ppc_link:
          type: string
          description: Pay-per-click partner application URL
        related_links:
          type: array
          description: Related navigation links (geographic hierarchy from state down to neighborhood)
          items:
            $ref: '#/components/schemas/RelatedLink'
        nearby_schools:
          type: array
          items:
            $ref: '#/components/schemas/School'
        neighborhood_highlights:
          type: array
          items:
            $ref: '#/components/schemas/NeighborhoodHighlight'
        nearby_buildings:
          type: array
          items:
            $ref: '#/components/schemas/NearbyItem'
        nearby_cities:
          type: array
          items:
            $ref: '#/components/schemas/NearbyItem'
        nearby_neighborhoods:
          type: array
          items:
            $ref: '#/components/schemas/NearbyItem'
        nearby_zipcodes:
          type: array
          items:
            $ref: '#/components/schemas/NearbyItem'

    Property:
      type: object
      required: [zpid, link, address, street, city, state, zipcode, latitude, longitude, home_status, home_type, price, currency]
      properties:
        zpid:
          type: string
          description: Zillow property ID
        link:
          type: string
          description: Full Zillow property URL
        address:
          type: string
          description: Full formatted address
        street:
          type: string
          description: Street address
        city:
          type: string
        state:
          type: string
        zipcode:
          type: string
        county:
          type: string
        county_fips:
          type: string
          description: FIPS county code
        country:
          type: string
        neighborhood:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        home_status:
          type: string
          description: 'Listing status (e.g., "FOR_SALE", "RECENTLY_SOLD", "FOR_RENT")'
        home_type:
          type: string
          description: 'Property type (e.g., "CONDO", "SINGLE_FAMILY", "TOWNHOUSE", "LOT", "MULTI_FAMILY", "APARTMENT")'
        parcel_id:
          type: string
          description: Tax parcel / APN identifier
        price:
          type: number
          description: Current listing price or last sold price
        price_change:
          type: integer
          description: Most recent price change in the listing currency (negative = price drop)
        price_change_date:
          type: string
          description: 'Date of the most recent price change (YYYY-MM-DD)'
        price_change_date_string:
          type: string
          description: 'Raw date-of-price-change string from Zillow (typically YYYY-MM-DD)'
        currency:
          type: string
        beds:
          type: integer
        baths:
          type: integer
        sqft:
          type: integer
          description: Living area in square feet
        sqft_units:
          type: string
        lot_size:
          type: number
          description: Lot size
        lot_size_units:
          type: string
        year_built:
          type: integer
        description:
          type: string
          description: Property description text
        days_on_zillow:
          type: integer
        time_on_zillow:
          type: string
        zestimate:
          type: integer
          description: Zillow estimated market value
        zestimate_low_percent:
          type: integer
          description: Zestimate low range percentage
        zestimate_high_percent:
          type: integer
          description: Zestimate high range percentage
        rent_zestimate:
          type: integer
          description: Estimated monthly rent
        monthly_hoa_fee:
          type: integer
        property_tax_rate:
          type: number
        date_posted:
          type: string
          description: 'Date the listing was posted (YYYY-MM-DD)'
        date_sold:
          type: string
          description: 'Date the property was sold (YYYY-MM-DD)'
        last_sold_price:
          type: number
        mls_id:
          type: string
          description: MLS listing ID
        thumbnail:
          type: string
          description: High-resolution thumbnail URL
        street_view_image_url:
          type: string
          description: Google Street View image URL
        virtual_tour_url:
          type: string
          description: 3D tour or virtual tour URL
        photo_count:
          type: integer
        favorite_count:
          type: integer
        page_view_count:
          type: integer
        is_showcase:
          type: boolean
          description: Whether this is a Zillow showcase listing
        listing_type:
          type: string
          description: 'Listing type (e.g., "For Sale by Agent")'
        keystone_home_status:
          type: string
          description: 'Internal Zillow status (e.g., "ForSale", "ForRent", "RecentlySold")'
        contingent_listing_type:
          type: string
          description: 'Contingency type if the listing is under contract (e.g., "INSPECTION", "FINANCING")'
        new_construction_type:
          type: string
          description: 'New construction category (e.g., "BUILDER_SPEC", "BUILDER_PLAN")'
        move_in_completion_date:
          type: string
          description: Estimated move-in completion date for new construction
        what_i_love:
          type: string
          description: '"What I Love" agent-written highlight'
        interactive_floor_plan_url:
          type: string
          description: Interactive 3D floor plan URL
        marketing_name:
          type: string
          description: Marketing name for the unit (typically apartment unit identifier)
        lot_premium:
          type: number
          description: Lot premium upcharge for new construction
        tour_view_count:
          type: integer
          description: Number of times the 3D tour has been viewed
        restimate_minus_30:
          type: number
          description: Rent Zestimate value 30 days ago
        zestimate_minus_30:
          type: number
          description: Zestimate value 30 days ago
        has_vr_model:
          type: boolean
          description: Whether the listing has a VR/3D model
        has_promotion:
          type: boolean
          description: Whether the listing has an active promotion
        has_bad_geocode:
          type: boolean
          description: Whether the listing's address has been flagged as poorly geocoded
        is_undisclosed_address:
          type: boolean
          description: Whether the address is hidden by the seller
        is_premier_builder:
          type: boolean
          description: Whether the listing is from a premier builder partner
        is_income_restricted:
          type: boolean
          description: Whether the listing has income restrictions
        is_move_in_ready:
          type: boolean
          description: Whether the new construction home is move-in ready
        brokerage_name:
          type: string
        building_name:
          type: string
          description: Building name (for apartment units)
        building_id:
          type: string
          description: Building ID (for apartment units)
        images:
          type: array
          description: Property photo URLs at highest available resolution
          items:
            type: string
        walk_and_transit_scores:
          $ref: '#/components/schemas/WalkAndTransitScores'
        home_insights:
          type: array
          description: AI-generated property highlights
          items:
            type: string
        home_value_chart_data:
          type: array
          description: Historical Zestimate values over time
          items:
            $ref: '#/components/schemas/HomeValueChart'
        price_history:
          type: array
          description: Listing and sale price history
          items:
            $ref: '#/components/schemas/PriceHistoryEntry'
        tax_history:
          type: array
          description: Annual property tax records
          items:
            $ref: '#/components/schemas/TaxHistoryEntry'
        open_house_schedule:
          type: array
          description: Upcoming open house events
          items:
            $ref: '#/components/schemas/OpenHouseEvent'
        facts_and_features:
          $ref: '#/components/schemas/FactsAndFeatures'
        affordability_estimate:
          $ref: '#/components/schemas/AffordabilityEstimate'
        listing_provider:
          $ref: '#/components/schemas/ListingProvider'
        rich_media:
          $ref: '#/components/schemas/RichMedia'
        static_map:
          $ref: '#/components/schemas/StaticMap'
        listing_sub_type:
          $ref: '#/components/schemas/ListingSubType'
        special_offers:
          type: array
          description: Active promotions or special offers
          items:
            $ref: '#/components/schemas/SpecialOffer'

    Building:
      type: object
      required: [zpid, link, building_name, building_type, address, street, city, state, zipcode, latitude, longitude, description, phone]
      properties:
        zpid:
          type: string
        link:
          type: string
        building_name:
          type: string
        building_type:
          type: string
        address:
          type: string
          description: Full formatted address
        street:
          type: string
        city:
          type: string
        state:
          type: string
        zipcode:
          type: string
        county:
          type: string
        country:
          type: string
        neighborhood:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        description:
          type: string
        neighborhood_description:
          type: string
          description: Description of the neighborhood and zip code area
        availability_insights:
          type: string
          description: Summary of recent availability changes
        lease_duration:
          type: integer
          description: Standard lease duration in months
        phone:
          type: string
          description: Building contact phone number
        photo_count:
          type: integer
        available_units:
          type: integer
        total_units:
          type: integer
        walk_score:
          type: integer
        bike_score:
          type: integer
        transit_score:
          type: integer
        currency:
          type: string
        home_types:
          type: array
          description: Home types offered in the building
          items:
            type: string
        is_low_income:
          type: boolean
        is_senior_housing:
          type: boolean
        is_student_housing:
          type: boolean
        is_waitlisted:
          type: boolean
          description: Whether the building has a waitlist for available units
        is_landlord_liaison_program:
          type: boolean
          description: Whether the building participates in the Landlord Liaison Program
        is_income_restricted_cta_shown:
          type: boolean
          description: Whether the listing displays an income-restricted application CTA
        images:
          type: array
          description: Building photo URLs
          items:
            type: string
        videos:
          type: array
          description: Building marketing videos
          items:
            $ref: '#/components/schemas/Video'
        third_party_virtual_tours:
          type: array
          description: External 3D and virtual tour links
          items:
            $ref: '#/components/schemas/ThirdPartyVirtualTour'
        home_insights:
          type: array
          description: AI-generated building highlights
          items:
            type: string
        zov_insight:
          $ref: '#/components/schemas/ZovInsight'
        floor_plans:
          type: array
          description: Available floor plans with units
          items:
            $ref: '#/components/schemas/FloorPlan'
        price_ranges:
          type: array
          description: Rent ranges by bedroom count
          items:
            $ref: '#/components/schemas/PriceRange'
        amenities:
          $ref: '#/components/schemas/Amenities'
        pet_policy:
          type: array
          description: Per-species pet rules
          items:
            $ref: '#/components/schemas/PetPolicyEntry'
        special_offers:
          type: array
          items:
            $ref: '#/components/schemas/SpecialOffer'

    Attribution:
      type: object
      properties:
        agent_name:
          type: string
        agent_phone:
          type: string
        agent_license:
          type: string
        co_agent_name:
          type: string
        co_agent_phone:
          type: string
        co_agent_license:
          type: string
        broker_name:
          type: string
        broker_phone:
          type: string
        mls_name:
          type: string
        mls_id:
          type: string
        mls_disclaimer:
          type: string
        listing_agreement:
          type: string
        last_checked:
          type: string
          description: Timestamp the listing was last checked by Zillow
        last_updated:
          type: string
          description: Timestamp of the most recent listing data update
        provider_logo:
          type: string
          description: URL of the listing source / MLS provider logo
        listing_offices:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              name:
                type: string
        listing_agents:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              name:
                type: string
              license:
                type: string

    ContactInfo:
      type: object
      properties:
        agent_name:
          type: string
        phone:
          type: string

    WalkAndTransitScores:
      type: object
      properties:
        walk_score:
          type: integer
        walk_score_description:
          type: string
        transit_score:
          type: integer
        transit_score_description:
          type: string
        bike_score:
          type: integer
        bike_score_description:
          type: string

    Comparable:
      type: object
      properties:
        zpid:
          type: string
        address:
          type: string
        price:
          type: integer
        beds:
          type: integer
        baths:
          type: integer
        sqft:
          type: integer
        home_type:
          type: string
        home_status:
          type: string
        link:
          type: string
        thumbnail:
          type: string

    HomeValueChart:
      type: object
      properties:
        name:
          type: string
          description: 'Chart series name (e.g., "This home", "Sale")'
        points:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                description: 'Date (YYYY-MM-DD)'
              value:
                type: number
                description: Estimated value in dollars

    PriceHistoryEntry:
      type: object
      required: [event]
      properties:
        date:
          type: string
        event:
          type: string
          description: 'Event type (e.g., "Listed for sale", "Sold", "Listing removed")'
        price:
          type: integer
        price_per_square_foot:
          type: integer
        price_change_rate:
          type: number
        source:
          type: string
        is_rental:
          type: boolean

    TaxHistoryEntry:
      type: object
      required: [year, tax_paid]
      properties:
        year:
          type: integer
        tax_paid:
          type: number
        tax_increase_rate:
          type: number
        value:
          type: integer
          description: Assessed property value
        value_increase_rate:
          type: number

    School:
      type: object
      properties:
        name:
          type: string
        rating:
          type: integer
          description: GreatSchools rating (1-10)
        grades:
          type: string
          description: 'Grade range (e.g., "K-5", "6-8")'
        distance:
          type: number
          description: Distance in miles
        link:
          type: string
          description: GreatSchools profile URL

    OpenHouseEvent:
      type: object
      properties:
        start_time:
          type: string
          description: 'Start time (YYYY-MM-DD HH:MM:SS)'
        end_time:
          type: string

    FactsAndFeatures:
      type: object
      properties:
        bedrooms:
          type: integer
        bathrooms:
          type: number
        bathrooms_full:
          type: integer
        bathrooms_half:
          type: integer
        bathrooms_float:
          type: number
          description: Bathroom count expressed as a decimal (handles half/quarter baths)
        bathrooms_one_quarter:
          type: integer
        bathrooms_three_quarter:
          type: integer
        living_area:
          type: string
          description: Formatted living area string (raw resoFacts value, e.g. "818 sqft")
        above_grade_finished_area:
          type: string
          description: 'Finished square footage above grade (formatted, e.g. "2,976")'
        below_grade_finished_area:
          type: string
          description: 'Finished basement square footage (formatted, e.g. "868")'
        basement:
          type: string
          description: 'Raw basement description (e.g. "Finished,Full")'
        home_type:
          type: string
        year_built:
          type: integer
        stories:
          type: integer
        lot_size:
          type: number
          description: Lot size (raw resoFacts value)
        zoning:
          type: string
        parcel_number:
          type: string
        architectural_style:
          type: string
        builder_name:
          type: string
          description: Builder name for new construction listings
        cumulative_days_on_market:
          type: string
          description: 'Cumulative days on market (formatted string, e.g. "10 days")'
        on_market_date:
          type: string
          description: 'Date the property was first put on the market (YYYY-MM-DD)'
        price_per_square_foot:
          type: number
        hoa_fee:
          type: string
        tax_annual_amount:
          type: number
        tax_assessed_value:
          type: number
        heating:
          type: array
          items:
            type: string
        cooling:
          type: array
          items:
            type: string
        appliances:
          type: array
          items:
            type: string
        flooring:
          type: array
          items:
            type: string
        interior_features:
          type: array
          items:
            type: string
        exterior_features:
          type: array
          items:
            type: string
        parking_features:
          type: array
          items:
            type: string
        parking_capacity:
          type: integer
        covered_parking_capacity:
          type: integer
        open_parking_capacity:
          type: integer
        green_energy_efficient:
          type: array
          description: 'Sustainability / green-energy features (e.g. ["Solar Panels"])'
          items:
            type: string
        has_garage:
          type: boolean
        garage_capacity:
          type: integer
        has_attached_garage:
          type: boolean
        has_carport:
          type: boolean
        has_open_parking:
          type: boolean
        fireplace_features:
          type: array
          items:
            type: string
        fireplaces:
          type: integer
        roof_type:
          type: string
        foundation_details:
          type: array
          items:
            type: string
        construction_materials:
          type: array
          items:
            type: string
        sewer:
          type: array
          items:
            type: string
        water_source:
          type: array
          items:
            type: string
        laundry_features:
          type: array
          items:
            type: string
        community_features:
          type: array
          items:
            type: string
        utilities:
          type: array
          items:
            type: string
        gas:
          type: array
          items:
            type: string
        fencing:
          type: string
        levels:
          type: string
        view:
          type: array
          items:
            type: string
        window_features:
          type: array
          items:
            type: string
        patio_and_porch_features:
          type: array
          items:
            type: string
        security_features:
          type: array
          items:
            type: string
        pool_features:
          type: array
          items:
            type: string
        lot_features:
          type: array
          items:
            type: string
        other_structures:
          type: array
          items:
            type: string
        room_types:
          type: array
          items:
            type: string
        association_fee:
          type: string
        association_fee_includes:
          type: array
          items:
            type: string
        fees_and_dues:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              fee:
                type: string
        has_association:
          type: boolean
        has_cooling:
          type: boolean
        has_heating:
          type: boolean
        has_fireplace:
          type: boolean
        has_spa:
          type: boolean
        has_view:
          type: boolean
        has_waterfront_view:
          type: boolean
        has_private_pool:
          type: boolean
        has_basement:
          type: boolean
        has_land_lease:
          type: boolean
        is_new_construction:
          type: boolean
        is_furnished:
          type: boolean
        has_home_warranty:
          type: boolean
        subdivision_name:
          type: string
        property_condition:
          type: string
        listing_terms:
          type: string
        special_listing_conditions:
          type: string
        availability_date:
          type: string
          description: 'Rental availability date (YYYY-MM-DD)'
        lease_term:
          type: string
        has_pets_allowed:
          type: boolean
        allowed_pets:
          type: array
          items:
            type: string
        property_sub_type:
          type: array
          items:
            type: string
        elementary_school:
          type: string
        elementary_school_district:
          type: string
        middle_school:
          type: string
        middle_school_district:
          type: string
        high_school:
          type: string
        high_school_district:
          type: string
        at_a_glance_facts:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
              value:
                type: string

    FloorPlan:
      type: object
      required: [name, sqft, min_price, max_price]
      properties:
        name:
          type: string
          description: Floor plan name
        beds:
          type: integer
        baths:
          type: integer
        sqft:
          type: integer
        min_price:
          type: integer
        max_price:
          type: integer
        available_from:
          type: string
          description: 'Earliest availability date (YYYY-MM-DD)'
        lease_term:
          type: string
        allowed_pets:
          type: array
          items:
            type: string
        units:
          type: array
          items:
            $ref: '#/components/schemas/Unit'
        images:
          type: array
          items:
            type: string

    Unit:
      type: object
      properties:
        unit_number:
          type: string
        zpid:
          type: string
        price:
          type: integer
        sqft:
          type: integer
        baths:
          type: integer
        available_from:
          type: string
          description: 'Availability date (YYYY-MM-DD)'

    PriceRange:
      type: object
      properties:
        name:
          type: string
          description: 'Bedroom display name (e.g., "Studio", "1 bd")'
        beds:
          type: integer
        min_price:
          type: integer
        max_price:
          type: integer

    Amenities:
      type: object
      properties:
        building_details:
          type: array
          items:
            type: string
        laundry:
          type: array
          items:
            type: string
        pet_summary:
          type: object
          properties:
            allowed_pets:
              type: array
              items:
                type: string
            details:
              type: string
        hours:
          type: array
          description: Office hours
          items:
            type: string
        property_amenities:
          type: array
          items:
            type: string
        unit_amenities:
          type: array
          items:
            type: string
        appliances:
          type: array
          items:
            type: string
        floor_coverings:
          type: array
          items:
            type: string
        common_unit_amenities:
          type: array
          items:
            type: string
        building_amenities:
          type: array
          items:
            $ref: '#/components/schemas/AmenityGroup'
        unit_features:
          type: array
          items:
            $ref: '#/components/schemas/AmenityGroup'
        policies:
          type: array
          items:
            $ref: '#/components/schemas/AmenityGroup'
        special_features:
          type: array
          items:
            $ref: '#/components/schemas/AmenityGroup'

    AmenityGroup:
      type: object
      properties:
        category:
          type: string
        items:
          type: array
          items:
            type: string

    PetPolicyEntry:
      type: object
      properties:
        type:
          type: string
          description: 'Pet type (e.g., "cats", "dogs")'
        is_allowed:
          type: boolean
        description:
          type: string
        deposit:
          type: integer
        monthly_fee:
          type: integer
        one_time_fee:
          type: integer
        weight_limit:
          type: integer

    AffordabilityEstimate:
      type: object
      properties:
        total_monthly_cost:
          type: integer
          description: Estimated total monthly housing cost (mortgage + taxes + insurance)

    ListingProvider:
      type: object
      description: Listing source attribution for rentals (Zillow Rental Manager / partner feeds)
      properties:
        agent_name:
          type: string
        agent_license:
          type: string
        posting_website_url:
          type: string
        posting_group_name:
          type: string
        source_text:
          type: string

    RichMedia:
      type: object
      description: 3D / interactive-media tour metadata beyond the top-level virtual_tour_url
      properties:
        interactive_media_url:
          type: string
          description: 'Zillow imx (image-experience) tour URL'
        has_localized_photos:
          type: boolean
        is_lms_tour:
          type: boolean

    SpecialOffer:
      type: object
      properties:
        text:
          type: string

    NeighborhoodHighlight:
      type: object
      properties:
        name:
          type: string
        description:
          type: string

    NearbyItem:
      type: object
      properties:
        name:
          type: string
        link:
          type: string
        zpid:
          type: string
        price:
          type: integer

    StaticMap:
      type: object
      properties:
        url:
          type: string
          description: Google Static Map image URL at highest available resolution

    MortgageRates:
      type: object
      description: Current Zillow Home Loans mortgage rate buckets
      properties:
        fifteen_year_fixed:
          $ref: '#/components/schemas/MortgageBucket'
        thirty_year_fixed:
          $ref: '#/components/schemas/MortgageBucket'
        arm_5:
          $ref: '#/components/schemas/MortgageBucket'

    MortgageBucket:
      type: object
      properties:
        rate:
          type: number
          description: Annual percentage rate
        source:
          type: string
          description: 'Source of the rate quote (e.g., "ZGMI")'

    ListingSubType:
      type: object
      description: Boolean flags describing the listing sub-type
      properties:
        is_FSBO:
          type: boolean
        is_FSBA:
          type: boolean
        is_newHome:
          type: boolean
        is_forAuction:
          type: boolean
        is_comingSoon:
          type: boolean
        is_foreclosure:
          type: boolean
        is_bankOwned:
          type: boolean
        is_pending:
          type: boolean
        is_openHouse:
          type: boolean

    Seo:
      type: object
      description: SEO metadata for the building page
      properties:
        h1:
          type: string
        title:
          type: string
        description:
          type: string

    ZovInsight:
      type: object
      description: Zillow ZOV (Zillow-Owned Value) insight summarizing distinctive amenities
      properties:
        tagline:
          type: string
        tags:
          type: array
          items:
            type: string
        description:
          type: string

    MarketInsights:
      type: object
      description: Local rental market insights link
      properties:
        name:
          type: string
          description: Geographic area name
        link:
          type: string
          description: Absolute URL to the market trends page

    RelatedLink:
      type: object
      description: Geographic hierarchy entry
      properties:
        name:
          type: string
        link:
          type: string
        type:
          type: string
          description: 'Granularity level (e.g., "State", "County", "City", "Zipcode", "Neighborhood")'

    Video:
      type: object
      properties:
        url:
          type: string
          description: External video URL (typically Vimeo or YouTube)
        label:
          type: string
          description: 'Optional caption (e.g., "All units", "Unit 307F")'
        thumbnail:
          type: string
          description: Thumbnail image URL

    ThirdPartyVirtualTour:
      type: object
      properties:
        url:
          type: string
          description: External 3D or virtual tour URL
        title:
          type: string
        provider:
          type: string

    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: Zillow URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results

    SearchParameters:
      type: object
      properties:
        engine:
          type: string
        zpid:
          type: string

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong