Your first API call in minutes

What you'll build

The signup → key → install → first call journey is four steps. Steps 1–3 are pure deterministic physics; step 4 is an optional, clearly-separated AI layer on top of the same engine.

Every call is authenticated with a Bearer key you create in your dashboard. The base URL is https://api.geog.ai/v1.

Three access levels

Every geog.ai computation runs through the same deterministic capability layer — you choose how much abstraction you want on top of it:

1. Raw endpoints

Direct calls to individual endpoints (/v1/context, /v1/simulate/flood, /v1/terrain/profile, …). Maximum control; you handle orchestration. This quickstart uses this level.

2. Capability API

Discover registered capabilities at GET /v1/capabilities (public), then run one with explicit inputs:

POST /v1/capabilities/terrain_profile/execute
{"inputs": {"start": {"lat": 31.9, "lon": -99.9}, "end": {"lat": 32.0, "lon": -99.8}}}

Or compose multiple steps into a serializable, auditable SpatialAnalysisPlan via POST /v1/plans and execute it deterministically. Every result carries a validation record, dataset provenance, and a trust level. SDKs: client.capabilities.execute(...) in both Python and TypeScript.

3. Natural-language API (AI Spatial Analyst)

Ask in plain language; an LLM planner translates your question into a plan constrained to registered capabilities, which is then validated (schema → capabilities → inputs → cost) before anything runs. The LLM never invents spatial math and no LLM-generated code executes.

POST /v1/analyze
{"query": "What's the elevation profile between these two points?",
 "execution": "plan"}   // "plan" = return validated plan only; "auto" = validate then execute

SDKs: client.analyze("...", execution="auto") / client.analyze("...", { execution: "auto" }). LLM token cost is metered against your account and reported in planner.token_cost_units.

Agents and MCP-compatible tools (Claude, Cursor, etc.) can also connect directly to the MCP server at POST /v1/mcp — see the MCP connection guide.

Troubleshooting

Hit a snag on your first run? Here are the four issues developers report most often, the exact error envelope you'll see, and how to fix each one. Every error response uses the same shape — an ok: false envelope with a machine-readable error.code, a human-readable error.message, and a request_id you can quote when emailing support.

401 Unauthorized — INVALID_API_KEY

The API key is missing, malformed, expired, or revoked. The most common cause is forgetting the Bearer prefix or shell-quoting issues that strip the variable.

Fix checklist:

• Confirm the header is Authorization: Bearer <prefix>.<secret> — the literal word Bearer, a single space, then the whole dotted key string.
• Echo the variable before sending: echo "$GEOG_API_KEY". An empty value usually means the env var was set in a different shell session — re-source ~/.zshrc or restart your terminal.
• Send the entire key including the dot. Sending only the public prefix (the part before the .) returns INVALID_API_KEY — the secret half is what authenticates.
• Rotated or revoked keys stop working instantly. If you regenerated the key at geog.ai/account, copy the new one — the old value will keep returning 401.

422 Validation error — INVALID_PARAMS

The request was authenticated but the body or query string failed validation. error.message always names the offending field.

Fix checklist:

• /context takes device_id, not coordinates. A raw lat/lon lookup belongs to GET /v1/nearby — pointing coordinates at /context returns a validation or 404 device_not_found error.
• vertical_id must match V\d\d (e.g. V01) on POST /v1/simulate/*, and the vertical must be entitled on your key.
• Send numbers, not strings. JSON "50.0" (with quotes) fails where a number is expected — use 50.0.
• /nearby radius_m is capped at 10 000 m in Phase 1; larger values return radius_exceeds_phase1_cap.
• An unknown simulation engine returns 404 with UNSUPPORTED_CAPABILITY and lists the available engines.

Job never reaches succeeded

Your POST /v1/simulate/flood returned 202 with a job_id, but polling never flips to succeeded. Poll the live status path — GET /v1/simulate/jobs/{job_id} — and read the status field directly.

Fix checklist:

• Poll /v1/simulate/jobs/{job_id}, not /v1/jobs/{id}. The generic /v1/jobs/{id} path is documented-only and is not served by the live API — polling it returns 404 forever. The SDK wait_for_job / waitForJob helpers already target the correct path.
• Terminal statuses are succeeded, failed, and expired — not "complete". Read the result envelope from GET /v1/simulate/jobs/{job_id}/result only after status == "succeeded"; that route returns 404 (with retryable: true) until the job succeeds.
• A 404 job_not_found on the status route usually means you're authenticating as a different tenant than the one that submitted the job — jobs are scoped to the submitting tenant to prevent cross-tenant reads.
• Cancelled jobs land in expired via DELETE /v1/simulate/jobs/{job_id}. If your poll loop sees expired, someone cancelled the job.
• Optional callbacks: supply callback_url (HTTPS) on the submit to receive an HMAC-signed result on terminal status instead of polling.

Low confidence — confidence < 0.6

This isn't an error — the request succeeded with HTTP 200 — but the envelope's top-level confidence signals that key spatial layers were unavailable for this location. Treat the result as directional, not actionable, and don't trigger automated alerts on it. The provenance.degraded list tells you exactly which layers were missing.

What the score means:

• ≥ 0.85 — site-calibrated with full layer coverage, safe for automated decisions and alerting.
• 0.60 – 0.85 — uncalibrated but well-supported; surface to humans, gate auto-actions.
• < 0.60 — several layers degraded; directional only. Show a "low confidence" badge and require manual review.

How to raise confidence:

• Register and calibrate the site. A location with no calibration (calibration_age: null, as above) is the single biggest driver of a low score — most sites move from ~0.35 to 0.9+ after a single calibration pass.
• Read provenance.degraded. Each entry is a layer the API couldn't resolve for this location (e.g. terrain, atmospheric). Supplying or enabling those datasets for the site removes them from the list and lifts confidence.
• Check coverage: on the edge of a supported region parts of the SpatialState fall back to coarser data and confidence drops. Set a floor with the min_confidence query param to have /context return 422 instead of a weak envelope.
• In code, gate on confidence explicitly — e.g. if ctx["confidence"] < 0.6: queue_for_review() — rather than treating every 200 OK as actionable.

Next steps

Now that you've made your first calls, here's where to go next: