Document the query variants people actually use
This page is the operator-facing reference for Homecastr API and MCP integrations. It records practical request shapes, the fallback ladder, and the evidence behind the public guidance.
Directly verified from runtime-facing sources we inspected ourselves.
Verified from the current route, wrapper, or MCP handler code path.
A reasonable operational inference that still needs broader telemetry proof.
Request shape matrix
| Surface | Input shape | Route | What it does | Evidence | Inspected source |
|---|---|---|---|---|---|
| Address lookup | address | /api/v1/forecast | Geocodes first, then resolves to the forecast target used by the current product surface. | observed | /api/v1/usage + route behavior audit June 12, 2026 |
| Parcel forecast | acct | /api/v1/forecast/lot | Uses parcel account variants and returns the latest lot-level forecast fan chart for the matched account. | observed | /api/v1/usage June 12, 2026 |
| Unit forecast | acct + include_siblings | /api/v1/forecast/unit | Uses the same parcel key as lot-level forecasting, with optional sibling-unit expansion. | observed | /api/v1/usage June 12, 2026 |
| Tabblock forecast | geoid | /api/v1/forecast/tabblock | Uses a 15-digit Census GEOID20 for the highest-resolution public geography currently exposed. | observed | /api/v1/usage June 12, 2026 |
| Tract forecast | geoid | /api/v1/forecast/tract | Uses an 11-digit tract GEOID20 and an RPC wrapper so schema-cache changes do not break the public route. | observed | /api/v1/usage + tract route code June 12, 2026 |
| ZCTA forecast | zcta | /api/v1/forecast/zcta | Uses a 5-digit ZIP/ZCTA area for broad coverage when tract or parcel data is unavailable. | observed | /api/v1/usage June 12, 2026 |
| ZIP3 forecast | zip3 | /api/v1/forecast/zip3 | Exposes a regional comparison geography for quick top-of-funnel market checks. | implemented | MCP handler + route surface audit June 12, 2026 |
| County forecast | fips | /api/v1/forecast/county | Uses a 5-digit county FIPS for market-level analysis and fallback coverage. | observed | /api/v1/usage June 12, 2026 |
| State forecast | fips | /api/v1/forecast/state | Uses a 2-digit state FIPS for macro comparisons across all 50 states. | observed | /api/v1/usage June 12, 2026 |
| Legacy hex | h3_id | /api/v1/forecast/hex | Compatibility path only. Keep for old integrations, but prefer tract or tabblock for new work. | observed | /api/v1/usage + MCP handler code June 12, 2026 |
Direct table access
Used where the table shape is stable enough for the public route to query the backing forecast table directly.
Route behavior audit
RPC wrapper
Used where clients need schema-cache insulation or a multi-table compatibility layer.
Tract route + status route logic
Legacy compatibility route
Retained for older clients and direct hex-cell integrations, but not preferred for new integrations.
/api/v1/usage + MCP handler code
Fallback hierarchy
1. Address -> geocode
implementedResolve the address to a location first. If the geocode is ambiguous or missing, fail fast with a location-specific error instead of guessing.
Forecast route behavior
2. Parcel when available
observedPrefer parcel or unit coverage when the jurisdiction supports it. That is the most specific public forecast shape today.
/api/v1/usage + product behavior review
3. Tract next
observedIf parcel coverage is absent, use tract coverage as the next stable fallback for neighborhood-level forecasting.
/api/v1/usage + product flow review
4. ZCTA, county, then state
assumedBroaden geography only when finer coverage is unavailable. This is an inferred widening order from adjacent product flows and endpoint coverage, not a single canonical router.
Coverage surface inference
Status and freshness
Live-only checks
observedActive probes against API and MCP entrypoints tell us whether a route is usable right now.
/api/v1/status + /api/v1/status/history
Freshness checks
observedSource-specific checks based on as_of_date or similar recency metadata degrade when a source goes stale or the freshness field is missing.
/api/v1/status route logic + status history snapshots
Historical / monitoring-backed signals
observedPersisted usage and status snapshots are the right source for trends rather than a single live request.
/api/v1/usage + /api/v1/status/history
API builders
Start with the most specific geography you can resolve, then widen only when coverage requires it. Prefer public routes and wrapper-backed endpoints over compatibility-only hex paths.
MCP users
Pick the tool that matches the geography you already have. Use tract or tabblock for area reasoning, parcel or unit for property reasoning, and county or state for broad comparison work.
Operators
Use the status page for live health, and use persisted usage and status history when you need evidence over time.
Evidence appendix
This appendix keeps time-bound operational examples public without mixing them into the main integration guidance. Every row below records what was inspected, when it was inspected, and what that observation does and does not prove.
| Claim | Label | Inspected source | Inspection date | Verification note |
|---|---|---|---|---|
| Observed usage window for public forecast routes | observed | /api/v1/usage | June 12, 2026 | The inspected 30-day usage window showed all documented public forecast routes except /api/v1/forecast/zip3. |
| Current MCP probe example | observed | /api/v1/status/history | June 12, 2026 | The inspected snapshot recorded MCP Server as outage because the probe returned HTTP 404. That is a probe-level fact, not a durable product-health claim. |
| Current freshness example | observed | /api/v1/status/history + status route logic | June 12, 2026 | The inspected snapshot marked the HCAD / Houston freshness check as degraded because as_of_date was stale on that source. |
| Wrapper and transport behavior | implemented | Repo route audit + MCP handler code | June 12, 2026 | Used to verify wrapper-backed tract access, compatibility-only hex support, and MCP tool/transport exposure. |
Observed limits of this audit
- Not verified in PostHog event history for every endpoint shape.
- Not verified in Supabase request logs for every request variant.
- Not verified in Redis trace data for every fallback path.
- Not verified in Vercel route logs for every deployment-time behavior.
Documentation
Reference, guide, and status pages share this navigation so the public docs set stays consistent.