Cubi Estate Map API

openapi: 3.2.0
info:
  title: Cubi Estate Map API
  version: 0.1.0
  description: 'Operations tagged Map across 2 of this provider''s published API definitions: cubi-estate-openapi.json, cubi-estate-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://mcp.cubi.estate
  description: Host serving this spec (Swagger UI at https://mcp.cubi.estate/docs loads /openapi.json); also hosts the MCP endpoint https://mcp.cubi.estate/mcp
tags:
- name: Map
paths:
  /map/clusters:
    get:
      summary: Public browse-map cluster counts (§23; map_grid_mv-backed)
      description: 'Cluster counts for the /map page. z <= 4 → one marker per country

        (bbox ignored); deeper → grid cells inside `bbox` (''w,s,e,n'', required).

        Optional fast filters (price_min/max, beds_min, baths_min, area_min,

        plot_min, floor_min/max, tags=) switch the source from map_grid_mv to the

        per-listing map_listing_attrs MV (mig 320); `mode=price` (the map''s color

        switcher) does the same and adds per-cluster price quartiles p25/p50/p75.

        Anything other than `mode=price` is count mode. Counts are user-visible

        sale listings, refreshed nightly — they can lag live search ≤24 h.'
      operationId: map_clusters_map_clusters_get
      parameters:
      - name: z
        in: query
        required: true
        schema:
          type: integer
          maximum: 22
          minimum: 0
          title: Z
      - name: bbox
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Bbox
      - name: mode
        in: query
        required: false
        schema:
          type: string
          default: count
          title: Mode
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Map Clusters Map Clusters Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Map
  /map/pins:
    get:
      summary: Public browse-map pins for a small bbox (§23; deep zoom)
      description: 'Individual listings inside a small bbox (''w,s,e,n''). Guarded: malformed

        bbox → 400, area > _MAP_BBOX_MAX_AREA deg² → 400 `bbox_too_large` (checked

        before any DB work). Pins cap at _MAP_PINS_LIMIT (`truncated` flag);

        coarse-geocoded rows come back as per-centroid `approx_groups`. Accepts the

        same optional fast filters as /map/clusters (filtered path reads the

        map_listing_attrs MV, mig 320).'
      operationId: map_pins_map_pins_get
      parameters:
      - name: bbox
        in: query
        required: true
        schema:
          type: string
          title: Bbox
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Map Pins Map Pins Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Map
  /map:
    get:
      summary: Public browse-the-corpus map page (§23)
      description: 'Standalone map of the whole active corpus: country markers → grid

        clusters → street-level pins linking to /listing/{id}. Public, no auth,

        iframe-able (no XFO/CSP), `?theme=dark` + `?lang=` as on the §6 fragment.

        Cluster/pin data arrives client-side via /map/clusters + /map/pins.


        INDEXABLE since §54-D2 (was noindex + CSS-only text): canonical to

        www.cubi.estate/map, meta description, and a server-rendered #map-info

        section below the viewport (counts per country from map_grid_mv + fresh

        sample listings + the map → /chat handoff), 1 h cache, fail-soft.'
      operationId: browse_map_page_map_get
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
      tags:
      - Map
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
x-refined-from:
- cubi-estate-openapi.json
- cubi-estate-openapi.yml