Casa Intelligence Widget API

openapi: 3.2.0
info:
  title: Casa Intelligence Engine Widget API
  description: Proprietary data ingestion, analysis, and prediction engine for Queensland property development intelligence.
  version: 2.0.0
tags:
- name: Widget
paths:
  /api/v1/widget/geocode:
    get:
      tags:
      - Widget
      summary: Widget Geocode
      description: 'Geocode an address. Without magic_key: SEQ-biased, up to 8 candidates (the

        Chrome Extension''s path). With magic_key: the one suggested address, exact.

        No auth required — proxies the free ArcGIS geocoder.'
      operationId: widget_geocode_api_v1_widget_geocode_get
      parameters:
      - name: address
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          description: Address to geocode
          title: Address
        description: Address to geocode
      - name: magic_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 400
          - type: 'null'
          description: 'From /geocode/suggest: resolves that one suggestion exactly, no bias'
          title: Magic Key
        description: 'From /geocode/suggest: resolves that one suggestion exactly, no bias'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/widget/geocode/suggest:
    get:
      tags:
      - Widget
      summary: Widget Geocode Suggest
      description: Australia-wide address suggestions with no bias, for the website's autocomplete. Each carries a magic_key for /geocode.
      operationId: widget_geocode_suggest_api_v1_widget_geocode_suggest_get
      parameters:
      - name: text
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 300
          description: What the visitor has typed so far
          title: Text
        description: What the visitor has typed so far
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/widget/property:
    get:
      tags:
      - Widget
      summary: Widget Property Lookup
      description: 'Property intelligence for Chrome Extension and widgets.


        Accepts address (required) plus optional lat/lng for reliable spatial lookup.

        `?v=3` additionally attaches the `intelligence_v3` block (scenario ladder,

        measured yield, planner''s take — SPEC-EXTENSION-V3.md §4); without it the

        response keeps the pre-v3 shape so the published extension keeps working.


        Resolution strategy:

        1. Try DB cache (fast path, <50ms)

        2. Try DB live queries (address match → prefix → street → spatial)

        3. Geocode address → fetch from public QLD APIs (never 404 for valid SEQ address)


        When the database is unavailable, skips straight to public API fallback.'
      operationId: widget_property_lookup_api_v1_widget_property_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: address
        in: query
        required: true
        schema:
          type: string
          minLength: 3
          description: Property street address
          title: Address
        description: Property street address
      - name: lat
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Latitude (for spatial lookup)
          title: Lat
        description: Latitude (for spatial lookup)
      - name: lng
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Longitude (for spatial lookup)
          title: Lng
        description: Longitude (for spatial lookup)
      - name: v
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Response version — 3 adds intelligence_v3
          title: V
        description: Response version — 3 adds intelligence_v3
      - name: land_area
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Listing's stated land size in m² (from the REA/Domain page). Used ONLY to disclose a multi-lot holding when it materially exceeds the resolved title area; never affects the resolved parcel.
          title: Land Area
        description: Listing's stated land size in m² (from the REA/Domain page). Used ONLY to disclose a multi-lot holding when it materially exceeds the resolved title area; never affects the resolved parcel.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetPropertyResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetErrorResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HoldingBlock:
      properties:
        is_partial_holding:
          type: boolean
          title: Is Partial Holding
          default: true
        resolved_area_m2:
          type: number
          title: Resolved Area M2
        listing_area_m2:
          type: number
          title: Listing Area M2
        ratio:
          type: number
          title: Ratio
        note:
          type: string
          title: Note
      type: object
      required:
      - resolved_area_m2
      - listing_area_m2
      - ratio
      - note
      title: HoldingBlock
      description: 'Partial-holding disclosure — the listing spans more than the one title

        we resolved. Never fabricated: only present when a trustworthy listing land

        size is materially larger than the resolved parcel.'
    WidgetOverlay:
      properties:
        category:
          type: string
          title: Category
        severity:
          type: string
          title: Severity
          default: Medium
      type: object
      required:
      - category
      title: WidgetOverlay
      description: Compact overlay summary for widget display.
    WidgetPropertyResponse:
      properties:
        property_id:
          type: string
          title: Property Id
        address:
          anyOf:
          - type: string
          - type: 'null'
          title: Address
        suburb:
          anyOf:
          - type: string
          - type: 'null'
          title: Suburb
        lga:
          type: string
          title: Lga
        development_score:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Development Score
          default: 0
        score_label:
          type: string
          title: Score Label
          default: Not Assessed
        score_tier:
          anyOf:
          - type: string
          - type: 'null'
          title: Score Tier
        tier_color:
          anyOf:
          - type: string
          - type: 'null'
          title: Tier Color
        score_breakdown:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Score Breakdown
        zone_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Zone Code
        zone_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Zone Name
        allows_subdivision:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Allows Subdivision
        area_m2:
          anyOf:
          - type: number
          - type: 'null'
          title: Area M2
        min_lot_area_m2:
          anyOf:
          - type: number
          - type: 'null'
          title: Min Lot Area M2
        overlay_count:
          type: integer
          title: Overlay Count
          default: 0
        overlay_severity:
          type: string
          title: Overlay Severity
          default: None
        overlays:
          items:
            $ref: '#/components/schemas/WidgetOverlay'
          type: array
          title: Overlays
          default: []
        nearby_da_count:
          type: integer
          title: Nearby Da Count
          default: 0
        nearby_decided:
          type: integer
          title: Nearby Decided
          default: 0
        nearby_approved:
          type: integer
          title: Nearby Approved
          default: 0
        nearby_approval_rate:
          anyOf:
          - type: number
          - type: 'null'
          title: Nearby Approval Rate
        avg_days_to_decision:
          anyOf:
          - type: integer
          - type: 'null'
          title: Avg Days To Decision
        top_comparables:
          items:
            $ref: '#/components/schemas/WidgetComparableDA'
          type: array
          title: Top Comparables
          default: []
        report_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Report Url
        holding:
          anyOf:
          - $ref: '#/components/schemas/HoldingBlock'
          - type: 'null'
        data_freshness:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Data Freshness
      type: object
      required:
      - property_id
      - lga
      title: WidgetPropertyResponse
      description: 'Slim response optimized for the Developer Window widget.


        Contains only the data needed to render the widget panel.

        Sub-200ms target response time via pre-computed materialized view.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    WidgetErrorResponse:
      properties:
        error:
          type: string
          title: Error
        detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Detail
      type: object
      required:
      - error
      title: WidgetErrorResponse
      description: Error response for widget API.
    WidgetComparableDA:
      properties:
        da_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Da Id
        address:
          anyOf:
          - type: string
          - type: 'null'
          title: Address
        decision:
          anyOf:
          - type: string
          - type: 'null'
          title: Decision
        lots_proposed:
          anyOf:
          - type: integer
          - type: 'null'
          title: Lots Proposed
        days_to_decision:
          anyOf:
          - type: integer
          - type: 'null'
          title: Days To Decision
        distance_m:
          anyOf:
          - type: integer
          - type: 'null'
          title: Distance M
        application_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Application Type
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      type: object
      title: WidgetComparableDA
      description: Minimal comparable DA for widget display (top 3).
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key