isopleth
v0.1.1
Published
Official JavaScript/TypeScript client for the Isopleth API: public location data and parcel records for any US point, plus ready-made tools for OpenAI, Anthropic and Vercel AI SDK agents.
Maintainers
Readme
isopleth
Official JavaScript/TypeScript client for the Isopleth API: public-dataset facts for any US location (terrain, flood, wildfire, weather, power grid, utilities, environment, demographics and more) and public parcel records (owner, values, last sale, boundary) in the states that publish them. Every value comes with its source, license and confidence.
Typed, zero dependencies, ESM + CommonJS, built on fetch: works in Node 18+, Bun, Deno and edge runtimes
(Cloudflare Workers, Vercel Edge).
Quickstart
npm i isopleth
export ISOPLETH_API_KEY=isp_live_... # free key: https://isopleth.dev/signup/ (ISOPLETH_KEY also works)import { Isopleth } from "isopleth";
const iso = new Isopleth();
console.log((await iso.fetch("1600 Pennsylvania Ave NW, Washington, DC", { preset: "flood_risk" })).fields);What's in it
| Method | API | Cost |
| --- | --- | --- |
| fetch(location, { fields, preset }) | POST /v1/fetch | 1 lookup per started block of 50 fields |
| fetchBatch(locations, { ... }) | POST /v1/fetch/batch | 1 lookup per location per 50 fields |
| geocode(address) | POST /v1/geocode | Free (0 lookups) |
| enrich(location \| { parcel_id } \| { apn, state }) | POST /v1/enrich | 5 lookups per matched parcel |
| search({ state, acres_min, ... }) | POST /v1/search | 25 lookups per page with results |
| searchIter(...) / searchPages(...) | paginates next_cursor | per page, as above |
| coverage(state?) | GET /v1/parcels/coverage | free |
| fields(), searchFields(q), presets() | GET /v1/meta/fields | free |
| usage() | GET /v1/usage | free |
A location is [lat, lng], { lat, lng } or a US street address string. Request parameters use the API's own
names (acres_min, include_geometry...), so the API docs apply as written.
await iso.fetch([30.2672, -97.7431], { fields: ["elevation", "nfhl_flood_zone"] });
await iso.fetchBatch([[35.1, -101.9], "500 E 11th St, Austin, TX"], { preset: "terrain" });
const parcel = await iso.enrich([32.7767, -96.797]);
for await (const p of iso.searchIter({ state: "TX", county: "Travis", acres_min: 40, limit: 100 }, { maxPages: 3 })) {
console.log(p.parcel_id, p.fields.owner, p.fields.gisacre);
}Errors, retries and idempotency
import { QuotaExhaustedError, RateLimitError } from "isopleth";
try {
await iso.search({ state: "TX", acres_min: 1000 });
} catch (e) {
if (e instanceof QuotaExhaustedError) console.log(e.needed, e.remaining); // 402
else if (e instanceof RateLimitError) console.log(e.retryAfter); // 429 (seconds)
else throw e;
}Every error has code, message, status and requestId. Rate limits (429), busy/upstream errors
(502/503/504) are retried up to maxRetries: 2 times, honouring Retry-After (up to maxRetryDelayMs: 60000)
with jittered exponential backoff otherwise; DailyCapReachedError is never retried. fetchBatch, enrich
and search send an Idempotency-Key on every call (pass your own with { idempotencyKey }), so a retry is
never charged twice, and network failures are retried only for those calls and GETs.
Options: new Isopleth({ apiKey, baseURL, timeoutMs: 120000, maxRetries: 2, fetch }). The key defaults to
ISOPLETH_API_KEY (in Workers pass it explicitly: new Isopleth({ apiKey: env.ISOPLETH_API_KEY })) and is
kept in a private field. Don't ship a key to browsers; call the API from your server.
Agents
The same tools as the hosted MCP server (https://api.isopleth.dev/mcp).
Vercel AI SDK (npm i ai):
import { generateText } from "ai";
import { isoplethTools, INSTRUCTIONS } from "isopleth/ai";
const { text } = await generateText({
model, system: INSTRUCTIONS, tools: isoplethTools(), maxSteps: 5, // or stopWhen: stepCountIs(5) on AI SDK 5+
prompt: "Which of these Texas parcels are outside the 100-year floodplain? ...",
});OpenAI / Anthropic / anything else (isopleth/tools):
import { Isopleth } from "isopleth";
import { anthropicTools, openaiTools, openaiResponsesTools, callTool, INSTRUCTIONS } from "isopleth/tools";
const iso = new Isopleth();
// pass anthropicTools() / openaiTools() to the model, then for each tool call:
const result = await callTool(iso, call.name, call.arguments); // object or the model's JSON stringcallTool returns API errors as { error: {...} } so the model can react (pass { raiseErrors: true } to throw).
Pass names: [...] to any helper for a subset of tools.
License
MIT © Luxitag LLC. Data returned by the API carries its own per-source license and attribution.
