Skip to main content
Use Search to discover parcels that satisfy hard conditions. Use inline enrichment when you want cited fields for those exact matches, or standalone Enrich when you have one location to investigate. This walkthrough returns at most one parcel per Search request and makes each optional paid step explicit. It does not guarantee that the example area currently contains a match.

​
Before the first request

Create an API key and accept current terms as described in Authentication. Search and Enrich require the corresponding licensed credential grants. Set MIREYE_API_KEY in your environment; the examples use curl, jq and uuidgen. Never put a credential in a URL or a shared response file. On Free, a completed Search query costs $0.20, including a zero-match, limited or partial result. Successful enrichment costs $0.02 per delivered parcel. The ceilings below cover these rates; active-plan discounts can lower the charge. Read the returned billing receipt and Pricing for the account’s rates. Running all three requests below has a combined ceiling of $0.44. You can skip the ordinary Search when choosing inline enrichment, or skip inline enrichment when you only want to investigate one selected result separately. Each new paid operation gets a new idempotency key. Keep that key and the exact request body when recovering a lost response. The commands have no automatic retry or pagination loop. Search and its inline enrichment share a 180-second server budget; allow at least 210 seconds in the HTTP client or MCP host. Choose names from the reference for the operation you are performing: The Fetch catalog is not the complete Search or Enrich catalog. Search’s apn filter corresponds to the Enrich output parcelnumb; state corresponds to state2. Preserve APN punctuation and leading zeros, and retain state/county context.

​
1. Find one candidate

Create search-request.json:
All filters must pass. Every Search needs a positive state or state2 selection: eq with one two-letter code, or in with a nonempty list from the 50 states and DC. A county, APN or polygon filter does not replace it. For example, an APN in Maricopa County still needs state = AZ and county 04013; a polygon around Austin still needs state = TX. GeoJSON positions use [longitude, latitude]. Generate a key once for this operation, then send the request:
Basic Search returns parcel identity, the stored parcel analysis_point, and scalar filter values under fields unless already represented at the top level. Here the county FIPS is returned as fields.geoid, separately from the county name. Add public Search or Enrich names in fields for other values at the same query price. The first match found is not a ranked recommendation. limit: 1 bounds the returned count, not the number of candidates that may need evaluation. Inspect status and completion_reason before deciding what to do next:
  • complete with exhausted means the loaded candidate set was exhausted, not that the source covers every real-world parcel.
  • limited means the page limit or an internal work ceiling stopped the search.
  • partial means some work failed or timed out. Keep confirmed matches; an empty partial page does not prove that no qualifying parcels exist.
Do not weaken the user’s hard conditions to manufacture a match. If there is no candidate to review, stop here or explicitly revise the request as a new operation.

​
2. Optionally enrich the shortlist inline

For the complete current Enrich catalog on each returned parcel, create search-enriched-request.json:
This is a new Search operation, not an upgrade to the saved first response. Use a new key and no old cursor. If you already know you need these fields, begin with this request and skip the ordinary Search above. For only ownership and zoning, use basic Search with fields: ["owner", "zoning"] instead.
enrich must be a JSON boolean. With enrich: true, the entire current Enrich catalog is attempted regardless of fields. Basic fields selections never enable per-parcel enrichment billing. Inline enrichment reuses the exact selected parcel and its stored parcel lat/lon without another lookup. Each match contains enriched_fields instead of fields; read enriched_fields.owner.value, for example. Check overall status and completion_reason, then preserve each compact field’s source, confidence, optional unit and interpretation hints. The map can be sparse or empty even after a match. Billing uses internal outcomes: at least one successful or valid no-data field counts as one delivered enrichment, including partial work; invalid or all-failed enrichment incurs no Enrich unit. No matches means no enrichment units. The public map’s size cannot determine the charge.

​
3. Optionally investigate one selected parcel separately

