Quickstart

1. Get an API key

Create an account on the account page with your email. We send a sign-in link; after you sign in you can create keys. Keys look like isp_live_…. Treat them like passwords: keep them on your server, never in browser or mobile code.

2. Authenticate

Send the key in one header, either Authorization: Bearer <key> or X-API-Key: <key>. Keys in the query string are rejected.

3. Fetch fields for a location

curl https://api.isopleth.dev/v1/fetch \
  -H "Authorization: Bearer $ISOPLETH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat": 30.2672, "lng": -97.7431,
       "fields": ["elevation", "slope_degrees", "nearest_substation_distance_m"]}'

Locate the point with lat/lng (WGS84) or with address (a US street address). Choose data with fields (up to 50 names) or a preset. You can send both; the result is their union.

curl https://api.isopleth.dev/v1/fetch -H "Authorization: Bearer $ISOPLETH_KEY" -H "Content-Type: application/json" \
  -d '{"address": "1600 Pennsylvania Ave NW, Washington, DC", "preset": "flood_risk"}' 

Python

import os, requests

r = requests.post("https://api.isopleth.dev/v1/fetch",
                  headers={"Authorization": f"Bearer {os.environ['ISOPLETH_KEY']}"},
                  json={"lat": 39.7392, "lng": -104.9903, "preset": "natural_hazard"},
                  timeout=60)
r.raise_for_status()
for name, f in r.json()["fields"].items():
    print(name, f.get("value"), f.get("unit"), f["status"])

JavaScript (server side)

const r = await fetch("https://api.isopleth.dev/v1/fetch", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ISOPLETH_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ lat: 47.6062, lng: -122.3321, fields: ["elevation", "slope_degrees"] }),
});
const data = await r.json();

4. Read the response

Each entry in fields has a status: ok (value present), absent (the source has nothing at or near this point; value is null) or failed (the source could not be read; see error and retryable). Failed fields are also listed in partial_failures. confidence is high, medium, low or unknown, and dataset_vintage names the edition of the source when known. Every field carries source, license and attribution, and attributions groups them by source so you can show credits once. If you display or redistribute values, show the attributions (see the API Terms).

5. Batch

curl https://api.isopleth.dev/v1/fetch/batch -H "Authorization: Bearer $ISOPLETH_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: job-2026-10-28-001" \
  -d '{"locations": [{"lat": 35.08, "lng": -106.65}, {"address": "200 E Colfax Ave, Denver, CO"}],
       "preset": "solar_siting"}' 

Results come back in the same order as locations, each with its own ok flag. The batch size limit depends on your plan. Send an Idempotency-Key (8 to 128 characters of letters, digits, _ and -) to retry a batch safely: a repeat with the same body returns the stored result and is not charged again.

6. Geocode

curl https://api.isopleth.dev/v1/geocode -H "Authorization: Bearer $ISOPLETH_KEY" -H "Content-Type: application/json" \
  -d '{"address": "350 5th Ave, New York, NY"}' 

Limits and headers

Responses include X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Lookups-Charged and X-Lookups-Remaining. On 429 or 503, wait for Retry-After seconds. GET /v1/usage shows your plan, balance and recent usage and is free. Some fields are slow because they call a live public service; these are limited per minute and you can bound the wait with max_wait_s.

Errors

Errors return JSON {"error": {"code", "message", "request_id"}}. Common codes:

Full schemas are in the API reference.