geog.ai API Reference

Returns the full SpatialState for a registered device — terrain, jurisdiction, wind vector, nearby entities, atmospheric stability class, and asset proximity. Enrichment runs at ingest time; this call returns the pre-computed state with a confidence-weighted freshness score.

Resolves SpatialState for up to 500 devices in a single request. Responses are returned as an array in the same order as the input IDs. Partial failures are represented with null result entries and an error sub-object.

Returns all registered entities within a given radius of a coordinate, optionally filtered by type. Results are ordered by distance and include the SpatialState for each entity.

Returns all registered entities whose registered location falls within a given GeoJSON polygon. Used for zone-based queries — "which sensors are inside this permit boundary?", "which personnel are inside this exclusion zone?"

Returns all applicable regulatory jurisdictions and permit obligations for a given coordinate — air quality authority, watershed governance, noise ordinance, and any cross-boundary relationships. Jurisdiction data is cached aggressively; jurisdictions change rarely. If you pass a device_id, jurisdiction is returned as part of the SpatialState (no separate charge).

Runs an atmospheric dispersion model for a point or area source. Tier 1 uses Gaussian plume (fast screening, <8s). Tier 2 uses AERMOD-style regulatory-grade modeling (15–60s). Tier 3 uses Lagrangian particle tracking for non-steady-state scenarios (minutes). Returns concentration isopleths (polygons), predicted readings at registered sensor locations, and affected zone classifications.

Opens a Server-Sent Events (SSE) stream that delivers a running plume simulation in real time. Shares the source, wind, stability_class, duration_min, species, and output_receptors shape with the async /simulate/plume endpoint and adds two streaming-specific options. The server responds 200 OK with Content-Type: text/event-stream and emits four named events — tick, concentration, alert, and end — until the simulation completes or the client disconnects. Every event carries a stable id: field; clients that drop the connection should reconnect with Last-Event-ID to resume from the last event seen. The official SDKs (streamPlume in TypeScript, stream_plume in Python) implement this reconnect-with-backoff behaviour automatically. Billed once on end.

To resume a dropped connection, replay the same request with the Last-Event-ID header set to the last id: value the client received (e.g. -H "Last-Event-ID: 47"). The server will resume the stream from the next event.

Runs DEM-based watershed delineation, SCS Curve Number rainfall-runoff modeling, kinematic wave channel routing, and 2D inundation mapping. Returns flood extent polygons at multiple return intervals, time-to-crest forecasts, and a list of sensors predicted to be inundated and at what time.

Runs the ITM/Longley-Rice terrain propagation model for a single RF node. Returns a coverage probability polygon at the specified RSSI threshold, plus a raster heatmap and link budget summary. For multi-node mesh analysis, use POST /rf/mesh/viability.

Runs ISO 9613-2 octave-band outdoor sound propagation from a point or line source. Accounts for geometric spreading, atmospheric absorption, ground effect, barrier insertion loss, and vegetation attenuation. Returns noise contour polygons (isodB lines) and exceedance flags at registered receptor locations (property boundaries, sensitive receivers).

Models heat propagation from industrial sources, fire events, or HVAC failures. Returns time-to-temperature-threshold at monitored locations, hot zone polygons for personnel exclusion, and cooling equipment failure cascade prediction. Used for cold chain breach analysis, server room modeling, and wildfire thermal exposure.

Models wildfire spread using terrain, fuel model, and weather conditions. Returns fire perimeter polygons at specified time intervals, rate-of-spread vectors, and smoke plume trajectory (linked to /simulate/plume for full smoke transport). Used for V50 (Wildfire) vertical, prescribed burn planning, and asset protection zone analysis.

Returns the coverage probability polygon for a registered RF node at a given RSSI threshold. Cached per node until terrain or node configuration changes. Faster than /simulate/rf_coverage for registered nodes — uses pre-computed ITM results.

Returns the link budget between two registered nodes — predicted RSSI, fade margin, Fresnel zone clearance, and obstruction analysis. Uses ITM for terrain analysis. Returns a pass/fail recommendation for the link given the specified reliability threshold.

Identifies coverage gaps within a defined area given existing node topology. Returns a GeoJSON heatmap of gap severity and a list of H3 cells with insufficient coverage. Used as the input analysis step before /rf/optimize/placement.

