POST /v1/lookup - Mireye Earth

When to use this

/v1/geocode answers “where is this address.” This endpoint answers a different question: “what are the canonical join keys for this place, and how confident should I be?” Use /v1/lookup when the input might be ambiguous, when you want a parcel attached, or when the input could be a coordinate or an APN instead of a clean address.

Every response says how it resolved and how confident it is. disposition is one of:

resolved — a coordinate, plus a parcel when the geocode cleared parcel-quality accuracy.
clarify — the input is genuinely ambiguous: multiple plausible matches at comparable confidence. You get candidates, never a silent pick.
no_match — an honest failure, with a reason.

The rule behind all three: a clarification or an honest no-match is always acceptable; a silently wrong place never is. An unqualified “1100 King St W, Toronto” can land on Toronto, Ontario or Toronto, Ohio at similar confidence — a single top-ranked geocode result can never reveal that a comparably-good alternative existed. This endpoint checks multiple candidates specifically so it can tell you when that’s happened, instead of picking one and hoping.

Request shape

Field	Type	Required	Notes
`input`	string	yes	1–256 characters. An address, a `"lat,lng"` pair, or an APN.
`include_parcel`	boolean	no	Default `true`. Set `false` to skip the parcel lookup entirely — you still get the coordinate and disposition, just no parcel attempt.
`kind`	string	no	Explicit override: `"address"`, `"coord"`, or `"apn"`. Omit to let the input’s shape decide.

Example: a clean, parcel-quality match

curl -s https://api.mireye.com/v1/lookup \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"input": "480 Berdoll Ln, Cedar Creek TX"}' | jq

{
  "disposition": "resolved",
  "lat": 30.199699,
  "lng": -97.496411,
  "resolved_address": "480 BERDOLL LN, CEDAR CREEK, TX 78612",
  "resolved_location": { "lat": 30.199699, "lng": -97.496411, "source": "address" },
  "county_fips": "48021",
  "county": "Bastrop County",
  "tract_geoid": "48021950400",
  "state_fips": "48",
  "state": "Texas",
  "block_group_geoid": "480219504001",
  "block_geoid": "480219504001000",
  "congressional_district": "TX-27",
  "cbsa_name": "Austin-Round Rock-San Marcos, TX Metro Area",
  "cbsa_code": "12420",
  "elevation_m": 152.3,
  "fema_flood_zone": "X",
  "within_floodplain": false,
  "coastal_high_hazard": false,
  "county_market": {
    "population": 106822,
    "population_growth_1yr_pct": 4.1,
    "net_domestic_migration": 3120,
    "building_permits_total_annual": 1450,
    "building_permits_sf_annual": 1200,
    "building_permits_yoy_pct": 6.2,
    "hpi_yoy_pct": 3.8,
    "employment_total": 47210,
    "employment_yoy_pct": 2.9,
    "median_household_income_usd": 78500
  },
  "in_opportunity_zone": false,
  "opportunity_zone_tract_geoid": null,
  "timezone": "America/Chicago",
  "parcel": {
    "parcel_id": "R123456",
    "apn": "...",
    "address": "480 BERDOLL LN, CEDAR CREEK, TX 78612",
    "area_m2": 20234.5,
    "geometry": "...",
    "geometry_wkt": "...",
    "owner": "PECAN GROVE FARMS #1 LLC",
    "zoning": "AG",
    "land_use": "Agricultural",
    "assessed_value_usd": 185000,
    "last_sale_date": "2019-03-14",
    "last_sale_price_usd": 210000,
    "transaction_count": 3,
    "match_type": "exact",
    "match_distance_m": 4.2,
    "match_radius_m": null,
    "source": "REGRID"
  },
  "match_method": "geocode_rooftop+point_in_parcel",
  "confidence": 0.95
}

Area, hazard, and market context

Every resolved response carries free context beyond the coordinate and parcel, gathered concurrently with the parcel lookup (not after it — a slow enrichment call never adds to the parcel leg’s latency):

Jurisdiction codes, from the same Census Geocoder call as county_fips/county/tract_geoid: state_fips, state, block_group_geoid, block_geoid, congressional_district (e.g. "TX-27"), cbsa_name/cbsa_code (the metro or micro market, e.g. "Austin-Round Rock-San Marcos, TX Metro Area").
Elevation and flood risk: elevation_m, fema_flood_zone, within_floodplain, coastal_high_hazard — the same catalog sources /v1/fetch uses (3DEP/EPQS elevation, FEMA NFHL).
County market context: county_market bundles ten metrics from five federal sources (Census PEP/BPS/ACS, FHFA, BLS QCEW) — population and its 1-year growth, net domestic migration, building permits (total, single-family, YoY %), home-price YoY %, employment (total, YoY %), and median household income.
Opportunity Zone status: in_opportunity_zone (a federal tax-incentive designation) and opportunity_zone_tract_geoid when applicable.
Timezone: timezone, the IANA zone name (e.g. "America/Chicago").

