Developer docs

Address data, v1

One header, JSON responses. Look up any US address. Cached hits are $0.005; live AI pulls are $0.02.

Get an API key Copy an example

Copy a request

Example API calls

Pick a call, switch language, copy. Swap in a key from the dashboard.

GET/api/v1/properties

Full street address in q. Cached records younger than a year return immediately.

curl -G "https://earthydata.com/api/v1/properties" \
  --data-urlencode "q=1847 Maplewood Drive, Austin, TX 78703" \
  -H "Authorization: Bearer ed_live_YOUR_KEY"

Authentication

Send the secret on every request. Prefixes are safe to display; the full key is shown once in the dashboard.

Header

Authorization: Bearer ed_live_YOUR_KEY

Endpoints

GET /api/v1/properties

Look up a street address or coordinates, or search cached records by zip, city, state, or street.

GET /api/v1/properties/fresh

Same lookup as /properties, always live. Requires q or lat+lng.

GET /api/v1/properties/:id

Fetch one property by id.

GET /api/v1/coverage

US county registry. Pass state to list counties and whether a parcel layer is wired.

Parameters

Address or coordinates trigger a lookup. zip, city, state, and street filter records already in cache. Flags accept 1 / true / yes / on, or 0 / false / no / off.

Lookup

Param	Type	Notes
`q` string	string	Street address, or lat,lng. A street number plus another token (or coordinates) starts a lookup.
`lat` number	number	Latitude. Use with lng. Range −90 to 90.
`lng` number	number	Longitude. Use with lat. Range −180 to 180.
`fresh` flag	flag	Skip cache and pull live facts. 1, true, yes, on, or empty. Alias: refresh.
`wait` flag	flag	Default true. 0, false, no, off, or async returns immediately while status is enriching.

Search

Param	Type	Notes
`zip` string	string	Exact ZIP on cached records.
`city` string	string	City name, case-insensitive.
`state` string	string	State abbreviation, case-insensitive.
`street` string	string	Street name contains match.
`limit` number	number	Search page size, 1–50. Default 10. Ignored on lookups.

Coverage takes state (e.g. WA). Without it, the response lists wired counties only.

Response

Lookups return data as an array of one record, plus status, cached, and durationMs. Null fields are omitted. If facts are still loading, status is enriching and the response includes Retry-After.

Field	Notes
id	Property id. Use with /properties/:id.
status	ready, enriching, partial, failed, or not_found.
address	Formatted street address.
city, state, zip, county	Parsed location.
lat, lng	Coordinates.
type	Property type, e.g. SINGLE_FAMILY.
beds, baths, sqft, lotSqft	Living area and lot when published.
yearBuilt, stories, floor, garage	Stories is the building floor count. floor is the unit floor for condos/apartments.
parcelId, assessedValue	Assessor fields when the county publishes them.
value	Estimated value.
lastSalePrice, lastSaleDate	Last sale, date as YYYY-MM-DD.
schoolDistrict, floodZone, hoa	Public extras when found.
notes	Public notes array, omitted when empty.

200 · ready

{
  "data": [{
    "id": "cmlx7k2ab0001",
    "status": "ready",
    "address": "1847 Maplewood Drive, Austin, TX 78703",
    "city": "Austin",
    "state": "TX",
    "zip": "78703",
    "county": "Travis",
    "lat": 30.2805,
    "lng": -97.7642,
    "type": "SINGLE_FAMILY",
    "beds": 3,
    "baths": 2,
    "sqft": 1842,
    "lotSqft": 6534,
    "yearBuilt": 1998,
    "stories": 2,
    "garage": 2,
    "parcelId": "0102030405",
    "assessedValue": 812000,
    "value": 875000,
    "lastSalePrice": 640000,
    "lastSaleDate": "2019-06-14",
    "schoolDistrict": "Austin ISD",
    "floodZone": "X"
  }],
  "status": "ready",
  "cached": true,
  "durationMs": 42
}

200 · enriching

{
  "data": [{
    "id": "cmlx7k2ab0001",
    "status": "enriching",
    "address": "1847 Maplewood Drive, Austin, TX 78703"
  }],
  "status": "enriching",
  "cached": false,
  "durationMs": 2100,
  "retryAfterSeconds": 12
}

Headers

X-Credits-Balance remaining USD
X-Credits-Charged this request
X-Credits-Kind cached or live
Retry-After seconds, when status is enriching

Credits

Pay as you go — no subscription. Top up from the dashboard when the balance runs out. Estimate volume.

Cached

$0.005

per lookup

Live

$0.02

per lookup

$1.00 starting credit — 200 cached or 50 live lookups
Top up $10.00, $25.00, $50.00, $100.00. Optional auto top-up. No subscription.

Errors

Status	Error	When
401	unauthorized	Missing or revoked API key.
402	payment_required	Not enough credits. Top up from the dashboard.
400	missing_query	/properties/fresh without q or lat+lng.
404	not_found	Unknown property id.
502	lookup_failed	Live lookup could not resolve the address.
500	query_failed	Search or fetch failed.