Computes the full link budget matrix for a mesh network — every node-to-node pair, with failure probability based on calibrated path loss models. Returns a connectivity matrix, mesh reliability score, single-points-of-failure, and failure scenario analysis. Async job; typical completion 15–40 seconds for networks up to 200 nodes.

Given existing mesh topology, terrain, and coverage requirements, returns the top-N candidate locations that maximize marginal coverage gain. Consultants charge $50K+ for site surveys that produce this output manually. The optimizer runs terrain-aware ITM models against candidate grid points and ranks by marginal coverage gain per dollar of deployment cost.

Generalizes RF placement to any monitoring objective — air quality sensor spacing (accounting for plume physics), flood gauge placement (watershed coverage), or acoustic monitor placement (source coverage). Returns ranked candidate locations with objective-specific marginal gain scores.

Recommends sensor placement for a given ZOOID vertical — accounts for the vertical's specific measurement physics, regulatory requirements, and deployment constraints. For V01 (gas monitoring), incorporates prevailing wind roses and upwind source locations. For V02 (water quality), uses watershed topology and flow network.

Returns the current monitoring coverage fraction for a given area and sensor type. Coverage is defined by the spatial footprint of registered sensors given their detection physics — not just proximity. A gas sensor on a hilltop covers a different downwind area than one in a valley.

Identifies monitoring gaps within a defined area — H3 cells where no sensor provides adequate coverage given detection physics. Returns a GeoJSON gap heatmap and summary statistics. Companion to /coverage; where /coverage returns a fraction, /gaps returns the geographic specifics of what is not covered.

Returns the stored trajectory (sequence of positions with timestamps and uncertainty bounds) for a registered moving entity over a specified time window. Uses MobilityDB temporal spatial joins for efficient window queries.

Predicts the future trajectory of a moving entity given current position, velocity, and historical movement patterns. Returns a predicted path with expanding uncertainty bounds. Used for drone flight path prediction, fleet routing optimization, and personnel zone arrival forecasting.

Returns all nodes in the sensor graph that are "downstream" of a source event — entities likely to be affected if the source produces an event. Edge weights reflect propagation physics (plume transport, fluid flow, RF signal paths). Returns nodes ordered by predicted arrival time and estimated impact magnitude.

Returns optimal evacuation routes from specified locations to safe zones, routing around active hazard polygons (from live plume, fire, or flood simulations). Uses pgRouting on the facility graph with real-time hazard avoidance. Used by V15 (Personnel Safety) and V17 (Emergency Response) verticals.

Returns all sensors and assets upstream of a given node in the sensor graph — entities that could causally affect the target node. Used for root cause analysis: "which upwind sources could have caused this reading?", "which upstream watershed sensors are relevant to this gauge?"

Returns the current calibration state for a site-specific propagation model — parameter values, last update timestamp, accuracy metrics (predicted vs observed), and calibration history. Used for regulatory audit trails and model performance monitoring.

Returns the current status of an async job. When status is complete, the full result is included in the response. Jobs expire 48 hours after completion.

