{"version":1,"contract":{"confidence":"Figures carry confidence: 'high' | 'low' | 'unknown'. UNKNOWN MEANS THE SOURCE COULD NOT ANSWER — never treat it as zero. 'low' means measured but from thin data or a reported sampling cap.","caveats":"Every brief and score ships a caveats[] array. Read it before the numbers; it states assumptions (e.g. in-extent roads presumed impassable) and sampling limits.","degraded":"Responses with health.sourcesUsable < health.sourcesQueried are served uncached and incomplete by design. Retry later for a full read.","nulls":"A null score means the system refused to invent a number. Do not impute.","licenses":"Per-record license fields matter: ODbL-1.0 sources are share-alike; CDLA/CC0/public-domain are permissive. Keep them separable downstream."},"tools":[{"name":"hazard_events","method":"GET","path":"/earth/events","params":{},"returns":"Active GDACS events with extent bboxes (posQuality: modeled-bbox), alert levels, provenance."},{"name":"event_brief","method":"GET","path":"/earth/event-brief","params":{"id":"event id, e.g. FL1102983"},"returns":"Exposure/lifelines/condition/observation joins for one event; every figure has confidence; caveats[] first-class. First generation ~30s, then cached 30min.","latency":"up to 60s cold"},{"name":"event_changes","method":"GET","path":"/earth/event-changes","params":{},"returns":"New/escalated/deescalated/resolved events, newest first, plus history-subsystem status."},{"name":"site_intel","method":"GET","path":"/earth/site-intel","params":{"lat":"deg","lon":"deg","radius":"m, 100-3000","category":"optional, e.g. cafe — enables saturation factor"},"returns":"Explained site score: signed contributions, per-feature confidence, caveats, evidence geometry. score:null when too little is known.","latency":"up to 60s cold"},{"name":"site_scan","method":"GET","path":"/earth/site-scan","params":{"bbox":"w,s,e,n (max 0.05 deg span)","category":"optional"},"returns":"Ranked grid cells with per-cell confidence and nearest-road distance."},{"name":"places_bbox","method":"GET","path":"/earth/places","params":{"bbox":"w,s,e,n"},"returns":"Overture places (CDLA-permissive) in the box, sampled."},{"name":"infrastructure_bbox","method":"GET","path":"/earth/infrastructure","params":{"bbox":"w,s,e,n"},"returns":"Communication + power structures (ODbL, surveyed positions). Coverage is very incomplete: absence is unknown, not zero."},{"name":"twin_earth","method":"GET","path":"/earth/w/twin_earth","params":{},"returns":"All live twin layers plus unavailable[] naming absent layers and why."},{"name":"place_trends","method":"GET","path":"/earth/place-trends","params":{"bbox":"w,s,e,n (max 1 deg/side, Indonesia archive coverage)"},"returns":"Map churn between the two newest archived snapshots: appeared/disappeared by id with named samples. Conflates real change with mapping activity — the caveat ships in-band."},{"name":"street_measure","method":"GET","path":"/earth/street-measure","params":{"lat":"deg","lon":"deg","maxM":"artifact search radius, 50-400 (default 150)"},"returns":"Phase B geometry measured from street photos (metric depth × angular extent, no lidar): road width with method and spread, per-scene calibration verdict (detected vehicles measured against physical priors — scaleTrust ships in-band), and a georeferenced object inventory (label, distance, size, bearing, derived coordinates; heightIsLowerBound when the frame cut the object). measured:false = this ground has not been measured, which is not zero."},{"name":"sweep_request","method":"POST","path":"/earth/sweep-request","params":{"lat":"deg","lon":"deg","radius":"m, 200-1000 (default 450)"},"returns":"Queue a precision sweep for unswept ground. Coverage grows where agents ask: the sweep engine processes the queue and the area goes live in seen_layer when done (typically minutes to hours). Already-covered ground returns queued:false with the reason. The queue is public at GET /earth/sweep-queue."},{"name":"seen_layer","method":"GET","path":"/earth/seen","params":{"lat":"deg","lon":"deg","radius":"m, 100-1500 (default 450)"},"returns":"Batch precision detections (tree/vehicle/building/water) swept offline by a local open-vocabulary detector over imagery tiles, georeferenced, with per-box scores and region flags for canopy clusters. covered:false = this ground has not been swept, which says NOTHING about what stands on it. The precision half of the SEEN layer; tile_detect is the interactive hint half."},{"name":"tile_detect","method":"GET","path":"/earth/detect-tile","params":{"z":"17-20","x":"tile x","y":"tile y"},"returns":"The SEEN layer for one imagery tile: VLM bounding boxes (tree/vehicle/building/water) with per-box confidence, both tile-normalized and georeferenced. Uncalibrated vision, the counterpart of environment_features' MAPPED layer — compare them, never blend them. Absence of a detection is not absence on the ground.","latency":"2-10s cold, then cached 7d"},{"name":"environment_features","method":"GET","path":"/earth/environment","params":{"lat":"deg","lon":"deg","radius":"m, 100-800 (default 400)"},"returns":"The fundamental fixed furniture of a place: mapped trees + tree rows, gates, communication towers, power structures and power lines. Mapped positions only (OSM ODbL + Overture archive); health{} names which source answered, and ABSENCE IS UNKNOWN, NOT ZERO — coverage is sparse. Heights are not in the data; renderers use class priors."},{"name":"road_geometry","method":"GET","path":"/earth/road-geometry","params":{"lat":"deg","lon":"deg","radius":"m, 100-1000 (default 400)"},"returns":"Road centerlines with the street-class width prior attached (ruasWidthM = one direction of carriageway, a MODEL not a measurement; two-way is typically ~2 ruas; null = class outside the model). The spatial boundary an agent can reason and measure against; the caveat ships in-band."},{"name":"environmental_fingerprint","method":"GET","path":"/earth/fingerprint","params":{"lat":"deg","lon":"deg"},"returns":"Hudhud v0 environmental fingerprint: passable width, sidewalk, surface, obstacles, signage, lighting, overhead clearance and flood evidence, read by a VLM from nearby street photos with the scale anchors it used, cross-checked against the street-class width prior. Figures ship confidence + source; disagreements are disclosed, not averaged.","latency":"5-60s cold (multi-image VLM; may ride out one quota window), then cached 6h"}],"mcp":"POST /mcp — the same tools as a Model Context Protocol server (streamable HTTP, stateless), for agents that speak MCP rather than REST.","fairUse":"Keyless by default. Anonymous traffic: 120 req/min per IP. A free key (X-Api-Key or ?key=) raises it to 600 req/min and names your usage at GET /earth/usage. The contract lives at GET /earth/limits."}