How to tell what our coverage claim really includes
Our public coverage directory counts source families and markets, not actor variants, endpoints, or internal collection paths. That avoids turning several technical routes to the same inventory into an inflated source count.
A source in the directory means we maintain an integration surface for it. It does not mean every field, geography, asset class, or historical date is equally available. The useful question is narrower: does the current serving snapshot contain the sources, records, fields, and observation times your workflow needs?
- Name the required markets and asset classes.
- Identify the sources that materially define inventory in each market.
- Specify required fields and acceptable omission rules.
- Define freshness and recovery expectations per source or market.
Why a successful request can still produce a failed dataset
Every source has different pagination, retry, parsing, and blocking behavior. We keep those mechanics inside the source integration while exposing one stable delivery contract to you.
We accept a collection only when its terminal state, persisted rows, reported count, identifiers, required fields, and stored artifacts agree. An HTTP 200 can still hide an empty parser result, truncated pagination, duplicate rows, or a response that never reached storage.
- Source URL and external identifiers are retained.
- Collection and snapshot timestamps are explicit.
- Partial coverage and acquisition failures identify themselves.
- Retries do not silently create duplicate deliveries or charges.
What we normalize—and what we refuse to guess
Our common schema aligns transaction type, property category, price, currency, typed areas, bedrooms, location, media, and contact information. Units and enums are explicit. Unknown values remain absent or null according to the contract instead of being filled with a convenient default.
Derived values are allowed only when their inputs and transformation are transparent. For example, price per area can be calculated when compatible price and area values are present; it should never conceal which measurements produced it.
- Retain the raw assertion beside the normalized value.
- Convert units only with explicit source units.
- Separate missing, unavailable, and not applicable states.
- Version breaking semantic or structural changes.
How we decide that two listings describe the same property
A portal listing ID identifies one source offer, not necessarily one physical property. Canonical identity uses multiple signals to associate likely offers for the same property while preserving every underlying source assertion.
We start with deterministic identifiers when they exist, then compare address, coordinates, unit, floor, area, bedrooms, description fingerprints, and media. Signals that can fail for the same reason do not count as independent proof. Every association remains reviewable and reversible because a false merge is more damaging than a duplicate row.
- Keep source offer IDs stable and queryable.
- Use several independent signals before merging.
- Preserve the offers grouped under each property.
- Make uncertain matches separable and auditable.
How old is too old depends on the decision
Different sources and markets change at different speeds. We record when a listing was first seen, last observed, and last changed so you can apply a freshness policy that fits the decision being made.
When a source is temporarily unavailable, the last-known record is not relabeled as current. Delivery can distinguish current observations, stale evidence, unavailable sources, and incomplete coverage so a customer can proceed, defer, or exclude the affected market.
- Read snapshot and observation timestamps.
- Set a maximum acceptable age for the workflow.
- Treat source unavailability separately from zero inventory.
- Contract stricter recovery objectives only where required.
What to check before trusting a delivery
Before accepting a snapshot, check that the returned count equals the rows you persisted. Then validate the schema version, required identifiers, uniqueness, freshness, completeness markers, provenance, and usage receipt.
The runtime capabilities manifest is the current authority for enabled markets, filters, limits, schemas, and machine-access gates. Static documentation explains the contract but does not override runtime state.
- Confirm returned count equals the number of rows.
- Check required identifiers and uniqueness.
- Reject stale or truncated output when the workflow requires completeness.
- Persist the request ID, usage receipt, and source context.