Standalone Enrich accepts exactly one locator: an address or both lat and lng. It does not accept an APN or parcel ID as a locator. After reviewing the one candidate in search-result.json, copy its actual analysis_point coordinates into a small request. The following command refuses to continue without a usable point and sends only lat and lng, not Search’s method property:
Keep the generated key and body to recover this operation; rerunning the whole block generates a new key and can incur another charge. You can skip Search and call Enrich directly when you already know the location. Check parcel_match.status first. Only matched returns fields; ambiguous, no_match and unavailable return an empty fields map. Do not choose an ambiguous candidate automatically. Review parcel_match.parcel, parcelnumb, state2 and geoid against the selected Search result’s APN, address, state/county and source. Keep the two responses separate until the identity is resolved. Basic Search can explicitly request supported identifiers such as ll_uuid, but an identifier is not a standalone Enrich locator. Compare returned authoritative identifiers when available. Matching APNs or nearby coordinates alone cannot prove that both calls selected the same parcel. APNs can repeat across jurisdictions. Inline enrichment avoids this second-match uncertainty when the goal is to enrich the Search match itself. Standalone Enrich samples the matched parcel’s stored centroid when available, otherwise the input point (stored_parcel_centroid / input_fallback). Search uses the unchanged stored parcel lat/lon with method parcel_stored_lat_lon, even when that point is outside the polygon, so point-based values can differ even for the same parcel. Search skips candidates with invalid stored coordinates and marks the response partial. A point sample does not describe the whole boundary; only fields explicitly defined as parcel calculations do that.

​
Read returned values without losing their meaning

Enrich fields form a flat map in Enrich preset order; shared fields appear once, followed by fields outside presets in catalog order. Preserve the returned order when presenting or exporting a complete result. Standalone Enrich, mireye_enrich, and Search enriched_fields use the same sparse field projection. Each returned field contains value, source, confidence, and interpretation_hints, plus unit only when defined. Keep false and zero values. Failed fields are omitted, as are null-valued fields outside a temporary 33-field allowlist. A retained null can still mean a missing source attribute; do not assume it establishes absence. Even a matched parcel can legitimately return fields: {}. Standalone Enrich omits field source_url metadata, timestamps, vintage, TTL, notes, field status, lifecycle and failure metadata, as well as top-level fetched_at and partial_failures. Parcel identity, geocode quality, the analysis point, parcel_match.status and billing remain available. Search removes per-match field_status, enrichment, enrichment_status and enrichment_error; it keeps one outer billing receipt and overall completion status. Basic mode retains selected null values in fields. Full enrichment applies the compact omission policy to enriched_fields. Neither a missing enriched key nor a basic null is evidence of a negative finding. Fetch and Ask contracts are unchanged. Standalone Enrich can combine fields with one preset by union. Omitting or nulling both requests all 546 fields; an empty standalone fields list is invalid. Enrich has no 50-field cap. This differs from both Search’s empty-list behavior and Fetch’s explicit-field limit.

​
Continue or recover deliberately

Only request another page when more results are needed and next_cursor is non-null. Copy it as cursor while keeping filters, fields and enrich unchanged. limit may change within 1–100. Each page is a new paid query with a new key and its own cost ceiling. Cursors expire after one hour; changing enrichment mode or selected fields requires restarting without the cursor. A disconnected client does not cancel owned paid execution. Work keeps its existing deadline, and saved results remain subject to current authorization, dataset permissions and retention. Recovery does not add missing data or charge again. Follow Errors for capacity, authorization and recovery details.

​
Use the same workflow through hosted MCP

Connect through hosted MCP. Send the same Search or Enrich body inside req, with idempotency_key as its sibling. For example:
Call mireye_search with this object. Use a unique key for new work and preserve it for recovery; the displayed placeholder is not a reusable key for unrelated queries. mireye_enrich uses the same wrapper for its locator and field selection. The hosted client must allow at least 210 seconds for Search. OAuth credentials belong to the MCP connection; do not substitute them for an HTTP API key.