SitePath API

Authentication

Every request (except /health) must include an API key in the Authorization header.

curl https://www.sitepathintel.com/api/v1/counties \
  -H "Authorization: Bearer sp_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Create a key

If your account has API access, open your account → API keys and click Create new key. Give it a descriptive name (e.g. "Production CRM"). The full key is shown once — copy it to a secrets manager immediately. We store only an irreversible hash; lost keys must be revoked and recreated.

Limits: up to 10 active keys per account (contact us to raise). Revoking a key takes effect within 60 seconds.

Versioning

The API is versioned two ways. The path version (/api/v1) changes only for a rewrite that breaks the URL surface. Day-to-day changes are governed by a dated version — the current one is 2026-08-01, returned on every response as the X-API-Version header.

We add fields and endpoints without a version bump, so write tolerant parsers (ignore unknown fields). A change that removes or renames a field ships under a new dated version; we announce it to active API customers and serve Deprecation and Sunset headers on the old behavior for a transition window before it's retired.

Request IDs

Every response includes a Request-Id header (e.g. req_0a1b2c…), and every error repeats it in the body as request_id. Log it. When you contact support about a specific call, quote the request id and we can find it immediately.

Pagination

List endpoints (/counties, /projects, /changes) return a consistent envelope. Records live in data; each carries its own object type.

{
  "object":      "list",
  "data":        [ { "object": "project", … }, … ],
  "has_more":    true,
  "next_cursor": "eyJvIjo1MDB9",   // opaque — pass back as ?cursor=
  "total":       1284
}

To page, pass limit and the previous response's next_cursor as ?cursor=. Stop when has_more is false (next_cursor is then null). Treat the cursor as opaque — don't construct or parse it.

Rate limits & quota

Two per-key limits apply. A short burst limit (sliding window) and a monthly request ceiling:

Every 2xx response reports where you stand, so you can self-throttle instead of hitting errors:

Exceed the burst limit and you get 429 rate_limited; exhaust the monthly ceiling and you get 429 monthly_quota_exceeded. Both include Retry-After (seconds) — back off and retry.

Errors

Errors return a typed JSON object plus the request id. Branch on error.type (a stable class) or error.code (specific) — never on the message text.

{
  "error": {
    "type":    "authentication_error",
    "code":    "invalid_key",
    "message": "Invalid or revoked API key.",
    "doc_url": "https://www.sitepathintel.com/api-docs#errors"
  },
  "request_id": "req_0a1b2c3d…"
}

Types: authentication_error (401), permission_error (403), invalid_request_error (404/405), rate_limit_error (429), api_error (5xx). Codes you might see:

OpenAPI & tools

A machine-readable OpenAPI 3.1 spec describes every endpoint, parameter, schema, and error. It's public (no key needed):

curl https://www.sitepathintel.com/api/v1/openapi.json

Import it into Postman or Insomnia (File → Import → URL), or generate a typed client in your language with openapi-generator. The spec's version matches the dated X-API-Version.

Official libraries

Hand-crafted, zero-dependency clients with auto-pagination, retries, ETag caching, and typed errors:

pip install sitepath            # Python 3.8+
npm install @sitepath/api       # Node 18+

Webhooks Preview

Instead of polling /changes, register an endpoint and SitePath will POST signed events to it as the dataset updates. Manage endpoints from your account; each gets its own signing secret (shown once, revealable later).

Event types

• change.created — a new row in the change feed
• county.updated — a county's score or status changed
• moratorium.changed — a moratorium was enacted or lifted
• project.status_changed — a project decision changed status

Event payload

POST https://your-endpoint.example.com/sitepath
SitePath-Signature: t=1893456000,v1=<hmac-sha256>

{
  "object":  "event",
  "id":      "evt_…",
  "type":    "change.created",
  "created": "2026-08-04T00:00:00Z",
  "data":    { … the change/county/project record … }
}

Verify the signature

Compute HMAC-SHA256(secret, "<t>.<raw-body>") and compare (constant-time) to the v1 value. Reject if t is more than 5 minutes old (replay protection). Always verify before trusting a payload.

