burnban
Current fire restrictions and campfire rules for any point in Arizona, on any date, with the official source and the time it was last checked.
Disclaimer. Informational only. Verify with the land manager before lighting any fire. Not legal advice.
What this is
Buyers are AI agents and the people who build them: trip planners, outdoor assistants, camping tools. Send a latitude and longitude, get back every jurisdiction that contains the point, its restriction stage and rules, a computed effective block with the most restrictive rule per field, and a link to the signed source for each answer. When burnban does not know, it says unknown rather than guessing.
Coverage
Arizona only. Coverage is per jurisdiction and grows over time. Each jurisdiction reports a coverage_level of full, partial or planned, plus its last_verified time. A point in a planned area returns unknown with the nearest official sources. The live list is free: GET https://api.burnban.app/v1/coverage.
Endpoints
| Route | Cost | Purpose |
|---|---|---|
GET /v1/lookup?lat=&lon=&date= | $0.01 | Restrictions for a point. date is optional, formatted YYYY-MM-DD, and defaults to today in America/Phoenix. |
GET /v1/coverage | free | Jurisdictions, coverage level, last verified time. |
GET /v1/health | free | Build id, database reachability, last successful ingest time. |
POST /mcp | tool dependent | MCP server over Streamable HTTP. |
GET /.well-known/x402.json | free | Machine-readable payment terms. |
Invalid input returns 400 with {"error": {"code": "invalid_request", "message": "..."}} and is never charged. A failed lookup is not charged either.
Price and how to pay
Each lookup costs $0.01, paid in USDC with x402 version 2, scheme exact, on Base mainnet (eip155:8453). Pay to not configured yet. No account and no API key.
- Request
/v1/lookupwithout payment. The server answers402with a base64 JSONPAYMENT-REQUIREDheader listing the accepted payment. - Sign the payment and retry the same request with a
PAYMENT-SIGNATUREheader. - On success the response is
200and carries a base64 JSONPAYMENT-RESPONSEheader with the settlement transaction.
With @x402/fetch this is handled for you:
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
const pay = wrapFetchWithPaymentFromConfig(fetch, {
schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(privateKeyToAccount(KEY)) }],
});
const res = await pay("https://api.burnban.app/v1/lookup?lat=35.19&lon=-111.63");
console.log(await res.json());
Payment terms in machine-readable form: /.well-known/x402.json. Responses to paid routes are sent with Cache-Control: no-store.
MCP server
Endpoint: https://api.burnban.app/mcp, Streamable HTTP. Tools:
get_fire_restrictions, paid, $0.01. Argumentslat,lon, optionaldate. Payment follows the x402 MCP transport: an unpaid call returns a tool result withisError: trueand the payment requirements instructuredContent. Retry with the signed payment in_meta["x402/payment"]. The settlement comes back in_meta["x402/payment-response"].get_coverage, free. No arguments.
Response fields
Every field of the /v1/lookup response, and of the get_fire_restrictions tool result, which is the same JSON.
| Field | Meaning |
|---|---|
query | The request as interpreted. |
query.lat | Latitude in decimal degrees (WGS84). |
query.lon | Longitude in decimal degrees (WGS84). |
query.date | Requested date (YYYY-MM-DD, Arizona time); today in America/Phoenix when omitted. |
query.date_rule | How the date became an instant: today = the request time; past = 12:00 Arizona time that day; future = rules in force now plus published orders starting by 12:00 that day. |
query.evaluated_at | Instant the rules were evaluated at, ISO 8601 with the Arizona offset (-07:00). |
jurisdictions | Every jurisdiction whose boundary contains the point, national forests first, then counties, then cities. |
jurisdictions[].id | Stable jurisdiction id, for example usfs-coconino. |
jurisdictions[].type | national_forest, county or municipality. |
jurisdictions[].name | Official name. |
jurisdictions[].agency | Agency that issues the orders. |
jurisdictions[].coverage_level | full, partial or planned. Planned jurisdictions always answer unknown. |
jurisdictions[].ranger_district | Ranger district containing the point, for national forests; its orders are folded into this entry. |
jurisdictions[].ranger_district.id | Ranger district id. |
jurisdictions[].ranger_district.name | Ranger district name. |
jurisdictions[].mirrors | Id of the jurisdiction whose orders this one copies because it has no source of its own, or null. |
jurisdictions[].status | restrictions (at least one rule is restricted), no_restrictions (recently checked and no order restricts anything), or unknown. |
jurisdictions[].restriction_stage | Fire danger stage of the stage order in force (0 to 3). 0 means no stage order is in force, though standing year-round orders may still restrict fires. Null when unknown. |
jurisdictions[].rules | One value per rule field, the most restrictive across this jurisdiction's orders in force. |
jurisdictions[].rules.{field} | Rule value from the enum for that field, or unknown. allowed means no order we track restricts it; standing laws still apply. |
jurisdictions[].conditions | Plain-language limits and exceptions from the order that supplied each rule, where the order states any. |
jurisdictions[].conditions.{field} | Conditions for that rule field. |
jurisdictions[].order_number | Number of the main order in force (the stage order if any), or null. |
jurisdictions[].effective_since | Start of the main order, ISO 8601 with offset. |
jurisdictions[].effective_until | Scheduled end of the main order, ISO 8601 with offset, or null when open ended. |
jurisdictions[].source_url | Official document for the main order, or the agency alerts page when no order is in force. |
jurisdictions[].last_verified | Latest successful check of this jurisdiction's sources at or before the freshness instant (UTC). |
jurisdictions[].confidence | high, medium or low. Lowered one level when last_verified is over 72 hours old, capped at low for mirrored jurisdictions and at medium for future dates. Null when unknown. |
jurisdictions[].orders | Every order in force for this jurisdiction at the evaluation instant. |
jurisdictions[].orders[].jurisdiction_id | Jurisdiction that issued the order (a ranger district for district orders). |
jurisdictions[].orders[].order_number | Order number as printed, or null when the agency did not number it. |
jurisdictions[].orders[].title | Order title. |
jurisdictions[].orders[].stage | stage_0 to stage_3, year_round or other. |
jurisdictions[].orders[].effective_since | Order start, ISO 8601 with offset. |
jurisdictions[].orders[].effective_until | Scheduled order end, ISO 8601 with offset, or null. |
jurisdictions[].orders[].area | Area the order covers, as the order describes it. |
jurisdictions[].orders[].source_url | Official order document. |
jurisdictions[].orders[].confidence | Confidence in the extracted order. |
jurisdictions[].notes | Caveats for this jurisdiction: boundary meaning, mirroring, staleness, district order areas. |
effective | Most restrictive answer across all jurisdictions that are not unknown. |
effective.restriction_stage | Highest restriction_stage among those jurisdictions, or null. |
effective.rules | One entry per rule field. |
effective.rules.{field} | Winning value for that rule field. |
effective.rules.{field}.value | Most restrictive known value; unknown never wins over a known value. |
effective.rules.{field}.from | Id of the jurisdiction that supplied the value, or null when unknown. |
effective.rules.{field}.order_number | Order that supplied the value, or null. |
effective.rules.{field}.conditions | Conditions attached to the winning value, or null. |
effective.confidence | Lowest confidence among the jurisdictions that supplied a value; capped at medium when any jurisdiction is unknown or the point is near a boundary. Null when nothing is known. |
unknown | Ids of jurisdictions whose answer is unknown (planned coverage, stale data or never checked). |
nearest_sources | Official pages to check by hand when something is unknown. |
nearest_sources[].jurisdiction_id | Jurisdiction the page belongs to, or null for a statewide page. |
nearest_sources[].name | Page owner. |
nearest_sources[].url | Page URL. |
near_boundary | True when the point is within about 12 m of a boundary in the simplified boundary data, so membership may be wrong. |
date_note | Explains future-date handling and any order that starts or ends on the requested date; null otherwise. |
notes | Caveats for the whole answer. |
disclaimer | Always present. Informational only; not legal advice. |
generated_at | When this response was generated (UTC). |
Coverage fields
Every field of the /v1/coverage response and the get_coverage tool result.
| Field | Meaning |
|---|---|
jurisdictions | Every jurisdiction burnban knows about. |
jurisdictions[].id | Stable jurisdiction id. |
jurisdictions[].type | national_forest, ranger_district, county or municipality. |
jurisdictions[].name | Official name. |
jurisdictions[].agency | Agency that issues the orders. |
jurisdictions[].parent_id | Parent jurisdiction (the forest, for a ranger district), or null. |
jurisdictions[].mirrors | Id of the jurisdiction whose orders this one copies, or null. |
jurisdictions[].coverage_level | full, partial or planned. |
jurisdictions[].source_count | Enabled sources owned by this jurisdiction. |
jurisdictions[].verified_via | Jurisdiction whose sources verify this one (parent forest or mirrored jurisdiction), or null. |
jurisdictions[].last_verified | Latest successful source check (UTC), or null. |
jurisdictions[].freshness | fresh (72 hours or less), stale (over 72 hours), expired (over 14 days, lookups answer unknown) or never. |
jurisdictions[].note | Caveat for this jurisdiction, or null. |
disclaimer | Always present. Informational only; not legal advice. |
generated_at | When this response was generated (UTC). |
Rule values
Each key of rules takes one of these values. Order is least to most restrictive, and effective uses that order. unknown never wins over a known value.
| Rule field | Values, least to most restrictive |
|---|---|
campfires | allowed developed_sites_only prohibited unknown |
charcoal | allowed developed_sites_only prohibited unknown |
gas_stoves | allowed allowed_with_shutoff_valve prohibited unknown |
smoking | allowed enclosed_vehicle_or_building_or_developed_site_only enclosed_vehicle_or_building_only prohibited unknown |
fireworks | allowed prohibited unknown |
explosives | allowed prohibited unknown |
target_shooting | allowed prohibited unknown |
area | open closed unknown |
Freshness and confidence
Official sources are checked at least daily, and every few hours in fire season. A response is only as fresh as its last_verified. Confidence drops one level when the last verification is older than 72 hours, and the answer becomes unknown after 14 days. Every first-season order is reviewed by a person before it is published.
Contact
Questions, corrections and source problems: https://api.burnban.app/docs.