API Reference

Every request must include a bearer token in the Authorization header. Tokens are issued from your dashboard once your waitlist access is approved.

Authorization: Bearer tl_live_abc123...

• ›tl_live_ keys hit production data and count against your billed quota.
• ›tl_test_ keys route to the staging environment. Staging layers are refreshed weekly and may lag production; requests are free but rate-limited.
• ›All traffic must be TLS 1.2+. Plain-HTTP requests are rejected at the edge.

A single call to POST /v1/screen returns the full regulatory picture for a parcel. Example below uses the Austin, TX sample parcel (30.2672, -97.7431).

curl -X POST https://api.tierralens.co/v1/screen \
  -H "Authorization: Bearer tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "state": "TX",
    "lat": 30.2672,
    "lng": -97.7431,
    "layers": ["edwards", "karst", "tpdes"],
    "include_regulations": true,
    "include_permit_paths": true
  }'

{
  "state": "TX",
  "parcel": {
    "lat": 30.2672,
    "lng": -97.7431,
    "address": "South MoPac corridor, Austin, TX 78745",
    "acreage": 38.6,
    "zoning": "SF-2 w/ SOS overlay (Drinking Water Protection Zone)"
  },
  "layers_triggered": 5,
  "regulations_triggered": 6,
  "results": [
    {
      "code": "TX-EAPP-WPAP",
      "title": "Water Pollution Abatement Plan (Recharge Zone)",
      "authority": "Texas Commission on Environmental Quality (TCEQ)",
      "citation": "30 TAC §213.5",
      "risk": "high"
    },
    {
      "code": "TX-SOS",
      "title": "Austin Save Our Springs Ordinance",
      "authority": "City of Austin Watershed Protection",
      "citation": "Austin City Code §25-8-511",
      "risk": "high"
    },
    {
      "code": "ESA-7-KARST",
      "title": "ESA §7 — Karst Invertebrates",
      "authority": "USFWS Austin Ecological Services",
      "citation": "16 U.S.C. §1536; 50 CFR §17",
      "risk": "high"
    },
    {
      "code": "TX-TXR150000",
      "title": "TPDES Construction General Permit",
      "authority": "TCEQ (EPA-delegated NPDES)",
      "citation": "30 TAC §305 (TXR150000)",
      "risk": "medium"
    },
    {
      "code": "TX-RRC-SWR32",
      "title": "Statewide Rule 32 — Flaring & Venting",
      "authority": "Texas Railroad Commission",
      "citation": "16 TAC §3.32",
      "risk": "low"
    },
    {
      "code": "TX-CMP",
      "title": "Coastal Management Program Consistency",
      "authority": "Texas GLO + NOAA",
      "citation": "31 TAC §501; 16 U.S.C. §1456",
      "risk": "low"
    }
  ]
}

Every object in results is a Regulation. Set include_regulations: true (default) for the full schema including summary, permit_path, typical_timeline, and source_url.

Base URL: https://api.tierralens.co. All endpoints return JSON and are versioned under /v1. Launch coverage is TX and NY; additional states land behind a beta flag.

TypeScript types for every object the API returns. The shapes are identical across REST and MCP surfaces.

type StateCode = "TX" | "NY";

interface Regulation {
  code: string;                 // e.g. "TX-EAPP-WPAP"
  title: string;
  summary: string;
  authority: string;            // agency name
  citation: string;             // statute / rule reference
  triggered_by: string;         // why this parcel matched
  permit_path?: string;
  risk?: "low" | "medium" | "high";
  source_url?: string;
  typical_cost?: string;
  typical_timeline?: string;
}

interface DataLayer {
  id: string;                   // e.g. "tx-edwards"
  name: string;
  source: string;               // upstream feed
  color: string;                // hex, for map rendering
  icon: string;
  regulations: Regulation[];
}

interface StateProfile {
  code: StateCode;
  name: string;
  tagline: string;
  sampleParcel: {
    lat: number;
    lng: number;
    address: string;
    acreage: number;
    zoning: string;
  };
  distinctives: string[];
  layers: DataLayer[];
}

Limits are enforced per API key with a sliding 60-second window. When you exceed the limit, we return 429 rate_limited with a Retry-After header in seconds.

Higher throughput is available on enterprise plans — reach out for a dedicated rate-limit bucket and SLA.

Errors are returned as JSON with a stable error code and a human-readable message. Never parse the message for branching logic — switch on the code.

TierraLens ships a Model Context Protocol server at mcp.tierralens.co. It exposes every REST endpoint as a tool, so Claude and other MCP-aware agents can screen parcels, look up regulations, and subscribe to changes in-conversation — no adapter code required.

Drop the snippet below into your claude_desktop_config.json to wire it up:

{
  "mcpServers": {
    "tierralens": {
      "url": "https://mcp.tierralens.co",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer tl_live_..."
      }
    }
  }
}

Tools exposed: screen_parcel, list_layers, get_regulation, monitor_parcel. Auth uses the same bearer tokens as the REST API.

Breaking changes, new endpoints, and layer additions are tracked in the /changelog. Subscribe to the RSS feed there to get notified when regulations in your monitored parcels change upstream.