Skip to main content
POST
A Search query costs $0.20 on Free, whatever fields it returns and however many matches it finds, including zero. Build and Growth are discounted; see Pricing. Each page is a new query.

When to use this

Use /v1/search when:
  • You have criteria, not a location: “Arizona parcels of 100–1,000 acres”.
  • You want a shortlist of parcels with their identity and a few chosen fields.
  • You want the same fields for every match in one call.
Search returns the first matches found, not a ranked list. Every filter is an AND requirement. Use /v1/enrich instead when you already have one address or coordinate and want each value with its source, confidence and interpretation hints. List every field, its filter operators and whether it can be returned with GET /v1/search/fields.

Request shape

Any other top-level property is rejected with 422.

Filters

Each filter is {field, op, value}. Operators:
  • One state is required inside filters. Use one state2 filter with eq and one two-letter code. The 50 states and DC are accepted. A county or a polygon does not replace it. Each Search covers one state; to cover several states, run one search per state.
  • county is optional. It takes a five-digit FIPS string such as "04013" (keep the leading zero) or the name of a county in the requested state. Names ignore case, punctuation and a trailing County, Parish or Borough: "Prince George's", "St. Louis County" and "Harris County" all work. A name that matches no county, or more than one, returns 422 search_invalid_filter with close spellings when there are any; the FIPS string always works.
  • scity is the situs-address city. It is not mail_city.
  • mailadd with match takes one mailing address, such as "13141 Northwest Fwy Ste 300, Houston, TX 77040". Spellings like Street/St, Suite/Ste/# and North/N match each other; a different house or suite number does not. Leave the suite out to match every suite at that street address. A ZIP is required, in the value or as a mail_zip filter with eq. Next to match, mail_zip only supplies that ZIP.
  • pvd_gisacre is parcel area in acres, computed from the boundary. gisacre is the county-reported value.
  • Send JSON numbers and booleans, not strings. Dates use YYYY-MM-DD; timestamps use UTC ISO 8601.
  • null is never a filter value. A parcel with no value for a filtered field does not match, even with ne.
The Searchable fields page lists every filter name, its type and unit. Any other name, in filters or fields, returns 422 search_invalid_filter with the message Unknown Search field: <name>.

Search inside a polygon

Use a geometry filter with a WGS84 GeoJSON Polygon or MultiPolygon. Positions are [longitude, latitude].
  • intersects matches any parcel that shares area or a boundary point with the shape.
  • within matches only parcels the shape covers entirely.
  • Holes are respected. Acreage still means the whole parcel.
  • Send only type and coordinates: no Feature wrapper, CRS or altitude.
  • Rings must be closed and valid. Split shapes that cross the antimeridian into a MultiPolygon.
A geometry filter does not return geometry. Name parcel_boundary_geojson in fields if you want the boundary.

Example: Arizona parcels with owner and zoning

Values are illustrative. The null zoning above, with no remark, means the parcel record has no zoning value.

Response shape

Each match has: fields holds plain values. It does not repeat values already at the top level: filtering on state2 adds nothing, while filtering on a county FIPS code adds fields.geoid. 0, false and empty lists are real values. Point-based fields describe analysis_point; parcel calculations describe the whole boundary. For a value’s source and confidence, call Enrich.

Remarks

Each remark has a code and a message, and may add: Keys without a value are omitted. Branch on code and path only. message and hint are written for people and may change.
Remarks never change the price.

Paging

next_cursor is the only signal that more pages may exist. A short or even empty page can still carry a cursor, so keep paging until it is null before you say no more parcels match.
  • Send the cursor as cursor with the same filters and fields. limit may change.
  • Cursors expire after one hour. After that, or after 409 dataset_changed, start again without a cursor.
  • Each page is a new query with its own price, time limit and Idempotency-Key.
  • Pages are not a snapshot. Parcel data can change between calls.

Retries

Send a stable Idempotency-Key header for each page: 8–128 letters, digits, _, ., : or -. Repeating that key with the same body returns the saved page and its original receipt without another charge. Reusing a key for a changed body returns 409 idempotency_conflict. With no key, each call is a new query. Hosted MCP accepts the same value as the idempotency_key argument. Set your HTTP client timeout to at least 210 seconds.

Errors

Validation errors return detail.error, message, issues, retryable: false, docs_url and request_id. Each issue names the input path and gives a correction hint:
Search also returns the shared account, billing and dataset errors, such as 402 spend_limit_exceeded, 409 dataset_changed and 429 rate_limited. See Errors. Do not retry an unchanged 422.

Limits

  • 10 returned matches per page by default, with a 100-result maximum.
  • 180 seconds per page for finding matches and producing their fields. A page that runs out of time returns what it found, with a time_limit_reached remark.
  • There is no filter-count limit.
  • Polygons: at most 10,000 vertices across all geometry filters, and 1,000,000 km² per shape. Larger inputs are rejected, never simplified.
  • Cursors expire after one hour.

Headers

Idempotency-Key
string | null

Body

application/json
filters
SearchFilter · object[]
required

All conditions are required; source routing is automatic. Include exactly one state2 filter with eq and one two-letter US state code (50 states and DC). Each Search covers one state; run one search per state. County is optional.

Minimum array length: 1
cursor
string | null
Required string length: 1 - 2048
fields
string[]

Public Search or Enrich fields to return alongside filter values. Results omit values already present in the parcel identity.

Minimum string length: 1
Pattern: ^[a-z][a-z0-9_]*$
limit
integer
default:10

Parcels on this page, from 1 to 100; may change between cursor requests.

Required range: x >= 1
max_cost_usd
string | null
Pattern: ^(?:0|[1-9][0-9]*)(?:\.[0-9]{1,6})?$

Response

Successful Response

matches
SearchMatch · object[]
required
next_cursor
string | null
required
remarks
SearchRemark · object[]
required
request_id
string
required
billing
PaidBilling · object | null

The charge receipt for one paid Search or Enrich operation.