TypeScript SDK · @goable-io/sdk
A thin, fully-typed transport over the public API — one request method powers every call, and the types are generated from the OpenAPI contract.
Install
npm install @goable-io/sdk
# pnpm add @goable-io/sdk · yarn add @goable-io/sdkESM, Node ≥ 18 (uses global fetch; inject your own on older runtimes). Zero runtime deps.
Quickstart
import { GoableClient } from "@goable-io/sdk" const goable = new GoableClient({ apiKey: process.env.GOABLE_API_KEY! }) const { score, verdict, breakdown } = await goable.score({ location: { lat: 36.013, lng: -5.604 }, activity: "kitesurfing", window: { from: "2026-05-23T09:00Z", to: "2026-05-23T18:00Z" }, })
Authentication
The constructor takes your key plus optional transport overrides. See Authentication for how keys work.
new GoableClient({ apiKey: string, // required baseUrl?: string, // default https://api.goable.io fetch?: FetchLike, // inject for tests timeoutMs?: number, // default 30000; 0 disables })
Methods
| Method | Endpoint | Returns |
|---|---|---|
| score(req) | POST /v1/score | Single 0–100 verdict for an activity, location and window. |
| scoreSeries(req) | POST /v1/score/series | Hourly series across the forecast horizon. |
| scoreMulti(req) | POST /v1/score/multi | Several activities at one location in one call. |
| scorePortfolio(req) | POST /v1/score/portfolio | Joint score across many spots with correlation. |
| scoreHistorical(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 (Pro+). |
| 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.
Errors
Non-2xx throws GoableApiError (with status, code, issues); transport failures throw GoableNetworkError. See Errors & rate limits.
import { GoableApiError } from "@goable-io/sdk" try { await goable.score(req) } catch (err) { if (err instanceof GoableApiError) console.error(err.status, err.code) }
Types
ScoreRequest, ScoreResponse and the rest are generated from the server's OpenAPI 3.1 spec — an API change flows into the SDK types without hand-editing. Full endpoint reference: POST /v1/score.