Registers an HTTPS callback URL on your account. Once registered, every async job your account creates (/simulate/*, /rf/mesh/viability, /rf/optimize/placement, /optimize/*) will POST its full result envelope to this URL when it transitions to complete or failed. Per-job overrides can still be supplied via the webhook_url field on the job request body. Returns the registered webhook record including the secret used to sign deliveries — store it securely; it is shown only once.

Delivery payload

Each delivery is a POST with Content-Type: application/json containing the same response envelope you would receive from GET /jobs/{job_id} when the job is complete. The following headers are always set:

Verifying the signature

To prevent forged callbacks, recompute the HMAC on your side and compare it with X-Geog-Signature using a constant-time comparison. Reject deliveries where the timestamp is more than 5 minutes old to mitigate replay attacks. To exercise this code path end-to-end before any real job runs, jump to Recipe: verify your webhook in 30 seconds — it stitches registration, POST /webhooks/{id}/test, and this verifier into a single copy-pasteable example.

Accepting replays of older deliveries

Because POST /webhooks/{id}/deliveries/{delivery_id}/replay reuses the original signature timestamp, a strict |now - t| > 300 check will reject any replay of a delivery older than 5 minutes. A replay-safe verifier needs all three delivery headers: X-Geog-Webhook-Id to look up the correct endpoint secret (an account can have up to 10 registered webhooks, each with its own secret), X-Geog-Signature to recompute the HMAC, and X-Geog-Delivery to identify which delivery this is. Always recompute the HMAC, and skip the freshness check only when X-Geog-Delivery matches a delivery your server has previously seen and verified — that's the signal a replay is legitimate rather than a forged old payload. Dedupe on X-Geog-Delivery so the same event is not processed twice.

Every delivery, regardless of event type, uses the same JSON envelope so receivers can dispatch on a single field:

Dispatch on event (or the X-Geog-Event header — they always match) and parse result using the schema for that type:

job.complete body

job.failed body

calibration.updated body

webhook.disabled body

Fired on the last retry attempt before the platform pauses the webhook. The result block is byte-for-byte the same shape as GET /webhooks/{id}/health at as_of, so a receiver that already parses health-poll responses can reuse the same parser without a second API call to find out which counters tripped the auto-disable.

Generates a synthetic delivery for the registered webhook and POSTs it to the URL exactly as a real event would be sent — same envelope shape, same X-Geog-Signature HMAC, same retry rules. Designed for day-one verification of a brand-new receiver before any real job has run: confirm that the URL is reachable, your TLS certificate is valid, and your signature-verification code accepts the payload. Returns the resulting WebhookDelivery with test: true, and adds an X-Geog-Test: true header to the outbound POST so your handler can short-circuit production side-effects (alerts paged out, downstream writes, billing) for synthetic traffic.

The endpoint accepts an optional event in the body to choose which event type to simulate (job.complete by default). Test deliveries appear in GET /webhooks/{id}/deliveries alongside real ones (filter on test=true), are subject to the same retry schedule and auto-disable rules, and count against the per-webhook rate limit. They are throttled to 60 test deliveries per webhook per hour.

The three pieces above (register, POST /webhooks/{id}/test, and the signature verifier) are usually wired up together on day one. The snippets below stitch them into a single closed loop so you can prove your receiver works end-to-end before any real simulation job runs — and without waiting for one to fire.

How to use: run the receiver on a public HTTPS URL (use ngrok or similar in development), then run the registration script with that URL. The script registers the webhook, captures the signing secret, fires a synthetic job.complete via POST /webhooks/{id}/test, and your receiver logs signature OK within a second. If the signature fails, the receiver returns 400 and the delivery shows up as failed in GET /webhooks/{id}/deliveries — walk through Recipe: debug a failed delivery and replay it to fix the receiver and re-send without waiting for the next real job.

Python — register, send test, verify (Flask)

Node — register, send test, verify (Express)

Go — register, send test, verify (net/http)

Ruby — register, send test, verify (Sinatra)

Returns a paginated list of delivery attempts for the given webhook, newest first. Mirrors the delivery log shown on the dashboard and is intended for debugging receiver-side bugs without waiting for the next real job. Deliveries are retained for 30 days; older records return an empty page rather than an error. Combine with the status=failed filter to find candidates for replay after fixing your handler.

Returns the same filtered, paginated rows as GET /webhooks/{id}/deliveries, serialised as a CSV stream rather than a JSON envelope. Intended for one-off ops investigations: pipe the response into a file, hand it to a teammate, or paste it into a spreadsheet without scripting against the JSON endpoint.

The response uses Content-Type: text/csv; charset=utf-8 and is sent with Content-Disposition: attachment; filename="deliveries-<webhook_id>.csv" so browsers and curl -OJ save it directly to disk.

All filters behave identically to the JSON endpoint and compose with AND semantics — for example, ?status=failed&test=false&created_after=2026-04-21T02:00:00Z&created_before=2026-04-21T03:00:00Z exports only failed real (non-test) deliveries queued during that one-hour window, the slice you typically want to attach to an outage post-mortem.

Body is RFC 4180 CSV with a fixed header row, newest-first, identical to the JSON ordering. Columns, in order:

Encoding rules: RFC 4180 — fields containing commas, quotes, or newlines are wrapped in double quotes and embedded double quotes are doubled (" → ""). JSON null values are emitted as empty fields, not the literal string null. Line terminator is \r\n. Character set is UTF-8.

CSV bodies cannot carry a JSON meta object, so the next-page cursor is exposed in the X-Next-Cursor response header. To export every matching delivery, follow the cursor and concatenate the body of each page (skipping the header row on pages 2+):

Errors are returned as the standard JSON error envelope (not CSV) so existing client error handling keeps working.

Re-queues a previously attempted delivery for immediate re-send to the webhook's currently registered URL. Useful after fixing a receiver-side bug — there is no need to wait for the next real job. Returns a 202 Accepted with the updated WebhookDelivery reflecting its new pending state. The replay attempt counts toward the webhook's retry budget and increments attempt_count.

Returns the same rolling-window failure-rate counters that drive the platform's auto-disable rule, plus the current active / disabled_reason state. Use this endpoint to detect — programmatically, without waiting for the account owner's email — when a webhook has been auto-disabled after sustained delivery failures (≥50% failed deliveries in the last hour), or is trending toward it.

The reference for GET /webhooks/{id}/health and the webhook.disabled event tell you what the platform exposes; this recipe is the copy-pasteable monitoring loop you actually deploy. It pairs two complementary patterns so you find out about a sick receiver the moment the platform does, regardless of whether the receiver itself is still reachable:

(A) The polling guard — a small job that runs in your monitoring service (not on the receiver) and pulls GET /webhooks/{id}/health once a minute. It pages the receiver's owner as soon as status flips to degraded (failure rate ≥ 25%, still active) and opens a hard incident the instant status == "disabled" with disabled_reason == "auto_failure_rate" appears. disabled_reason == "manual" is treated as benign — someone turned it off on purpose.

(B) The inbound webhook.disabled handler — a separately-deployed receiver (different host, different on-call rotation) subscribed to the webhook.disabled event. The platform fires this event on the final attempt before pausing the original webhook, so a receiver that is failing for its own deploy reasons cannot also swallow the notification that it is failing. Pattern (A) is the source of truth (it works even if pattern (B) misses a delivery); pattern (B) closes the gap between two polls and is what wakes you up at 3am.

Once Recipe: verify your webhook in 30 seconds reports signature OK, the next thing you will hit in production is a failed delivery — a missing field, a 500 from your handler, a deploy that broke the route. This recipe walks through that full debug loop end-to-end using GET /webhooks/{id}/deliveries and POST /webhooks/{id}/deliveries/{delivery_id}/replay, so you can fix and re-send a real failure without waiting for the next simulation job to fire.

The worked example: the receiver from the verify recipe is shipped with a one-line bug — it calls result["bbox"], but job.complete payloads use bbox_4326. The first synthetic delivery returns 500 Internal Server Error, the platform retries with backoff and the delivery moves to status: failed. We list it, fix the field name, redeploy, replay the same whd_, and watch it land as success.

Python — the buggy receiver, the fix, then debug + replay

Node — the buggy receiver, the fix, then debug + replay

Once you've worked through Recipe: debug a failed delivery and replay it, the very next failure mode is a silent one: a replay of a delivery you already processed. The signature is valid, the payload is identical, and your handler will happily run end-to-end again — archiving the same plume result twice, double-charging an internal counter, or sending the same notification twice. The fix is a one-line dedupe at the top of the handler keyed on X-Geog-Delivery, the unique-per-delivery ID that POST /webhooks/{id}/deliveries/{delivery_id}/replay deliberately keeps stable across replays.

The pattern: claim the delivery ID atomically before doing any side-effecting work. If the claim succeeds, this is the first time you've seen this delivery — do the work. If the claim fails, this is a replay (or a retry from the platform's own backoff schedule) — ack with 200 and skip. The two snippets below show the claim against Postgres (INSERT ... ON CONFLICT DO NOTHING) and against Redis (SET NX); both are atomic primitives, so concurrent replays of the same delivery cannot both win the claim. Pick whichever store your service already has — the dedupe table only needs the delivery ID and a timestamp.

Python — Flask + Postgres ON CONFLICT DO NOTHING

Node — Express + Redis SET NX

Returns every webhook registered on the calling account, ordered by created_at descending. Use this to audit which endpoints are receiving deliveries, detect stale URLs, or build a management UI.

Returns the current configuration of one webhook. The signing secret is not returned — it is only available on the original POST /webhooks response. To rotate it, delete and re-register.

Partially updates a webhook. Send only the fields you want to change. Common uses: toggling active to pause/resume deliveries, re-pointing url after a backend migration, or narrowing the subscribed events.

Permanently removes a webhook. Deliveries already in flight may still arrive briefly, but no new deliveries will be queued. Use this to revoke a leaked endpoint or to rotate the signing secret (delete, then POST /webhooks to register a fresh one and capture the new secret).