Every one of these degrades independently to null on its own failure — none of them can turn an otherwise-successful resolved into anything else. Same guarantee parcel_unavailable already makes for the parcel leg, applied to enrichment too.

Example: genuine ambiguity — never a silent pick

curl -s https://api.mireye.com/v1/lookup \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"input": "1100 King St W, Toronto"}' | jq

{
  "disposition": "clarify",
  "candidates": [
    { "resolved_address": "1100 King St W, Toronto, ON, Canada", "lat": 43.6394, "lng": -79.4223, "confidence": 0.82 },
    { "resolved_address": "1100 King St W, Toronto, OH 45871", "lat": 41.0284, "lng": -84.3247, "confidence": 0.80 }
  ]
}

Present the candidates to the user (or use a disambiguation hint you have — state, county) rather than picking the first one. Up to 3 candidates are returned per response.

Example: a lone winner in the wrong town is a no_match, never silent

Some inputs name a city Geocodio only has ONE plausible match for — but the wrong one, in a different town that happens to share the same street name and number. There’s no second candidate to offer, so this isn’t clarify; it’s an honest no_match, same governing rule as everywhere else on this page:

curl -s https://api.mireye.com/v1/lookup \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"input": "100 Main St, Columbus"}' | jq

{
  "disposition": "no_match",
  "reason": "unaddressed_or_no_match",
  "hint": "the input named a different city than the best match found ('100 Main St, Fair Bluff, NC 28439') -- treated as a non-match rather than silently resolving to a place you didn't ask for."
}

The check compares the city you named against the winning candidate’s actual city (normalizing a small set of common spelling variants — Saint/St., Mount/Mt., Fort/Ft. — so a legitimately-abbreviated city is never a false positive). It only fires when the input actually names a city; a street-only input has nothing to contradict.

Example: a parcel-lookup failure never demotes a good geocode

If the parcel vendor is unavailable — including a plan/quota issue on our end — the geocode still comes back honestly, just without a parcel:

{
  "disposition": "resolved",
  "lat": 38.8977,
  "lng": -77.0365,
  "resolved_address": "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC",
  "parcel_unavailable": true,
  "parcel_unavailable_reason": "regrid_quota_exhausted",
  "match_method": "geocode_rooftop",
  "confidence": 0.95
}

This never becomes a 5xx, and it never demotes disposition away from resolved. The geocode succeeded; only the parcel attempt didn’t, and the response says exactly why.

A coarse geocode never gets a parcel

Below parcel-quality accuracy, resolved still returns the coordinate honestly — the parcel lookup is never even attempted. This is the same mechanism that protects /v1/geocode: a range_interpolation-grade match can be off by up to ~2,872 m in rural areas, which is easily a different parcel.

Swapped coordinates are a hard error, never a nearest-match

curl -s -i https://api.mireye.com/v1/lookup \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"input": "-73.9,40.7"}'

HTTP/1.1 422 Unprocessable Entity

{
  "detail": {
    "error": "resolve_coord_bounds",
    "message": "'-73.9,40.7': lat/lng appear swapped",
    "retryable": false
  }
}

This is the one input class the design treats as a hard failure rather than a best-effort placement — a transposed lat/lng is a caller bug, not an ambiguous location, and silently “fixing” it would risk landing on a plausible-looking but wrong point.

APN-only lookup is not supported yet

Regrid’s only wired integration here is a point (lat/lng) lookup — there is no attribute-search-by-APN path. An APN-shaped input returns a clean no_match:

{
  "disposition": "no_match",
  "reason": "apn_not_supported_in_v1",
  "hint": "APN-only lookup isn't supported yet -- supply an address or coordinate."
}

Response shape

