Language SDKs

Overview

The quickstart uses raw HTTP (cURL, requests, fetch) so you can see exactly what's on the wire. For day-to-day work, an SDK is faster: one install, a typed client, and you're calling the API.

Language	Package	Install	Status	Source
Python 3.10+	geog-ai	pip install geog-ai	Stable	python/
JavaScript / Node.js 18+	@geog-ai/sdk	npm install @geog-ai/sdk	Stable	typescript/
Go 1.21+	github.com/geog-ai/geog-go	go get github.com/geog-ai/geog-go	Preview	request access

Don't see your language? Every SDK is generated from openapi.yaml. You can produce a client for Ruby, Java, C#, Rust, PHP, Kotlin, Swift, or anything else openapi-generator supports — see Generate your own client below.

Why use an SDK?

The geog.ai HTTP API is intentionally simple — a few headers and JSON in, JSON out. The SDKs give you the same calls, but with the rough edges already smoothed off:

🔑 Auth & headers

Authorization: Bearer …, Content-Type, User-Agent, and X-Idempotency-Key are managed for you.

🧠 Typed responses

Generic JobResponse<TResult>, SpatialState, error envelopes — all typed so your IDE autocompletes payload fields.

⏳ Async-job polling

One waitForJob() / wait_for_job() call replaces dozens of lines of polling, backoff, and timeout logic.

🔁 Resilient streaming

Both SDKs reconnect SSE plume streams with exponential backoff and replay from Last-Event-ID on dropped connections. For request-level retries on regular calls, inject a requests.Session with an HTTPAdapter (Python) or wrap calls in your own retry policy (TypeScript).

📡 SSE streaming

Live plume tracking via streamPlume() / stream_plume() — reconnects with Last-Event-ID on dropped connections.

🛡 Webhook helpers

Register, list, update, test, and replay webhook deliveries (register_webhook(), send_webhook_test(), replay_webhook_delivery()). HMAC verification of X-Geog-Signature stays in your handler — see the 30-second recipe in the API reference.

Hello world in every language

Each SDK below has the same shape: install the package, instantiate a GeogClient with your API key, then call any of the documented endpoints. The minimal snippet under each section makes a real call to GET /nearby — the same endpoint used in step 3 of the quickstart.

You'll need an API key. Email hello@geog.ai for a test key (geog_test_sk_…) — it returns realistic synthetic data and never charges your account. Set it as GEOG_API_KEY in your shell before running any of the snippets below.

PY

Python 3.10+

geog-ai · uses requests

Stable

Install Shell

pip install geog-ai

Hello, geog.ai Python

import os
from geog_ai import GeogClient

geog = GeogClient(api_key=os.environ["GEOG_API_KEY"])
res  = geog.nearby(lat=31.9686, lon=-99.9018, radius_m=500)
print(res["result"]["entities"])  # nearby assets within 500 m
            

Already have a registered device? Pass device_id="…" to geog.context() instead — it returns a fully resolved SpatialState (terrain, meteorology, jurisdiction).

📂 Source & README 🧪 Runnable examples ⬇ PyPI

JS

JavaScript / Node.js 18+ · ESM & CJS

@geog-ai/sdk · uses global fetch

Stable

Install Shell

npm install @geog-ai/sdk
# or pnpm add @geog-ai/sdk
# or yarn add @geog-ai/sdk
            

Hello, geog.ai TypeScript / JavaScript (Node 18+)

import { GeogClient } from "@geog-ai/sdk";

const apiKey = process.env.GEOG_API_KEY;
if (!apiKey) throw new Error("Set GEOG_API_KEY in your environment");

const geog = new GeogClient({ apiKey });
const res  = await geog.nearby({ lat: 31.9686, lon: -99.9018, radius_m: 500 });
console.log(res.result.entities);  // nearby assets within 500 m
            

The same code works in plain JavaScript — just drop the import for a CommonJS require("@geog-ai/sdk"). Already have a registered device? Call geog.context({ device_id: "…" }) for a typed SpatialState (terrain, meteorology, jurisdiction).

TypeScript-first. The package ships .d.ts definitions for every endpoint and the JobResponse<TResult> generic. Plain JavaScript works too — the typings are optional.

📂 Source & README 🧪 Runnable examples ⬇ npm

GO

Go 1.21+

github.com/geog-ai/geog-go · zero non-stdlib deps

Preview

Preview. The Go client is in private preview while we lock down the public surface. Email us for a module-proxy invite — the snippet below shows the API we're shipping.

Install Shell

go get github.com/geog-ai/geog-go@latest

Hello, geog.ai Go

package main

