canonical: https://jentic.com/apis/oikolab.com/oikolab

# Oikolab Weather Data API

Oikolab Weather Data API delivers 70+ years of global hourly historical and forecast weather data drawn from NOAA and ECMWF reanalysis and forecast models. Supported datasets include ERA5, ERA5-Land, GFS, GEFS, ICON, GDPS, IFS-OPEN, CFS, SILAM, HRRR, NAM-CONUS, NBM, HRDPS, ICON-EU, and ICON-D2. A single /weather endpoint returns JSON, CSV, or NetCDF for any latitude, longitude, time range, and parameter set, making it suitable for energy modelling, climate research, and operational forecasting.

## For AI agents

Retrieve hourly historical and forecast weather data from ERA5, GFS, ICON, and other models for any global coordinate via a single API call.

## Scope

Does not provide weather alerts, station-observation data, or air-quality forecasts - use for hourly NWP and reanalysis weather data retrieval only.

## Capabilities

- Pull ERA5 hourly historical weather for any latitude, longitude, and parameter back to 1950
- Retrieve GFS, ICON, or HRRR forecasts at hourly resolution for the next 7-15 days
- Request multiple parameters (temperature, wind, irradiance, precipitation) in one call
- Return data as JSON, CSV, or NetCDF for direct use in pandas or xarray
- Aggregate hourly data into daily means or sums via the resampling parameter
- Query high-resolution regional models like HRRR for North America or ICON-D2 for Europe

## Use cases

### Energy demand modelling

Utilities and energy traders pull hourly ERA5 historical temperature and forecast GFS or ECMWF data for major load centres to feed demand and price models. The single-endpoint design lets analysts request every parameter and timestamp they need in one call, returning a tidy CSV or NetCDF that drops straight into a regression or ML pipeline.

Example prompt: Request ERA5 hourly temperature, wind speed, and solar irradiance for a coordinate over the past 10 years and return a CSV

### Renewables generation forecasting

Wind and solar operators use Oikolab to backtest and operationally forecast generation by pulling reanalysis irradiance and wind data alongside near-term forecasts from HRRR, ICON, or GFS. Switching between models is a single parameter change, which lets quants compare model skill without rebuilding ingestion pipelines.

Example prompt: Pull GFS forecast wind speed at 100 m for the next 72 hours at three turbine coordinates and return a JSON time series per location

### Climate risk analytics

Insurance and infrastructure firms run climate-risk analyses using 70+ years of ERA5 reanalysis to compute return periods for heat, cold, and precipitation events. The CSV and NetCDF output formats stream directly into xarray for spatial-temporal aggregation, removing the friction of standing up Copernicus CDS access.

Example prompt: Retrieve ERA5 daily maximum temperature at a coordinate for 1980-2024 and compute the 99th percentile per decade

### AI agent weather lookup via Jentic

An AI agent answering 'what was the weather in Madrid last Tuesday?' uses Jentic to call the Oikolab API without managing the api-key header. The agent searches for a weather lookup intent, loads the /weather schema, and executes with the coordinate, parameter, and date - Jentic injects the api-key from the vault.

Example prompt: Search Jentic for a historical-weather lookup, load the /weather schema, and execute it for Madrid on a user-supplied date with hourly temperature

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/weather` | Return hourly historical or forecast weather for a coordinate, model, and parameter list |

## Key resources

- **Weather** — Single endpoint returning hourly historical or forecast values for any coordinate, parameter set, and supported model

## Why Jentic

- **Setup:** Wiring the Oikolab Weather Data API by hand means setting up its api-key header and getting the model names, parameter codes, and date formats right on the single /weather endpoint yourself. Through Jentic you install once, import Oikolab from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** The Oikolab API exposes a single read operation with no resource id in the URL path, so scoping is by operation: you limit the agent to the one operation it needs, retrieving hourly weather and reanalysis data, and it can call nothing else.
- **Credential handling:** Your Oikolab API key is stored once, encrypted, by your own Jentic One instance and injected into the api-key header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get hourly temperature for a location', and Jentic returns the /weather operation with the right model and parameter values in its input schema so the agent calls it without browsing the reference docs.

## Related APIs

- **OpenWeatherMap API** — Consumer-grade weather API with current conditions, 5-day forecasts, and historical data
- **WeatherAPI.com** — Forecast and historical weather API with simpler parameter set than NWP-model-level access
- **Visual Crossing Weather API** — Aggregated weather records useful for cross-validation against Oikolab reanalysis pulls
- **AccuWeather Core API** — Commercial forecast API with location-keyed forecasts as an alternative when NWP model output is not required

## FAQ

### What authentication does the Oikolab Weather Data API use?

The API uses an API key passed in the api-key header. Through Jentic, the key is stored encrypted in the vault and injected at request time, so the raw header value never enters the agent's context.

### Can I retrieve ERA5 historical weather with the Oikolab API?

Yes. Pass model=era5 (or era5-land for higher-resolution land data) along with the desired parameters, latitude, longitude, and a start and end date. The endpoint returns hourly values back to 1950 in JSON, CSV, or NetCDF.

### What are the rate limits for the Oikolab Weather Data API?

Oikolab applies per-account quotas based on the subscription tier. Free trial keys have lower daily call and data-volume caps; paid tiers raise these. The response headers expose remaining quota - check them in production agents and back off when nearing the limit.

### How do I pull a forecast for a specific location through Jentic?

Search Jentic for 'oikolab forecast', load the schema for /weather, and execute with model set to gfs, ecmwf, or a regional model, plus latitude, longitude, parameter list, and a future time range. The result includes hourly forecast values up to the model's horizon.

### Which output formats does the Oikolab API support?

JSON, CSV, and NetCDF are all supported through a format query parameter. JSON is most convenient for ad-hoc queries; CSV is convenient for pandas; NetCDF is preferred for scientific workloads and integrates with xarray for multi-dimensional analysis.

### Is the Oikolab Weather Data API free?

A free trial key is available with limited daily quota. Paid tiers provide higher quotas, more datasets, and commercial-use rights. Pricing is based on data volume retrieved rather than per-call, so request only the parameters and time range you need.

### Can I limit what my agent is allowed to do with the Oikolab Weather API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use. The Oikolab Weather API exposes a single read operation on the /weather endpoint with no resource id in the path, so you scope by operation: you grant the agent only that one call to retrieve hourly historical and forecast weather data, and it can invoke nothing else. Your API key is stored by your own instance and injected at request time, so the agent never sees or controls the credential.