Python SDK · goable-sdk
A thin, fully-typed httpx transport over the public API — it mirrors the TypeScript client 1:1 (snake_case methods), and the request/ response types are pydantic v2 models generated from the live OpenAPI contract. It covers 100% of the public API surface: scoring, recommend-spot, decision, counterfactual explain, intelligence, underwriting, observations, and outcomes.
Install
pip install goable-sdk
v0.1.0, MIT licensed, on PyPI (pypi.org/project/goable-sdk). Requires Python 3.10+ and is built on httpx and pydantic v2. Source + the full method list: github.com/goable-io/python-sdk.
Quickstart
import os from goable_sdk import GoableClient goable = GoableClient(api_key=os.environ["GOABLE_API_KEY"]) result = goable.score({ "location": {"lat": 36.013, "lng": -5.604}, "activity": "kitesurfing", "window": {"from": "2026-05-23T09:00Z", "to": "2026-05-23T18:00Z" }, }) print(result.score, result.verdict)
Authentication
The constructor takes your key plus optional transport overrides. See Authentication for how keys work.
GoableClient( api_key, # required — sent as X-Goable-Key *, base_url=..., # default https://api.goable.io timeout=30.0, # seconds; 0 or None disables client=..., # inject an httpx.Client (tests) )
Methods
| Method | Endpoint | Returns |
|---|---|---|
| score(req) | POST /v1/score | Single 0–100 verdict for an activity, location and window. |
| score_series(req) | POST /v1/score/series | Hourly series across the forecast horizon. |
| score_multi(req) | POST /v1/score/multi | Several activities at one location in one call. |
| score_portfolio(req) | POST /v1/score/portfolio | Joint score across many spots with correlation. |
| score_historical(req) | POST /v1/score/historical | Percentiles + exceedance over the ERA5 archive. |
| projections(req) | POST /v1/projections | CMIP6 / CORDEX climate-decadal projections (Scale). |
| decision(req) | POST /v1/decision | Personalised go / no-go decision (any plan; reasoning narrative needs your own Anthropic key). |
| recommend_spot(req) | POST /v1/recommend-spot | Top-K ranked sub-spots in a region. |
| explain_counterfactual(req) | POST /v1/score/explain-counterfactual | Binding constraint, sensitivities, best window, best nearby spot. |
| explain(req) | POST /v1/intelligence/explain | Natural-language explanation of a score (any plan; needs your own Anthropic key). |
| briefing(req) | POST /v1/intelligence/briefing | Multi-slot narrative briefing (any plan; needs your own Anthropic key). |
| quote(req) | POST /v1/underwriting/quote | Parametric premium quote (Scale). |
| bind_policy(req) | POST /v1/underwriting/policy/bind | Convert a quote into a bound policy (Scale). |
| report_outcome(session_id, req) | POST /v1/score/:id/outcome | Report what actually happened for a scored session. |
| health() | GET /v1/health | Liveness / readiness probe. |
Try it
Pick an activity, a spot and the flags. Runs against the live engine (public demo tenant, 60 calls / hour / IP); falls back to a deterministic sample.
Display-only — the real /v1/score request has no option to omit fields; this just trims what's shown here.
Errors
Non-2xx raises GoableAPIError (with status, code, issues, plus retry_after_seconds / rate_limit); transport failures raise GoableNetworkError. A refused underwriting bind raises DriftActiveError, a subclass of GoableAPIError. See Errors & rate limits.
from goable_sdk import GoableAPIError try: goable.score(req) except GoableAPIError as err: print(err.status, err.code)
Types
ScoreResponse and the rest are pydantic v2 models generated from the server's OpenAPI 3.1 spec, importable straight from goable_sdk — an API change flows into the models without hand-editing. Full endpoint reference: POST /v1/score.