# Python
import hmac, hashlib, time
def verify(secret, header, raw_body, tolerance=300):
    parts = dict(kv.split("=") for kv in header.split(","))
    if abs(time.time() - int(parts["t"])) > tolerance: return False
    expected = hmac.new(secret.encode(), f'{parts["t"]}.{raw_body}'.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Health check

{ "object": "health", "status": "ok", "api_version": "2026-08-01", "ts": "2026-08-01T13:00:00.000Z" }

Counties — list

curl "https://www.sitepathintel.com/api/v1/counties?state=TX&grade=A&limit=5" \
  -H "Authorization: Bearer $SITEPATH_API_KEY"

{
  "object": "list",
  "has_more": true,
  "next_cursor": "eyJvIjo1fQ",
  "total": 14,
  "data": [
    {
      "object": "county",
      "fips": "48001",
      "state": "Texas",
      "stateCode": "TX",
      "county": "Anderson",
      "score": 36.9,
      "grade": "B",
      "rank": 12,
      "population": "57735",
      "lat": 31.8133,
      "lng": -95.6526,
      "ordinanceStatus": "Y",
      "hasMoratorium": false,
      "trajectory": "stable",
      "trajectoryLabel": "Stable",
      "trajectoryDelta12mo": 0,
      "dcStatus": "no-activity",
      "dcStatusLabel": "No Specific Activity"
    }
  ]
}

Counties — detail

curl https://www.sitepathintel.com/api/v1/counties/51117 \
  -H "Authorization: Bearer $SITEPATH_API_KEY"

Changes feed

BESS dataset

Data Centers dataset

Project pipeline

curl "https://www.sitepathintel.com/api/v1/projects?state=TX&status=denied&minMw=50&verificationLevel=per-project" \
  -H "Authorization: Bearer $SITEPATH_API_KEY"

{
  "object":            "project",
  "projectId":         "48201-...",
  "name":              "…",
  "developer":         "",            // empty = not recorded (NEVER inferred)
  "technology":        "solar",       // solar | bess | data-center
  "capacityMw":        "260",         // string; empty = not recorded
  "capacityMwh":       "",            // BESS only
  "acres":             "",
  "status":            "approved",
  "filedDate":         "",
  "decisionDate":      "2024-12-02",
  "lastStatusCheck":   "2026-04-15",  // solar only; when the status was last reverified
  "lastStatusChange":  "2024-12-02",  // solar only; when the status last changed
  "docketNumber":      "",
  "fips":              "48201",
  "stateCode":         "TX",
  "state":             "Texas",
  "county":            "Harris",
  "summary":           "",            // narrative source text (BESS / DC) when applicable
  "verificationLevel": "category",    // see table above
  "sourced":           true,          // is this record backed by a verified source?
  "source": {                         // source SIGNAL only — the URL is intentionally not exposed
    "publisher":   "EIA / state PUC",
    "reliability": 0.5,               // 0–1 confidence in the source
    "tier":        "category",
    "verified":    true,
    "lastChecked": "2026-08-01 10:57:00+00:00"
  }
}

Data integrity

The API serves the same datasets the rest of SitePath uses — there's no separate "API copy" that could drift. Every field traces back to a primary government document; if a value can't be verified, it isn't published.

The county dataset (data-public.js) is regenerated on the same cadence as the website. BESS and Data Center datasets refresh on the same automated sync cadence. The changes feed reflects whatever the last sync produced.

If you spot incorrect data, email support@sitepathintel.com with the FIPS code and the field — we verify and correct within 48 hours, and the fix shows up in the next API response.

Changelog

2026-08-01 — developer-experience upgrade

The wire API is now dated (X-API-Version: 2026-08-01). New: a Request-Id on every response (and in every error); typed error objects (error.type / code / doc_url + request_id); a consistent list envelope (object, data, has_more, opaque next_cursor, total) with an object type on every record; X-RateLimit-Reset and IETF RateLimit headers; and a public OpenAPI 3.1 spec. List responses moved from { counties: […] }/{ projects: […] } to { data: […] }, and cursors are now opaque tokens.

v1.2 — source signal, not source links

API responses now expose the source signal — publisher, reliability, verified, lastChecked — in place of raw source URLs, across /projects, /bess, /data-centers, and /changes. Each project also carries a sourced boolean. No data fields were removed. This keeps every record independently gradable for trust while the curated source-link corpus stays out of bulk export.

v1.1 — project pipeline enrichment

The /projects endpoint now returns BESS and data-center decisions in addition to solar. New fields: verificationLevel, summary (narrative source text), lastStatusCheck, lastStatusChange, capacityMwh (BESS). New query parameter: verificationLevel for filtering by evidence tier.

v1.0 — initial release

Endpoints: /health, /counties, /counties/:fips, /changes, /bess, /data-centers, /projects. Bearer-token auth via sp_live_* keys. Per-key rate limits.