Proximity, Ask & Runs

Three conveniences on top of the core endpoints. Each one goes through the same metering as the call underneath, so nothing here has a separate price.

Proximity: what is nearby

POST /v1/proximity with lat+lng or address returns the nearest mapped feature of each type you ask for, sorted nearest first, with the distance in meters, kilometers and miles and the feature's name and attributes where the source publishes them. Pick features (types), categories, or both; with neither you get a default set of 14 common types. Add radius_m to flag which features fall inside a distance.

curl https://api.isopleth.dev/v1/proximity -H "Authorization: Bearer $ISOPLETH_KEY" -H "Content-Type: application/json" -d '{"lat": 35.2226, "lng": -97.4395, "features": ["substation", "transmission_line"], "categories": ["places"], "radius_m": 5000}'

Response (trimmed to one feature):

{
  "lat": 35.2226,
  "lng": -97.4395,
  "features": [
    {
      "type": "substation",
      "label": "Substation",
      "category": "power",
      "status": "ok",
      "distance_m": 1840.2,
      "distance_km": 1.84,
      "distance_mi": 1.143,
      "within_radius": true,
      "source": "EIA_POWER",
      "attributes": {
        "nearest_substation_max_voltage_kv": 138
      }
    }
  ],
  "radius_m": 5000,
  "within_radius_count": 1,
  "lookups_charged": 1
}

Cost: 1 lookup per call. One call covers up to 50 underlying fields (about 20 types); if a request needs more, radius counts are left out first (counts_omitted), and beyond that it returns 400 too_many_feature_types, so split the types across calls, for example one per category. Nothing is charged when no data comes back. Distances are straight-line to the nearest feature in a public dataset, not a route, a survey or a utility study. GET /v1/proximity/types (free) lists the types.

Ask: plain-English questions

POST /v1/ask takes a question (and optionally a location) and maps it to one of the endpoints: point facts, proximity, parcel enrich, parcel search or geocode. It picks the fields, preset, filters or feature types from the question, runs the call, and returns a short answer, the plan and the full result. Planning is rules plus the field catalog, with no language model, so the same question always gets the same plan.

{
  "question": "How far is the nearest substation from 35.2226, -97.4395?"
}

POST /v1/ask/plan returns the plan alone, free: the endpoint, the exact request body, the estimated lookups, and needs when something is missing (usually a location). Set max_lookups on /v1/ask to refuse any plan estimated above your budget; a refused or incomplete question is free.

Cost: exactly what the planned call costs. Questions it cannot place return question_incomplete with the plan so you can fill the gap.

Async runs

For work too large for one request, POST /v1/runs starts a run and returns at once with its id (HTTP 202). Poll GET /v1/runs/{id} for progress and GET /v1/runs/{id}/results?offset=&limit= for results, which arrive while it runs. DELETE /v1/runs/{id} cancels a running run or deletes a finished one.

• kind: "batch": up to 2,000 locations with the same fields, split into batches of your plan's size.
• kind: "enrich": up to 1,000 parcel items, each one of lat+lng, address, parcel_id or apn+state, with optional point fields.
• kind: "search": a /v1/search body walked page by page, up to max_pages (40 at most).

{
  "kind": "search",
  "search": {
    "state": "NC",
    "county": "Wake",
    "acres_min": 20,
    "limit": 100
  },
  "max_pages": 10,
  "max_lookups": 150
}

Cost: each step is a normal call to /v1/fetch/batch, /v1/enrich or /v1/search, so it is metered, rate-limited and capped exactly as those are. max_lookups stops the run before a step that could take it over budget (status stopped, code budget_reached), and a run also stops if your quota or daily cap runs out. Up to 2 runs can be active per account. Results are held in memory only, never written to disk, and expire 24 hours after the run ends; a service restart also clears them.

In MCP

The MCP server exposes these as proximity, ask, plan_question, start_run and get_run.