Field	Type	Notes
`disposition`	string	`resolved`, `clarify`, or `no_match`.
`lat` / `lng`	number	Present on `resolved`.
`resolved_address`	string or null	The address the geocoder actually matched, when input was an address.
`resolved_location`	object	Present on `resolved`. The uniform `{lat, lng, source}` echo every location endpoint carries — `source` is `"address"` or `"coordinate"` depending on the input kind.
`county_fips`	string or null	5-digit county FIPS. Best-effort — a free Census Geocoder lookup that never fails the request; `null` if it’s unreachable.
`county`	string or null	Census-reported county name (e.g. `"Bastrop County"`), not formatted as “County, ST”.
`tract_geoid`	string or null	11-digit Census tract GEOID, 2020 vintage.
`state_fips` / `state`	string or null	2-digit state FIPS and full state name — same Census call as county/tract.
`block_group_geoid` / `block_geoid`	string or null	Finer-grained Census geoids than tract, same call.
`congressional_district`	string or null	e.g. `"TX-27"` — same Census call, one more `layers` token.
`cbsa_name` / `cbsa_code`	string or null	The metro/micro market (Core-Based Statistical Area) this point falls in, same Census call.
`elevation_m`	number or null	Meters above sea level (3DEP/EPQS).
`fema_flood_zone` / `within_floodplain` / `coastal_high_hazard`	—	FEMA NFHL flood-risk fields — same catalog source `/v1/fetch` uses.
`county_market`	object or null	Ten county-level federal metrics — see “Area, hazard, and market context” above.
`in_opportunity_zone` / `opportunity_zone_tract_geoid`	boolean/string or null	Federal Qualified Opportunity Zone status.
`timezone`	string or null	IANA timezone name, e.g. `"America/Chicago"`.
`parcel`	object or null	Present only when a parcel-quality geocode found a trustworthy parcel. All 17 Regrid `parcel_*` fields the endpoint’s one paid call already returns.
`parcel.parcel_id` / `apn` / `address` / `area_m2` / `geometry` / `geometry_wkt` / `owner` / `zoning` / `land_use` / `assessed_value_usd` / `last_sale_date` / `last_sale_price_usd` / `transaction_count` / `match_type` / `match_distance_m` / `match_radius_m` / `source`	—	Regrid-sourced parcel detail. Premium fields (`owner`/`zoning`/`land_use`/`assessed_value_usd`/`last_sale_*`/`transaction_count`) are `null` in free-tier mode.
`parcel_unavailable`	boolean	`true` when a parcel was eligible but the lookup didn’t produce one — check `parcel_unavailable_reason`.
`parcel_unavailable_reason`	string or null	e.g. `regrid_quota_exhausted`, `no_parcel_at_point`, `parcel_match_too_far`, `parcel_lookup_transient_error`, `parcel_lookup_malformed_response`.
`match_method`	string or null	e.g. `geocode_rooftop+point_in_parcel`, `geocode_range_interpolation`, `map_click`. Present on `resolved`.
`confidence`	number or null	One confidence scale throughout — geocode-tier confidence, penalized by match distance when a parcel is attached. Present on `resolved`.
`candidates`	array or null	Present only on `clarify` — up to 3, each with `resolved_address`, `lat`, `lng`, `confidence`.
`reason`	string or null	Present only on `no_match` — e.g. `unaddressed_or_no_match`, `address_too_coarse`, `apn_not_supported_in_v1`.
`hint`	string or null	A next-step suggestion, when there is one.

Errors

Input-validation failures specific to this endpoint:

Error code	HTTP	Retryable	Meaning
`resolve_coord_bounds`	422	no	Coordinate is outside any plausible bound — including the swapped-lat/lng case above.
`resolve_invalid_input`	422	no	Input didn’t parse as an address, coordinate, or APN-shaped token.
`resolve_busy`	429	yes	Per-worker overload gate (resolve has its own — separate from `/v1/geocode`’s). `Retry-After: 3`.
`resolve_timeout`	504	yes	Did not complete within the endpoint’s deadline. `Retry-After: 5`.

A propagated address-leg failure (input that resolved to nothing at all, or hit a geocoder-level problem) shares /v1/geocode’s error taxonomy exactly: address_form_unsupported, geocode_unconfigured, geocode_forbidden, geocode_timeout, geocode_upstream_error. A parcel-leg failure is never one of these — see above, it degrades the response instead.

Limits

One input per request. No batching in V1; loop client-side.
256 characters maximum, rejected rather than truncated.
Address-leg caching follows /v1/geocode’s rules: successful geocodes cache 30 days, negatives 24 hours, form-only normalization (case/whitespace/ punctuation) — see /v1/geocode’s Limits for the full detail, since the same cache backs both.
US only, same envelope as the rest of the API.
Parcel data depends on Regrid. There is no free parcel tier — a parcel is attached only when Regrid succeeds and the match is close enough to trust; every other case is an honest parcel_unavailable, not an error.

What we keep

Same retention as /v1/geocode: the input you send (when it’s an address) is recorded alongside the coordinate it resolved to, for 30 days, so a result can be audited later. If your use case cannot accommodate this, resolve client-side and call /v1/fetch or /v1/ask with lat/lng instead.

​When to use this

​Request shape

​Example: a clean, parcel-quality match

​Area, hazard, and market context

​Example: genuine ambiguity — never a silent pick

​Example: a lone winner in the wrong town is a no_match, never silent

​Example: a parcel-lookup failure never demotes a good geocode

​A coarse geocode never gets a parcel

​Swapped coordinates are a hard error, never a nearest-match

​APN-only lookup is not supported yet

​Response shape

​Errors

​Limits

​What we keep

When to use this

Request shape

Example: a clean, parcel-quality match

Area, hazard, and market context

Example: genuine ambiguity — never a silent pick

Example: a lone winner in the wrong town is a no_match, never silent

Example: a parcel-lookup failure never demotes a good geocode

A coarse geocode never gets a parcel

Swapped coordinates are a hard error, never a nearest-match

APN-only lookup is not supported yet

Response shape

Errors

Limits

What we keep