Implementing map search

Draft — source-reviewed on 22 October 2026. Runtime destination coverage, deployment and API enablement have not been verified. Examples are synthetic.

Supported geometry

Use GET /api/v1/public/property-reference?destination=TENERIFE to obtain destination.extent, including its numeric bounds and version. TENERIFE is the implemented destination. Do not hardcode unrelated islands or expand coverage from a marketing catalog.

POST /api/v1/public/properties/search requires one top-level area, either BOUNDS or POLYGON, and filters.operation. This geometry is distinct from the optional free-text filters.area.

{
  "destination": "TENERIFE",
  "area": {"kind": "BOUNDS", "south": 28.0, "west": -16.9, "north": 28.6, "east": -16.1},
  "filters": {"operation": "SALES"},
  "page": 1,
  "page_size": 24,
  "sort": "PUBLIC_ID_ASC"
}

Both bounds corners must lie inside configured coverage; south must be less than north and west less than east. Coordinates must be finite and valid. Antimeridian wrapping is unsupported. The example lies inside the source default extent; runtime reference data remains authoritative.

A polygon replaces that same area object:

{
  "kind": "POLYGON",
  "vertices": [
    {"lat": 28.1, "lng": -16.8},
    {"lat": 28.4, "lng": -16.7},
    {"lat": 28.2, "lng": -16.3}
  ]
}

Source defaults allow 3–100 distinct vertices, all inside coverage. One repeated closing vertex is accepted and removed. Repeated interior vertices, zero-area rings and nonadjacent edge intersections/touches are invalid. Holes, multipolygons, multiple simultaneous areas and radius search are not implemented. Both geometry kinds include matching boundary points.

Render permitted points only

Every search summary has required public_id, operation, view_types, catalogs and location; optional name, price, thumbnail and locality labels can populate a marker card. Use the public location.lat/lng without attempting to recover private coordinates. precision is EXACT or APPROXIMATE; label approximate points accordingly.

The geometry predicate evaluates permitted public points. A property without a usable public point is excluded from search even if its detail remains eligible. Detail location is optional/nullable: suppress the map if absent. Do not manufacture a coordinate from city, a LocalArea label or address_line.

For synthetic P9001, a point {lat: 28.15, lng: -16.6, precision: "APPROXIMATE"} is an approximate display location, never evidence of an exact address. Avoid map UI that promises doorstep directions or precise pin positioning for approximate data.

Requests, pagination and concurrency

Debounce viewport changes or provide “Search this area”; reset to page 1 whenever geometry changes. Cancel or ignore an older in-flight request after a newer viewport is selected. Commit cards, markers and pagination from the same newest successful response. Do not append old geometry's items to new results.

This is presentation pseudocode, not a transport implementation:

// Each search intent receives a monotonically increasing local sequence.
const requestSequence = nextSequence();
const result = await loadReviewedPublicSearch(request);
if (requestSequence === currentSequence()) {
  showResultForCurrentViewport(result);
}

The map shows only the returned page. total can exceed the number of visible markers; there is no separate unpaginated marker or cluster endpoint. Page size is capped by schema at 100 and may be further constrained by deployment. Offset is bounded; do not crawl every page as a substitute for a bulk map API.

States and privacy

While loading reference coverage, disable search submission. If metadata fails, show retry instead of guessing bounds. Distinguish loading, successful empty results, invalid drawing (422), disabled/unavailable API (404), throttling (429) and temporary failure (503). A map-provider loading failure should not prevent reading successfully loaded list cards. Do not send private addresses or internal identifiers to map providers.

Follow Cache-Control: no-store; avoid persistent marker datasets. Do not overlay private location data or infer investment classifications. See Search and map privacy for exact filter semantics.

Related operations

Coverage: GET /api/v1/public/property-reference; geometry search: POST /api/v1/public/properties/search; marker selection: GET /api/v1/public/properties/{public_id}. Supplied card/gallery images use GET /api/v1/public/properties/{public_id}/images/{asset_id}. Public agent photos, if shown on detail, use GET /api/v1/public/agent-images/{asset_id}.