AcreEyes API

Version 1 · base URL https://acreeyes.com/api/v1 · machine-readable spec openapi.json

Run the same parcel report as acreeyes.com from your own code: send a parcel number, address or point and get the full report back as JSON and PDF.

Authentication

Send your key in the header on every request: Authorization: Bearer ae_live_…. A key in a URL is refused (400 key_in_url), because URLs end up in logs.

How a report works

POST /runs answers at once with a run in status queued. A report takes one to three minutes: poll GET /runs/{run_id} (or watch /stream) until the status is done, then fetch result.report. One report counts against your plan when a run finishes and saves an analysis; failed and cancelled runs are free. Send an Idempotency-Key header so a retried start never runs twice.

Errors

Every error is JSON: {"error": code, "message": …, "request_id": …}. 401 unauthorized, 403 missing_scope / quota / not_subscribed, 404 not_found, 429 rate_limited / busy (honour Retry-After), 503 when your plan can't be checked. Quote the request_id when you ask for help.

Endpoints

Account

GET /health

Service health no key needed

GET /me

Your key, plan and this month's usage

GET /regions

States AcreEyes covers

GET /profiles

Scoring profiles and the Eyes

GET /usage

Charged runs in a month

Parameters

NameInTypeDefaultDescription
monthquerystring

Runs

POST /resolve

Check a parcel resolves (free) needs runs:write

Check a PIN or address resolves to a parcel before spending a run. Free; advisory (the run resolves it again). Always 200 with a `status`.

Request body

NameInTypeDefaultDescription
parcel *bodystringA PIN or an address; comma-separate several PINs.
countybodystringThe county, when a PIN exists in several.
statebodystringID

POST /runs

Start a report needs runs:write

Request body

Give exactly one of `pin`, `address` or `point`.

NameInTypeDefaultDescription
pinbodystringAssessor parcel number, e.g. RP58N02E070150A.
countybodystringWith `pin` only: the county, when the PIN exists in several.
addressbodystringA site address.
pointbodynumber[][longitude, latitude] inside the state.
statebodystringIDTwo-letter state code (GET /regions).
well_radius_milesbodynumber (0.1–10)2
good_well_gpmbodynumber (0.1–500)10The yield a well must reach to count as good.
stream_radius_milesbodynumber (0.1–5)1
advertised_acresbodynumber (0.01–1e+06)Optional: the acreage the listing advertises. Compared with the mapped parcel's acreage, never used in its place; a large gap is reported (and can hold the grade), saying when only part of the parcel may be for sale.
profilebodystringA scoring profile name (GET /profiles).
weightsbodyobject | stringPer-Eye multipliers: {"water": 2} or "water:2,hazard:1.5".
eyesbodystring[] | stringWhich Eyes the report shows (every lookup still runs): ["water", "hazard"] or "water,hazard"; absent = all.
skip_soilsbodybooleanFalseSkip the soils lookups.
skip_terrainbodybooleanFalseSkip the terrain lookups.
skip_streamsbodybooleanFalseSkip the streams lookups.
skip_hazardsbodybooleanFalseSkip the hazards lookups.
skip_diligencebodybooleanFalseSkip the diligence lookups.
skip_imagerybodybooleanFalseSkip the imagery lookups.
kindbody"analyze" | "find"analyze`find` (land discovery) needs the owner-only `find` scope.
sourcebody"auto" | "live" | "mirror"autoOwner keys only: read mirrored data live or from the local copy.
debugbody"trace" | "verbose"Owner keys only: trace detail.

GET /runs

List runs

Parameters

NameInTypeDefaultDescription
statusquerystring
sincequerystring
beforequerystring
limitqueryinteger50
key_idquerystring

GET /runs/{run_id}

Get a run

Parameters

NameInTypeDefaultDescription
run_idpathstring

POST /runs/{run_id}/cancel

Cancel a run needs runs:write

Parameters

NameInTypeDefaultDescription
run_idpathstring

GET /runs/{run_id}/logs

A run's output lines

Parameters

NameInTypeDefaultDescription
run_idpathstring
afterqueryinteger0
limitqueryinteger2000

GET /runs/{run_id}/stream

Watch a run live (server-sent events)

Server-sent events. Every log line is a plain `data:` message (a JSON string); structured events ride alongside it — `stage`, `flag`, `result`, `choices` (see StreamEvents) — and `end` carries the final run.

Parameters

NameInTypeDefaultDescription
run_idpathstring

GET /runs/{run_id}/debug

A run's debug summary

The run's debug trace. Customer keys: a redacted summary. Owner keys with `debug:full`: the full summary, and with `events=true` raw events from byte offset `after` (poll with the returned `next` to tail a live run).

Parameters

NameInTypeDefaultDescription
run_idpathstring
eventsquerybooleanFalse
afterqueryinteger0
limitqueryinteger2000

GET /runs/{run_id}/debug/download

Download a run's raw trace needs debug:full

Parameters

NameInTypeDefaultDescription
run_idpathstring

Analyses

GET /analyses

List saved analyses needs analyses:read

Parameters

NameInTypeDefaultDescription
profilequerystring
weightsquerystring

GET /analyses/{aid}

An analysis: summary and raw engine result needs analyses:read

Parameters

NameInTypeDefaultDescription
aidpathstring
profilequerystring
weightsquerystring

GET /analyses/{aid}/report.json

The report as JSON needs analyses:read

The full screening report as JSON (schema acreeyes.report/1): everything the PDF says, as data. `/v1/analyses/{id}` is the raw engine result.

compact=true leaves out the per-Eye detail and tables (`omitted` names them): about a quarter of the size, keeping the score, decision brief, flags and key facts.

Parameters

NameInTypeDefaultDescription
aidpathstring
hide_ownerquerybooleanFalse
compactquerybooleanFalse
profilequerystring
weightsquerystring

GET /analyses/{aid}/pdf

The report as a PDF needs analyses:read

Parameters

NameInTypeDefaultDescription
aidpathstring
brandquerystring
hide_ownerquerybooleanFalse
profilequerystring
weightsquerystring

GET /analyses/{aid}/maps/{name}.png

One report map (PNG, or JPEG when drawn over the aerial photo) needs analyses:read

Parameters

NameInTypeDefaultDescription
aidpathstring
namepathstring

POST /analyses/{aid}/share

Create a share link needs shares:write

Parameters

NameInTypeDefaultDescription
aidpathstring

Request body

NameInTypeDefaultDescription
brandbodystringYour brand name on the shared page.
prepared_forbodystringWho the report was prepared for.
hide_ownerbodybooleanTrueLeave the owner's name off.
listing_urlbodystringA link back to the listing.

Public-data rural land screening. AcreEyes is a public-data screening tool. Results are not a survey, appraisal, title search, septic or well approval, flood determination, water-right opinion or buildability opinion. Verify with the county and licensed professionals before relying on them.