> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mireye.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/enrich

> Resolve one US parcel and return cited attributes and calculations.

<Note>
  Enrich requires a Mireye bearer token and follows standard account rate limits.
  Requests currently cost zero customer credits.
</Note>

Use Enrich when you have a **specific parcel** to investigate. It resolves an address
or coordinate, establishes whether exactly one stored parcel matches, then returns
selected parcel attributes and calculations with field-level source metadata. To find
candidate parcels first, use [Search](/api-reference/search). Its optional
`enrich: true` returns the same field catalog and provenance for every matched parcel,
using Search's original parcel and interior point without a second lookup. Point-based
values can differ from a separate Enrich call, which uses the stored parcel centroid
or input fallback; whole-parcel calculations use the same original boundary.
The MCP tool [`mireye_enrich`](/mcp/tools#mireye_enrich) accepts the same Enrich
request body inside `req`.

## Quick request

```bash theme={null}
curl -s https://api.mireye.com/v1/enrich \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"lat": 40.75, "lng": -73.99, "fields": ["slope_degrees"]}' | jq
```

For local testing, replace the host with your local API address.

| Property | Type | Meaning |
| - | - | - |
| `lat`, `lng` | numbers | A US coordinate pair. Supply both together. |
| `address` | string | A US street address resolved server-side. Supply this instead of coordinates. |
| `fields` | array of field IDs | Individual Enrich names, such as `slope_degrees`, `owner`, or `zoning`. |
| `preset` | string | One named Enrich bundle, such as `terrain` or `parcel`. |

`fields` selects **individual Enrich field IDs**; `preset` selects **one bundle**.
You may supply both to request their union, with duplicates returned once.
For example:

```json theme={null}
{"lat": 40.75, "lng": -73.99, "preset": "terrain", "fields": ["owner", "slope_degrees"]}
```

The current presets are `parcel`, `zoning`, `buildings`, `valuation`, `legal`, `power`, `access`,
`water`, `terrain`, `environment`, `climate`, `hazards`, `market`, and
`constraints`. Returned `fields` stays one flat map, with related fields together
in this preset order, preserving each preset's field order. This order applies
to all fields, a preset, and an explicit selection; request order does not change
it. A field belonging to multiple presets appears once at its first preset.
Fields outside every preset follow in catalog order.

Omitting both selectors, or setting both to `null`, requests all
538 Enrich fields. An empty `fields` list and an unknown preset return 422;
unknown field IDs return `400 fields_unknown`. `"fields": ["zoning"]` requests
one field, while `"preset": "zoning"` requests the whole bundle. Enrich has no
50-field cap. Choose a small set for an initial screen; requesting all fields
can make a much larger response and invoke more producers. The
[Enrich field reference](/api-reference/enrich-fields) lists all individual IDs,
their types, units and bundle memberships. Enrich presets are independent of
[Fetch](/api-reference/fetch) presets.

## Fields excluded from Enrich

The following eight fields are excluded from Enrich's default selection and all
Enrich presets. Explicitly requesting any of them also returns
`400 fields_unknown`; they are not optional Enrich add-ons.

| Group | Field IDs |
| - | - |
| Hydrography | `huc_12_name`, `intersects_nhd_area`, `nearest_flowline_name`, `nearest_waterbody_name` |
| Water cooling | `huc12_thermoelectric_consumptive_use_m3_per_day`, `nearest_groundwater_well_depth_to_water_m`, `public_water_system_population_served`, `surface_water_supply_use_index_huc12` |

These fields remain available through [Fetch](/api-reference/fetch), with its
existing selectors and behavior. Enrich continues to support `owner_assemblage`
and all wetland fields, including parcel wetland-overlap calculations.

## Response examples

This matched response shows the identity, analysis point, and one field.
The values below illustrate the shape; they are not a live result for the
request above.

```json theme={null}
{
  "lat": 40.75,
  "lng": -73.99,
  "fetched_at": "2026-10-14T12:00:00Z",
  "resolved_location": {"lat": 40.75, "lng": -73.99, "source": "coordinate"},
  "analysis_point": {
    "lat": 40.7501,
    "lng": -73.9898,
    "method": "stored_parcel_centroid",
    "source": "parcel.centroid_lat/centroid_lon"
  },
  "parcel_match": {
    "status": "matched",
    "parcel": {
      "parcel_id": "example-parcel",
      "apn": "000001",
      "address": "100 EXAMPLE ROAD, EXAMPLE CITY, NY",
      "source": "parcel_vendor",
      "match_type": "exact_intersect",
      "match_distance_m": 0.0
    },
    "candidates": [],
    "reason": null
  },
  "fields": {
    "slope_degrees": {
      "value": 12.5,
      "unit": "degrees",
      "source": "USGS_3DEP",
      "source_url": "https://www.usgs.gov/3d-elevation-program",
      "confidence": "high",
      "fetched_at": "2026-10-14T12:00:00Z",
      "dataset_vintage": null,
      "ttl_seconds": 31536000,
      "notes": null,
      "status": "ok",
      "interpretation_hints": "Slope >15° materially raises wildfire spread risk on forested land. Slope >25° complicates conventional construction. Combine with lcms_class and dist_to_wui_m for wildfire underwriting."
    }
  },
  "partial_failures": []
}
```

When matching fails, the response is still HTTP 200 and explains why. For
example, `parcel_match: {"status": "no_match", "parcel": null,
"candidates": [], "reason": "No parcel matched the resolved point."}` is paired
with `analysis_point: null`, `fields: {}`, and `partial_failures: []`.

## Read the response in order

1. Check `resolved_location`. For an address, also inspect `geocode` and its
   `parcel_grade`, `normalized_address`, and `precision_note` before trusting a
   parcel-specific conclusion.
2. Check `parcel_match.status`. Only `matched` runs enrichment. `ambiguous` returns
   parcel candidates for clarification; `no_match` means the completed lookup found
   none; `unavailable` means matching could not be established. All three return
   `fields: {}` and no `analysis_point`.
3. For a match, inspect `analysis_point` and each requested `fields[name].status`.
   `ok` has a value, `absent` has a null value and an explanatory `notes` string,
   and `failed` has a null value plus `error` and `retryable`. Do not turn an
   absent or failed field into a zero or a negative finding.

The response also includes `lat`, `lng`, `fetched_at`, `parcel_match`, and
`partial_failures`. A matched parcel's `parcel_match.parcel` supplies its identity,
APN, address, source, and matching evidence. `analysis_point.method` is
`stored_parcel_centroid` when the stored pair exists or `input_fallback` otherwise.
It records the point used for point-based calculations; it is not a claim that
every point on the parcel has the same value.

Each field contains `value`, `unit`, `source`, `source_url`, `confidence`,
`fetched_at`, `dataset_vintage`, `ttl_seconds`, `notes`, `status`,
and `interpretation_hints`. Failed fields also have `error` and `retryable`, and
appear in `partial_failures`. The `error` and `retryable` keys are omitted when
inapplicable; other legitimate nulls, including `value`, `unit`, and unknown
timestamps or source metadata, remain present. Field `confidence` preserves the
producer's value, including `medium` for an absent NSRDB field. `lifecycle` stays
in the catalog and field discovery; it is omitted from returned field objects.
Read the field's hints before using a value as a site-wide or legal conclusion.
Field provenance can vary within one response because the selected facts come
from different sources. Search with `enrich: true` uses this same field shape
and ordering.

## Agent workflow

If you start with a broad criterion, [Search](/api-reference/search) for a shortlist.
With `enrich: true`, each result already contains the complete field map and provenance
in `enrichment`; inspect its statuses and `partial_failures`. Search's default is false.
For a separate investigation, pick a result using APN, address, state and county as
identity evidence. Enrich its address or `analysis_point` coordinate and confirm
`parcel_match.parcel` is the parcel you intended. The Search point is
an interior analysis point, but a fresh Enrich lookup may still be ambiguous or
unavailable. Never silently substitute another candidate.

Keep source URLs and per-field status with any answer you write. Retry a failed
field only when its `retryable` flag is true; ask for clarification when the
parcel match is ambiguous. An empty `fields` map after `no_match` or
`unavailable` does not mean the requested facts were absent.

## Access and errors

Authentication and coordinate/address validation follow the existing API
conventions. Invalid request shapes return 422; unknown individual field IDs
return `400 fields_unknown`. A resolved coordinate outside
the supported US envelope returns `400 coord_out_of_bounds`. Address-resolution
errors follow [Geocode](/api-reference/geocode). Account rate limits and the
shared Fetch worker-capacity limit can return 429 with `Retry-After`. See
[Errors](/api-reference/errors) for shared authentication responses.


## OpenAPI

````yaml POST /v1/enrich
openapi: 3.1.0
info:
  title: Mireye Earth
  description: >-
    Provenance-tagged geospatial data for US coordinates. POST /v1/fetch for
    deterministic field values (POST /v1/fetch/batch for up to 25 locations at
    once); POST /v1/ask for natural-language Q&A; GET /v1/meta/fields for the
    catalog.
  version: 0.16.0
servers: []
security: []
paths:
  /v1/enrich:
    post:
      summary: Enrich a parcel
      description: >-
        Requires a valid Mireye bearer token, with no plan restriction. Standard
        account rate limits apply. Resolve an address or coordinate to one
        parcel, then return selected Fetch, Regrid and polygon results. Use
        fields for individual field IDs and preset for one named Enrich bundle;
        both combine without duplicates. Omitted or null selectors mean all
        fields. Unresolved parcel matches return match evidence and empty
        fields. Currently costs zero credits.
      operationId: enrich_v1_enrich_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    EnrichRequest:
      properties:
        lat:
          anyOf:
            - type: number
            - type: 'null'
          title: Lat
        lng:
          anyOf:
            - type: number
            - type: 'null'
          title: Lng
        address:
          anyOf:
            - type: string
              maxLength: 256
              minLength: 1
            - type: 'null'
          title: Address
        fields:
          anyOf:
            - items:
                type: string
              type: array
              minItems: 1
            - type: 'null'
          title: Fields
          description: >-
            Individual Enrich field IDs, for example elevation or owner.
            Combined with preset by union; duplicates are returned once. Omit or
            use null for both selectors to request all Enrich fields.
        preset:
          anyOf:
            - type: string
              enum:
                - parcel
                - zoning
                - buildings
                - valuation
                - legal
                - power
                - access
                - water
                - terrain
                - environment
                - climate
                - hazards
                - market
                - constraints
            - type: 'null'
          title: Preset
          description: One named Enrich bundle, expanded before any additional fields.
      additionalProperties: false
      type: object
      title: EnrichRequest
      description: >-
        Address XOR lat/lng; select individual Enrich fields and/or one preset.


        Omitted/null selectors retain the all-fields default. Preset expansion
        and

        field-ID validation happen before geocoding, parcel lookup or producers.
    EnrichResponse:
      additionalProperties: true
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````