# Property Snapshot API — turn an address or listing URL into one normalized property record: status, price, sold history, key facts and valuation across the US, UK and more

> address OR listing_url → one normalized property snapshot: status, price, sold-history, core facts, valuation (where available), per-field provenance + a match block (how the address was resolved + match_confidence).
> ReefAPI engine `enrich-property` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/enrich-property/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /enrich-property/v1/snapshot — 5 credits
address OR listing_url → one normalized property snapshot: status, price, sold-history, core facts, valuation (where available), per-field provenance + a match block (how the address was resolved + match_confidence).

**Parameters:**
- `address` (string, optional) — Free-text property address (street + city + state/postcode). Provide this OR listing_url. For the most reliable match include the unit/apt and the postcode. Supported countries: US, UK, Japan.
- `listing_url` (string, optional) — A copied listing URL — routed to the right source automatically (zillow.com, redfin.com, realtor.com, rightmove.co.uk, suumo.jp). Provide this OR address.
- `country` (enum, optional) — Optional ISO country hint to skip auto-detection (US/GB/JP). Recommended when an address is ambiguous (e.g. a bare ZIP/outcode). [one of: US, GB, JP]
- `mode` (enum, optional, default "standard") — Depth of the snapshot. rich adds area market_context; cross_validated (US) reconciles facts across all 3 US sources. [one of: standard, rich, cross_validated]

**Returns:** property{address_normalized,country,source_engine,source_id,listing_url}, match{mode: url|address-search, confidence, reasons[], candidates_considered, unit_disambiguated}, status (active|for_rent|sold|off_market|unknown), price{list:{value,currency,source}, rent, sold_history[]{price,date,source}, price_per_area}, valuation{estimate,source} (null for UK — no AVM), facts{beds,baths,area{value,unit},year_built,property_type,lot_area — each {value,source,confidence}}, market_context? (rich), photos[] (refs), cross_validation? (cross_validated mode), coverage{supported,note}, provenance{per-source status+engine+missing_reason}; meta.extra.subcalls[] (contributing sources, customer-safe)

**Example request body:**
```json
{
  "listing_url": "https://www.zillow.com/homedetails/x/117892026_zpid/"
}
```

### POST /enrich-property/v1/resolve — 2 credits
address → ranked candidate listings[] (id + source + match_confidence) so the customer picks the exact property (apartment-unit / stale-listing disambiguation). The false-match-reducing flow — call this when a snapshot returns low confidence.

**Parameters:**
- `address` (string, optional) — Free-text property address (street + city + state/postcode). Provide this OR listing_url. For the most reliable match include the unit/apt and the postcode. Supported countries: US, UK, Japan.
- `country` (enum, optional) — Optional ISO country hint to skip auto-detection (US/GB/JP). Recommended when an address is ambiguous (e.g. a bare ZIP/outcode). [one of: US, GB, JP]
- `limit` (integer, optional, default 10) — Max candidate listings to return (resolve action).

**Returns:** query, country, candidates[]{source_engine, source_id, listing_url, address_line, match_confidence, match_reasons[], list_price, beds, baths, status, latitude, longitude}, count, best{...}, coverage{...}, provenance{...}

**Example request body:**
```json
{
  "address": "137 Mellison Road, Tooting, London, SW17"
}
```

### POST /enrich-property/v1/batch — 5 credits
snapshot up to 10 addresses/listing-URLs in one call (standard mode, cache-first, per-item ok/error).

**Parameters:**
- `items` (array, required) — Up to 10 addresses and/or listing URLs (array). Each is snapshotted independently; per-item ok/error.
- `country` (enum, optional) — Optional ISO country hint to skip auto-detection (US/GB/JP). Recommended when an address is ambiguous (e.g. a bare ZIP/outcode). [one of: US, GB, JP]

**Returns:** results[] (one snapshot payload or {ok:false,error} per input), count, ok_count

**Example request body:**
```json
{
  "items": [
    "0 Main St, Austin, TX",
    "1 Main St, Austin, TX",
    "2 Main St, Austin, TX",
    "3 Main St, Austin, TX",
    "4 Main St, Austin, TX",
    "5 Main St, Austin, TX",
    "6 Main St, Austin, TX",
    "7 Main St, Austin, TX",
    "8 Main St, Austin, TX",
    "9 Main St, Austin, TX",
    "10 Main St, Austin, TX"
  ]
}
```

### POST /enrich-property/v1/coverage — 0 credits
Static capability map: which countries/sources are supported, per-country source set, and the documented gaps (UK has no AVM; JP only 4 prefectures). No sub-calls.

**Parameters:** none

**Returns:** countries{US,GB,JP}{sources[], valuation, notes}, url_routing{domain→engine}, unsupported_policy

## More
- Try it live, no code: https://reefapi.com/playground?engine=enrich-property
- Human docs page: https://reefapi.com/docs/enrich-property
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt