SDK Documentation - AgroClimaX

Installation

Include the SDK via a script tag or import it in your bundler. No npm packages required.

Browser (CDN / self-hosted)

<script src="/sdk/climax-sdk.js"></script>

Node.js / Bundler

const AgroClimaX = require('./sdk/climax-sdk.js');

Basic Usage

// Initialize the client const client = new AgroClimaX({ apiKey: 'clmx_your_api_key', baseUrl: 'https://api.climax.ai' }); // Run a forecast for Montevideo const forecast = await client.forecast({ model: 'AIFS Single', lat: -34.9, lon: -56.2, lead_hours: 72, variables: ['2t', '10u', '10v'] }); console.log(forecast);

API Key Setup

All requests are authenticated via an X-API-Key header. Obtain your key from the Customer Portal and pass it to the constructor.

const client = new AgroClimaX({ apiKey: 'clmx_sk_live_abc123...', baseUrl: 'https://api.climax.ai' // optional, defaults to current origin });

If no apiKey is provided, the SDK omits the header, which is useful for local development against an unauthenticated backend.

Option	Type	Description
apiKey	string	Your AgroClimaX API key (prefix `clmx_`)
baseUrl	string	API base URL. Defaults to `''` (current origin)

forecast(opts)

POST /api/v1/forecast-runs

Trigger a forecast run and return results.

Param	Type	Description
model	string?	Model name, e.g. `'AIFS Single'`
lat	number	Latitude (required)
lon	number	Longitude (required)
lead_hours	number?	Lead time in hours
variables	string[]?	Variable codes, e.g. `['2t','tp']`

const result = await client.forecast({ model: 'GraphCast', lat: -31.4, lon: -55.5, lead_hours: 48, variables: ['2t', 'tp', 'msl'] }); // result.run_id, result.steps, result.variables ...

nowcast(opts)

POST /api/v1/nowcast

Short-range nowcast (0-6 hours) at high temporal resolution.

Param	Type	Description
lat	number	Latitude (required)
lon	number	Longitude (required)
lead_minutes	number?	Lead time in minutes (default: 360)
variables	string[]?	Variable codes

const now = await client.nowcast({ lat: -34.9, lon: -56.2, lead_minutes: 120, variables: ['2t', 'tp'] }); console.log('Nowcast steps:', now.steps);

models(), datasets(), benchmarks()

GET /api/v1/models | GET /api/v1/datasets | GET /api/v1/benchmarks

Retrieve platform catalogs.

const models = await client.models(); const datasets = await client.datasets(); const bench = await client.benchmarks('AIFS Single'); // optional model filter

frostRisk(opts)

POST /api/v1/decision/frost-risk

Evaluate frost probability and severity for a location.

Param	Type	Description
lat	number	Latitude (required)
lon	number	Longitude (required)
lead_hours	number?	Forecast horizon in hours

const frost = await client.frostRisk({ lat: -33.0, lon: -56.5, lead_hours: 24 }); console.log('Risk level:', frost.risk_level); // "high" | "moderate" | "low"

heatStress(opts)

POST /api/v1/decision/heat-stress

Compute heat stress index (WBGT) for a location.

const heat = await client.heatStress({ lat: -34.9, lon: -56.2 }); console.log('WBGT:', heat.wbgt_index);

renewablesWindow(opts)

POST /api/v1/decision/renewables-window

Find optimal production windows for renewable energy assets.

const window = await client.renewablesWindow({ lat: -33.5, lon: -53.4, asset_type: 'wind' }); console.log('Best window:', window.optimal_start, '-', window.optimal_end);

agriAssess(opts)

POST /api/v1/verticals/agri/assess

Comprehensive agricultural weather assessment for a field location.

Param	Type	Description
lat	number	Latitude (required)
lon	number	Longitude (required)
crop_type	string?	e.g. `'soy'`, `'wheat'`, `'rice'`

const agri = await client.agriAssess({ lat: -32.3, lon: -54.2, crop_type: 'soy' }); console.log(agri.frost_risk, agri.precipitation_outlook);

energyAssess(opts)

POST /api/v1/verticals/energy/assess

Energy production forecast and curtailment risk assessment.

Param	Type	Description
lat	number	Latitude (required)
lon	number	Longitude (required)
asset_type	string	`'solar'` or `'wind'` (required)
capacity_mw	number?	Installed capacity in MW

const energy = await client.energyAssess({ lat: -33.5, lon: -53.4, asset_type: 'solar', capacity_mw: 50 }); console.log('Estimated generation:', energy.generation_mwh);

provenance(runId)

GET /api/v1/explain/provenance/:id

Retrieve the full provenance chain for a forecast run: data sources, model version, pipeline steps, and license metadata.

const prov = await client.provenance('run_abc123'); console.log(prov.data_sources); // ["ERA5", "GFS-0.25"] console.log(prov.model_version); // "AIFS-v1.2.0" console.log(prov.license); // "CC-BY-4.0"

narrative(runId)

GET /api/v1/explain/narrative/:id

Generate a human-readable narrative explaining the forecast in natural language, including confidence levels and key drivers.

const story = await client.narrative('run_abc123'); console.log(story.summary); // "Temperature expected to drop to 2C by 06:00 UTC, driven by // a cold front advancing from the southwest. Confidence: high."

subscribe(onEvent) / unsubscribe()

SSE /api/v1/events/stream

Subscribe to platform events via Server-Sent Events. Receive live updates for completed forecasts, new alerts, and system status changes.

// Start listening client.subscribe(function (event) { console.log('Event type:', event.type); console.log('Payload:', event.data); if (event.type === 'forecast.completed') { console.log('Run', event.data.run_id, 'finished!'); } }); // Later, stop listening client.unsubscribe();

The SSE connection auto-reconnects on network errors. Error events are delivered to your callback with type: 'error'.

Try/Catch Pattern

All async SDK methods throw an Error when the server returns a non-2xx response. The error object includes status (HTTP code) and body (parsed JSON).

try { const result = await client.forecast({ lat: -34.9, lon: -56.2 }); console.log(result); } catch (err) { console.error('Status:', err.status); // 401, 422, 500 ... console.error('Message:', err.message); // "Invalid API key" console.error('Body:', err.body); // full JSON response }

Common Error Codes

Status	Meaning	Action
401	Unauthorized	Check your API key
403	Forbidden	Key lacks required scope
422	Validation Error	Check request parameters
429	Rate Limited	Back off and retry
500	Server Error	Retry or contact support

SDK Cliente

Quick Start