The API behind the land screen

The same engine that builds land screens is available to developers: REST for apps and pipelines, MCP for AI agents. Both return the same per-field envelope, with the source, dataset version and confidence on every value. Teams building site-selection tools (for example solar, storage or data center siting) can pull the grid, resource and hazard fields directly.

Request API access

The API is in early access. There are no public plans or self-serve keys yet. Tell us what you're building and we'll be in touch when keys are available.

Pre-launch: the API host api.groundtruth.example and key format are placeholders.

1. Authenticate

Send your API key as a bearer token: Authorization: Bearer $GROUNDTRUTH_API_KEY. Keep keys server-side; never ship them in a browser or mobile app.

2. Fetch a location

Ask for named fields, a preset, or both. Give either lat + lng or an address.

POST /v1/fetch

curl https://api.groundtruth.example/v1/fetch \
  -H "Authorization: Bearer $GROUNDTRUTH_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "lat": 41.878723, "lng": -87.635978,
    "fields": ["elevation", "within_floodplain_polygon",
      "nearest_osm_transmission_line_distance_m",
      "nearest_osm_transmission_line_voltage_kv",
      "huc_12_name", "wind_power_density_100m_wm2"],
    "extras": true
  }'

3. Read the envelope

Every field comes back in the same shape. absent means the source answered and there is nothing there (for example, no wetland within range). failed means an upstream error, and comes with error and retryable.

field envelope

{
  "value": 4777.1,
  "unit": "meters",
  "status": "ok",              // ok | absent | failed
  "source": "EIA_POWER",
  "source_url": "https://...",
  "confidence": "medium",
  "fetched_at": "2026-10-23T15:18:30Z",
  "dataset_vintage": "...",
  "ttl_seconds": 2592000,
  "notes": null,
  "x": {                       // only with "extras": true
    "vintage": "...", "as_of": "...",
    "substitute": false, "fallback": false, "cache_hit": true
  }
}

4. Screen many sites at once

Send up to 100 locations per call. Duplicate work inside a batch is shared, and one bad address doesn't fail the rest. max_wait_s sets a latency budget: a slow first read answers with a labelled substitute within that time, then upgrades to the primary source on the next call.

POST /v1/fetch/batch

curl https://api.groundtruth.example/v1/fetch/batch \
  -H "Authorization: Bearer $GROUNDTRUTH_API_KEY" \
  -H "Idempotency-Key: 7f9c2b1e" \
  -H "content-type: application/json" \
  -d '{
    "locations": [
      {"lat": 42.1, "lng": -93.5},
      {"address": "233 S Wacker Dr, Chicago, IL"}
    ],
    "preset": "grid_interconnect",
    "max_wait_s": 5
  }'

5. Connect an AI agent (MCP)

The MCP server exposes two tools: gt_fetch(lat, lng, fields?, preset?) and gt_list_fields(query?). It also runs over stdio for local use.

mcp config (placeholder URL)

{
  "mcpServers": {
    "groundtruth": {
      "url": "https://api.groundtruth.example/mcp",
      "headers": { "Authorization": "Bearer <YOUR_API_KEY>" }
    }
  }
}

Endpoints

POST	/v1/fetch	Fields or a preset for one location (lat + lng, or an address).
POST	/v1/fetch/batch	Up to 100 locations in one call. Index-aligned results, per-entry errors, Idempotency-Key replay for 24 h.
POST	/v1/geocode	Address to coordinates, with a quality block (match type, precision note).
GET	/v1/meta/fields	The live field catalog: names, types, units, presets, sources.
GET	/v1/meta/coverage	Implemented fields per preset.

Presets

boundaries building_lookup data_center_siting flood_risk grid_interconnect land_cover natural_hazard points_of_interest site_selection solar_siting storage_siting terrain utilities wildfire_underwrite wind_siting

Browse every field on the coverage page.

Attribution

If you display values derived from OpenStreetMap, Overture Maps, NREL datasets, Copernicus Sentinel-2 or the US Drought Monitor, show the attribution listed on the data sources page.