import (
  "context"
  "fmt"
  "os"

  geog "github.com/geog-ai/geog-go"
)

func main() {
  client := geog.NewClient(geog.WithAPIKey(os.Getenv("GEOG_API_KEY")))
  res, err := client.Nearby(context.Background(), &geog.NearbyRequest{
    Lat: 31.9686, Lon: -99.9018, RadiusM: 500,
  })
  if err != nil { panic(err) }
  fmt.Println(res.Result.Entities)  // nearby assets within 500 m
}
            

✉ Request preview access

Async-job polling, in one line

Every /simulate/*, /rf/mesh/viability, /rf/optimize/placement and /optimize/* endpoint returns an AsyncJobAccepted envelope (HTTP 202) with a job.id. Without an SDK you'd write a polling loop with backoff and timeout logic. With an SDK it's one call:

Submit → wait → typed result Python

job    = geog.simulate_plume({"source": {"lat": 31.96, "lon": -99.90, "emission_rate_gs": 2.4}, "duration_min": 60, "species": "H2S"})
result = geog.wait_for_job(job["job"]["id"], interval=2.0, timeout=300)
print(result["result"]["peak_ppb"])
        

Submit → wait → typed result TypeScript

const job    = await geog.simulatePlume({ source: { lat: 31.96, lon: -99.90, emission_rate_gs: 2.4 }, duration_min: 60, species: "H2S" });
const result = await geog.waitForJob<PlumeResult>(job.job.id, { intervalMs: 2000, timeoutMs: 300_000 });
console.log(result.result?.peak_ppb);
        

The full typed-result pattern (with the JobResponse<TResult> generic and per-endpoint result shapes) is documented in the API reference's Language Clients section.

Auth & configuration

The two production SDKs follow each language's own naming conventions. Read the API key from GEOG_API_KEY in your environment and pass it to the constructor.

TypeScript — `new GeogClient(opts)`

Option	Type	Default	Purpose
apiKey	string	required	Bearer token sent on every request.
baseUrl	string	`https://api.geog.ai/v1`	Override for staging or self-hosted deployments.
siteId	string	—	Forwarded as the `X-Site-ID` header.
timeoutMs	number	`30_000`	Per-request timeout (ms).
fetch	typeof fetch	global `fetch`	Inject your own `fetch` for Node < 18, edge runtimes, or test mocks.

Regular requests do not retry automatically — wrap them in your own retry policy if you need 429 / 5xx resilience. streamPlume() reconnects with exponential backoff (default maxRetries: 5) and replays from Last-Event-ID.

Python — `GeogClient(api_key, **opts)`

Option	Type	Default	Purpose
api_key	str	required	Bearer token sent on every request.
base_url	str	`https://api.geog.ai/v1`	Override for staging or self-hosted deployments.
site_id	str	—	Forwarded as the `X-Site-ID` header.
timeout	float	`30.0`	Per-request timeout in seconds.
session	requests.Session	fresh session	Inject a pre-configured session (proxies, retries via `HTTPAdapter`, etc.).

Non-streaming Python calls do not retry on their own; pass a requests.Session with a urllib3 Retry policy if you need automatic retries. stream_plume() reconnects with exponential backoff (max_retries=5) and replays from Last-Event-ID on dropped connections.

Generate your own client

For languages we don't ship today, point any OpenAPI generator at openapi.yaml — every endpoint, parameter, and schema is fully described.

openapi-generator-cli — Java, Ruby, Rust, Kotlin, Swift, C#, PHP, … Shell

# Example: generate a Ruby client
npx @openapitools/openapi-generator-cli generate \
  -i https://geog.ai/docs/openapi.yaml \
  -g ruby \
  -o ./geog-ruby
        

Stay in sync. The spec is the source of truth — we bump info.version on every release. Re-run your generator whenever the version changes; the response envelopes ({ ok, result, meta } and the JobResponse<TResult> shape) are stable across minor versions.

If you build a community client we'd love to link it from this page — drop us a line at hello@geog.ai.

Next steps

Tutorial

Quickstart Guide →

Walk through your first four API calls — context, simulate, webhook, done.

Reference

Full API Reference →

Every endpoint, parameter, response field, and error code.

Try it

Interactive Explorer →

Fire requests at the test endpoint right from your browser.

Support

Get an API key →

Test or live key — usually issued the same business day.

Overview

Why use an SDK?

Hello world in every language

Async-job polling, in one line

Auth & configuration

TypeScript — new GeogClient(opts)

Python — GeogClient(api_key, **opts)

Generate your own client

Next steps

TypeScript — `new GeogClient(opts)`

Python — `GeogClient(api_key, **opts)`