The API

One request, one reading.

The same engine the site runs, open to a script, a notebook, a GIS, or an agent. Send any land on Earth and get back what the instrument read: the score, the verdict, every finding behind it, the sources that answered and the ones that fell silent. No key. Every reading made this way is public and joins the wall, exactly as one made on the site does.

Endpoints

POST /api/v1/readings

Read a parcel. Send a GeoJSON Polygon, or a point with a half-side in km (0.06–12). Returns 201 with the reading and its permalink.

GET /api/v1/readings/{id}

One public reading in full. Takes a reading id, a /p slug, or a worked-example key: monteverde, guanacaste, pedasi, amazon.

GET /api/v1/readings?limit=24

The most recent public readings, as the wall lists them: place, coordinates, area, score, verdict, headline.

Read around a point

curl -X POST https://read.dearwise.earth/api/v1/readings \
  -H "Content-Type: application/json" \
  -d '{ "point": { "lat": 0.35, "lon": 36.95, "half_km": 0.6 } }'

Read an exact boundary

Positions are [longitude, latitude]; the ring closes on its first position. The engine reads 1 to 50,000 hectares.

curl -X POST https://read.dearwise.earth/api/v1/readings \
  -H "Content-Type: application/json" \
  -d '{ "geometry": { "type": "Polygon", "coordinates": [[
        [-84.812, 10.296], [-84.788, 10.296],
        [-84.788, 10.312], [-84.812, 10.312],
        [-84.812, 10.296] ]] } }'

What comes back

{
  "id": "…",
  "url": "https://read.dearwise.earth/p/…",
  "score": 72,
  "verdict": "Restore",
  "headline": "Good bones. The rest is work.",
  "area_ha": 145,
  "sources_read": ["terrain", "water", "soil", "climate", …],
  "sources_silent": [],
  "asset": { …the full reading: pillars, findings, sources, silence… }
}

A reading takes under a minute; the connection stays open until it lands. Missing sources lower confidence, never the score — a silent source is named in the asset, not filled in.

From Python

import requests
r = requests.post("https://read.dearwise.earth/api/v1/readings",
                  json={"point": {"lat": -1.9, "lon": 113.6, "half_km": 0.6}})
reading = r.json()
print(reading["score"], reading["verdict"], reading["url"])

Limits and terms

• —12 readings per hour per address, as a courtesy limit; a 429 says when it refills. Need more, for a portfolio or a research run? Write to us.
• —Readings are public, like the site's. Private readings are a TERRA Pro feature and stay on the site for now.
• —The data is public and the sources are named in every response; credit them when you publish. The lens — the weights that turn readings into a score — stays ours.
• —A reading is a first pass from orbit: a starting point for diligence and design, not a survey and not a listing.

Cross-origin requests are allowed from any origin. Responses carry X-TERRA-API-Version.