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—.

Detection runs on building footprints derived from high-resolution satellite remote sensing, with a confidence cut-off declared in every response.

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
  }'

Three ways to say where

By point:

curl -s -X POST "$BASE/v1/housing/evaluations" \
  -H "Authorization: Bearer $UCOTRON_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"lat": -34.121614, "lng": -59.724109, "radiusM": 50}'

A point has no area and the dataset returns footprints, so "here" needs a size: radiusM is the radius around the point, 50 m by default — a farmstead radius, covering the house and its sheds without pulling in the neighbour's — and up to 500 m. Beyond that it is a plot, and goes as a ring.

The order is [lng, lat], and Google Maps shows it the other way round.

A plot in Buenos Aires is [-59.72, -34.12]: longitude first. Copy from Google Maps — which shows -34.12, -59.72 — and paste it as-is, and the ring is geometrically valid and lands in the South Atlantic. The answer will be "no buildings detected", and it will be true: there are none in the ocean.

We cannot detect that for you: with those values both readings are valid numbers and nothing tells them apart. What we do is state which coordinates we analysed, with lat and lng named, in the report's provenance block. If the latitude there is not your plot's, this is why.

When the swap can be proven — a "latitude" above 90, which does not exist — the answer is a 422 instead of an analysis of the wrong place.

The way never to get it wrong is to send the point: lat and lng are named fields, and a named field cannot be swapped.

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 survey has a cut-off date, it is not a photo of today. A structure built afterwards does not appear, and its absence does not prove the plot is empty. The report says so.
• 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.
• The survey 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.
• The plot ring must be closed: the first and last points have to match. Otherwise the answer is 422 invalid_ring, instead of closing it on its own over a surface you did not ask for.

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