Housing

Answers: is there a building inside this plot? It verifies a risk declaration without visiting the field —whether the policyholder declares a shed, or declares that there is nothing there—.

The data comes from Google Open Buildings v3, a dataset of building footprints derived from high-resolution satellite imagery.

Two steps

sequenceDiagram
    participant C as Your system
    participant A as API
    C->>A: POST /v1/housing/evaluations
    A-->>C: 200 · { evaluationId, hasBuilding, buildingCount, totalAreaM2 }
    C->>A: POST /v1/housing/reports { evaluationId }
    A-->>C: 202 · job enqueued
    C->>A: GET /v1/reports/{id}/download
    A-->>C: 302 · the PDF

Evaluate

curl -s -X POST "$BASE/v1/housing/evaluations" \
  -H "Authorization: Bearer $UCOTRON_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "ring": [[-59.95,-35.05],[-59.949,-35.05],[-59.949,-35.051],[-59.95,-35.051],[-59.95,-35.05]],
    "minConfidence": 0.65
  }'

The ring is the plot polygon in [lng, lat], closed (first point repeated at the end). If the plot is already loaded, aoiRef is enough.

minConfidence is the cut below which a footprint is not counted. Lowering it increases false positives from shadows and dense vegetation; raising it loses small structures. The default is a reasonable middle ground.

The response carries hasBuilding, buildingCount, maxConfidence, totalAreaM2, and the list of footprints with centroid, area and confidence.

If status is not ok, nothing can be asserted about the plot: the message field says why.

Issue the report

curl -s -X POST "$BASE/v1/housing/reports" \
  -H "Authorization: Bearer $UCOTRON_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"evaluationId":"ev_hsg_…","locale":"en-US"}'

The PDF carries a satellite map with the plot outlined and each building marked, the size of the mark proportional to its area; the footprint table with centroid, area and confidence; and the provenance with the dataset and its snapshot date.

What breaks

When status is not ok, hasBuilding and buildingCount assert nothing: the contract prevents a failed run from reporting presence.

The full table of status codes is in Jobs, delivery and errors.

What it asserts, and what it does not

• The dataset is a snapshot, not a photo of today. A structure built after the cut does not appear, and its absence does not prove the plot is empty. The report states the snapshot date.
• It detects building footprints: it does not distinguish a house from a shed, a barn or a silo.
• Coverage is uneven outside urban areas. In sparse rural areas detection is less sensitive.
• Open Buildings provides the centroid and area, not the outline. That is why the map marks positions and sizes rather than drawing the building's shape: we do not know it.

It verifies the presence of satellite-detectable building as of the snapshot date. It does not replace a field inspection.