Docs·Getting started·Quickstart

From zero to a verdict in five minutes

One REST call turns weather, ocean, atmospheric and astronomical data into a single 0–100 suitability score for an activity, a place and a time. Here is the shortest path to your first one.

1 · Get a key

Sign up, then mint a key from your tenant portal. Keys are prefixed and SHA-256 hashed server-side; see Authentication for handling and rotation. The Free plan gives 1,000 calls/month (hard cap), enough to build with. Upgrade to Starter (€49/mo, 50k calls included + €1.50/1k overage) for production traffic. Full plan reference.

2 · Install the SDK

The TypeScript SDK is the most ergonomic path; it is zero-dependency and fully typed. cURL works anywhere if you prefer raw HTTP.

# npm · pnpm · yarn
npm install @goable-io/sdk

# or Python
pip install goable-sdk

3 · Your first score

Construct the client once with your key, then call score with an activity, a location and a time window:

import { GoableClient } from "@goable-io/sdk"

const goable = new GoableClient({
 apiKey: process.env.GOABLE_API_KEY!,
})

const result = await goable.score({
 activity: "kitesurfing",
 location: { lat: 36.01, lng: -5.61 }, // Tarifa
 window: { from: "2026-06-01T09:00:00Z", to: "2026-06-01T15:00:00Z" },
})

console.log(result.score, result.verdict)

The same call over HTTP:

curl https://api.goable.io/v1/score \
  -H "X-Goable-Key: $GOABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"activity":"kitesurfing","location":{"lat":36.01,"lng":-5.61},"window":{"from":"2026-06-01T09:00:00Z","to":"2026-06-01T15:00:00Z"}}'

4 · Read the verdict

Every response carries a score (0–100), a verdict, a per-dimension breakdown, a confidence block and the raw physical readings:

{
 "score": 82,
 "verdict": "favorable",
 "confidence": 0.78,
 "breakdown": [
 { "name": "wind", "value": 14.2, "suitability": 0.91, "weight": 0.4, "contribution": 0.36 }, …
 ],
 "eco": { energy_class: "moderate", … }
}

The verdict is one of excellent (86–100), favorable (71–85), fair (51–70), marginal (31–50), poor (1–30), not_feasible or unsafe. A universal hard gate (lightning ≥ 0.85 or hazardous AQI) forces unsafe regardless of the rest; a profile's own feasibility gate (e.g. no rideable wind) forces not_feasible instead — impossible, not dangerous. The full model is in Scoring model & verdicts.

Next steps

Explore the full request/response on the score endpoint reference, understand the bands and confidence in Concepts, or browse every endpoint in the interactive API Reference. When a session happens, you can report the outcome via the outcome endpoint. Outcome reporting is how the engine will calibrate to your spots once enough paired outcomes accumulate.