# NuaSense

> East African farm and market data for software and agents. Live weather stations and soil probes with the agronomy computed from them (spray windows, disease risk, irrigation need, a forecast corrected to the station), and the market layer (county prices, satellite demand, news signals, food security) for Kenya, Tanzania, Uganda and Rwanda. One key, one base URL, 40 datasets, 342 fields.

Base URL `https://api.nuasense.com/api/nuasense/v1`. Every dataset is one `GET`, answers JSON and takes the same time arguments. The same data is reachable as an MCP server at `https://mcp.nuasense.com/mcp`. This page is also served at `https://api.nuasense.com/` to any client that sends `Accept: text/markdown`; the index is `https://api.nuasense.com/llms.txt`, the full field list `https://api.nuasense.com/llms-full.txt`, and the OpenAPI 3.1 description `https://api.nuasense.com/openapi.json` (for Copilot Studio, GPT Actions, Postman and frameworks that turn a spec into tools).

## For coding agents

Paste this prompt into Claude Code, Codex, Cursor or another coding agent in your project:

```text
Add NuaSense field and market data to this project. Docs: https://api.nuasense.com/index.md

1. If `npx skills add nuasense/skills` works here, run it and read the installed skill; otherwise read the docs page above. The full field list is at https://api.nuasense.com/llms-full.txt.
2. A key needs an account at https://platform.nuasense.com with a confirmed email and a verified phone. If I have no key yet, tell me the four steps (sign up, confirm the email, verify the phone under API Keys, create a key) and wait until I paste the key. Read it from an environment variable; never write it into the repository.
3. Call GET https://api.nuasense.com/api/nuasense/v1/catalog with the key. It lists the datasets this key reaches. Build only against what it lists.
4. Send the header `X-NuaSense-Client: skill/0.1.0; agent=<your name>` on every call, with your own name as the agent.
5. Pick the dataset for the task, make one call with a small `limit`, show me the rows, then build the integration. On 429 wait for `Retry-After`; on 402 tell me what needs credit and stop.
```

What the agent can do alone: read these docs, call the catalog, choose a dataset, make the first call, build the integration. What it needs you for, once: the console hands out a key only to an account with a confirmed email and a verified phone (a code by SMS or WhatsApp). The key is shown once.

### Skill and plugin

- Skill for any agent that reads `SKILL.md` files: `npx skills add nuasense/skills` (https://github.com/nuasense/skills).
- Claude Code plugin with the skill and the MCP server: `/plugin marketplace add nuasense/skills`, then `/plugin install nuasense@nuasense`.
- MCP server for Claude.ai, Claude Desktop, Claude Code and other MCP clients: `https://mcp.nuasense.com/mcp`. It signs in with your console account; no key to paste.

### Say that you are an agent

Send `X-NuaSense-Client: skill/0.1.0; agent=<your name>` on every call (for a library, `sdk/<version>`). It changes nothing in price or limits. It lets us see which integrations were built by an agent, which is how we decide what to write for agents next. Values outside `[a-z0-9._-]` are dropped, not stored.

## Access

1. Account at https://platform.nuasense.com (email, confirm). The catalogue, the docs and the market layer are open from that moment.
2. Key under **API Keys** (https://platform.nuasense.com/manage/keys). The console asks for a verified phone first. A console key carries `market:read`, `farm:read` and `location:read`. Tick **Alerts and webhooks** when creating it to add `alerts:write` (market watches, webhooks). `ingest:write` is granted on request to info@nuasense.com.
3. Send the key as a bearer token on every call. Never in the URL.

```bash
curl https://api.nuasense.com/api/nuasense/v1/catalog \
  -H "Authorization: Bearer nua_live_…" \
  -H "X-NuaSense-Client: skill/0.1.0; agent=curl"
```

### What is free and what draws on credit

**You spend units, not calls.** A row of market or location data is one unit; your own farm data is one unit per call whatever it returns; a ready-made analysis is one unit and priced separately.

|  | rows per call | units per day | units per month | history |
|---|---|---|---|---|
| no credit | 100 | 200 | 1,000 | last 30 days of market and location data |
| with credit or a station | 1,000 | 1,500 (raised per account) | no ceiling, billed against the balance | full |
| your own farm data | 5,000 | 1 unit per call |  | full |

Credit is prepaid, by M-Pesa or card under **Billing & Pricing** (https://platform.nuasense.com/manage/billing); the rate card is on that page. Writing into the platform (sending readings as JSON, webhooks, exports) needs a funded account. Registering a station and its push token is free for the first three stations on an account.

Every response carries `X-Daily-Limit`, `X-Daily-Remaining`, `X-Monthly-Remaining` where a monthly ceiling applies, `X-Credit-Balance` and the `X-RateLimit-*` family, so a client can back off before it is refused. 60 requests a minute per key.

## Reading data

Identical on every dataset:

| Parameter | Meaning |
|---|---|
| `start`, `end` | RFC3339, or a duration relative to now (`-7d`, `-24h`). Default `start=-24h`; slow datasets carry their own default. Without credit, market and location data cannot start more than 30 days back (`402`). |
| `every` + `agg` | Downsample: `every=1h&agg=mean`. `agg` is one of mean, min, max, sum, last, first, count. |
| `fields` | Comma-separated subset. It can only narrow what is published; naming a field you cannot reach answers `400`, so "not granted" is distinguishable from "no data". |
| `limit` | Default 500. Ceiling per call: 100 rows without credit, 1,000 with, 5,000 for your own farm data. Counts rows in total. The call reserves `limit` against the budget before it runs and hands back what it did not use; a `limit` above what is left is refused whole (`429`), never part-served. |
| `order` | `asc` for oldest-first. Newest-first is the default. |
| any filter | Only the filters a dataset declares are accepted; they are listed per dataset below. `gateway_id` picks one of your own stations; omitted, the primary one. |

Response shape:

```json
{
  "dataset": "farm.weather.raw",
  "fields": [
    "temperature",
    "humidity"
  ],
  "filters": {
    "gateway_id": [
      "<your gateway>"
    ]
  },
  "range": {
    "start": "-24h",
    "end": "now()"
  },
  "count": 144,
  "limit": 500,
  "rows": [
    {
      "time": "2026-07-28T10:00:00Z",
      "gateway_id": "<your gateway>",
      "temperature": 21.4,
      "humidity": 62
    }
  ],
  "metering": {
    "tier": "paid",
    "unit": "call",
    "units_charged": 1,
    "max_rows_per_call": 5000,
    "history_days": null
  }
}
```

`metering` says what the call cost: `unit` is `row` on market and location data and `call` on your own farm data.

### Errors

| Status | Meaning | What to do |
|---|---|---|
| `400` | A field you cannot reach, a bad time or aggregation value, or a continent-wide dataset called without a filter. | Fix the request; the body names the problem. |
| `401` | Missing, malformed, revoked or expired key. | Ask the human for a key. |
| `402` | Market or location history beyond the free 30 days, prepaid credit spent, or a write on an account that never topped up. | Tell the human what needs credit. Do not retry. |
| `403` | The key lacks the scope, the station is not approved for API exposure, or `gateway_id` names a station the key does not own. | Different key or different request; retrying changes nothing. |
| `404` | The dataset exists but is not published to this key. The body names it. | An answer, not a routing accident. |
| `429` | Per-minute budget, the daily unit budget or the monthly one. The body says which and how many units are left. | Wait for `Retry-After`; ask with a smaller `limit`. |
| `451` | Dataset withheld on licence grounds. | Nothing; no key unlocks it. |

## Datasets

Declared datasets are what the API can serve. What a given key actually reaches depends on its scopes and on per-field approval — call GET /catalog with your key for that answer.

### Farm (18 datasets, 192 fields)

Your own stations and soil nodes: raw uplinks, hourly and daily roll-ups, derived agronomy, disease risk, forecast and field indices.

Scope `farm:read`. Paths are relative to `https://api.nuasense.com/api/nuasense/v1`.

| Path | Dataset | Updated | Filters | Note | Fields |
|---|---|---|---|---|---|
| `/farm/weather` | Weather station readings | ~10 min | `gateway_id` |  | 20 |
| `/farm/soil` | Soil node readings | ~10 min | `gateway_id`, `dev_eui`, `node_id`, `application` |  | 14 |
| `/farm/weather/hourly` | Weather — hourly roll-up | hourly | `gateway_id` |  | 7 |
| `/farm/soil/hourly` | Soil — hourly roll-up | hourly | `gateway_id`, `dev_eui` |  | 4 |
| `/farm/weather/daily` | Weather — daily roll-up | daily | `gateway_id` |  | 6 |
| `/farm/soil/daily` | Soil — daily roll-up | daily | `gateway_id`, `dev_eui`, `node_id`, `application` |  | 5 |
| `/farm/disease-risk` | Disease + pest risk (v2) | hourly | `gateway_id`, `kind`, `threat` |  | 9 |
| `/farm/spirulina` | Spirulina pond readings | ~10 min | `gateway_id`, `node_id` |  | 4 |
| `/farm/derived` | Derived weather variables | hourly | `gateway_id` |  | 29 |
| `/farm/forecast` | Weather forecast | 6 h | `gateway_id`, `source` |  | 11 |
| `/farm/water-balance` | Root-zone water balance | daily | `gateway_id` |  | 6 |
| `/farm/field-indices` | Satellite vegetation + SAR indices | weekly | `gateway_id`, `field_id`, `aoi_name`, `source` |  | 9 |
| `/farm/climate` | Long-horizon climate archive | daily top-up; reanalysis ends ~7 days before today | `gateway_id`, `source` |  | 7 |
| `/farm/soil-baseline` | Soil baseline | once per location | time only |  | 8 |
| `/farm/fields` | Field polygons | on edit | time only |  | 8 |
| `/farm/sensor-settings` | Sensor settings | on edit | time only |  | 17 |
| `/farm/alerts` | Alert history | 10 min engine cycle | time only |  | 15 |
| `/farm/advisories` | Advisory history | daily | time only |  | 13 |

### Market (22 datasets, 150 fields)

Prices, demand, trade, regulation, news signals and food security across Kenya, Tanzania, Uganda and Rwanda, with several layers covering all of Sub-Saharan Africa.

Scope `market:read`. Paths are relative to `https://api.nuasense.com/api/nuasense/v1`.

| Path | Dataset | Updated | Filters | Note | Fields |
|---|---|---|---|---|---|
| `/market/input-prices` | Crop-protection + input retail prices | daily | `source`, `country`, `category`, `product`, `formulation`, `pack_unit`, `brand` |  | 12 |
| `/market/prices` | Commodity + fertilizer prices | daily / weekly / monthly by source | `source`, `commodity`, `variety`, `market`, `county`, `country`, `currency`, `factory`, `unit`, `price_type` |  | 20 |
| `/market/news` | Agriculture news signals | daily 10:00 UTC | `source`, `commodity`, `variety`, `county`, `country`, `signal_type`, `direction`, `trust`, `horizon` |  | 15 |
| `/market/benchmarks` | Global commodity benchmarks | monthly | `source`, `scope`, `commodity`, `unit`, `kind` |  | 1 |
| `/market/trade` | Fertilizer trade flows | monthly | `source`, `country`, `hs4`, `flow`, `partner` | withheld, answers `451` | 2 |
| `/market/demand-indices` | Satellite demand indices | 10-daily / weekly | `country`, `county`, `index`, `level`, `source` |  | 1 |
| `/market/cropland-extent` | County cropland extent | annual | `country`, `county`, `class`, `level`, `source` |  | 7 |
| `/market/crop-mix` | County crop mix | monthly | `country`, `county`, `crop`, `level`, `source` |  | 5 |
| `/market/field-structure` | County field structure | static | `country`, `county`, `stat`, `level`, `source` | withheld, answers `451` | 2 |
| `/market/realtime-prices` | Real-time market prices | monthly | `source`, `country`, `adm1`, `market`, `commodity`, `currency` |  | 3 |
| `/market/food-security` | Food-security phase classification | per analysis round | `source`, `country`, `adm1`, `area`, `level`, `phase`, `validity` | needs `country` or `admin area` | 16 |
| `/market/fews-outlook` | Food-security outlook (FEWS NET) | monthly (outlooks Feb, Jun, Oct; key message updates between) | `source`, `country`, `scenario`, `assistance`, `fnid`, `unit_type`, `adm1`, `area`, `scale` | needs `country` or `admin area` | 3 |
| `/market/fews-population` | People in need of food assistance (FEWS NET) | monthly | `source`, `country`, `scenario`, `phase`, `fnid`, `adm1`, `area`, `document` |  | 15 |
| `/market/fews-prices` | Market prices hosted by FEWS NET | monthly | `source`, `publisher`, `country`, `adm1`, `market`, `commodity`, `cpc`, `price_type`, `product_source`, `unit`, `currency` | needs `country` or `market` or `commodity` | 3 |
| `/market/fews-trade` | Cross-border trade flows (FEWS NET) | monthly (East Africa: to 09/2024) | `source`, `publisher`, `reporter`, `origin`, `destination`, `border_point`, `commodity`, `cpc`, `flow`, `trade_type`, `unit` | needs `country` or `border point` or `commodity` | 2 |
| `/market/rainfall-anomaly` | Rainfall anomaly | per season/dekad | `source`, `country`, `adm1`, `adm2`, `adm_level`, `adm_pcode`, `season` | needs `country` or `admin area` | 3 |
| `/market/rainfall-subnational` | Rainfall against normal, by admin unit | dekadal | `source`, `country`, `unit`, `pcode`, `adm_level`, `shared_with` | needs `country` | 11 |
| `/market/agri-stress` | Agricultural stress | dekadal | `source`, `country`, `region`, `asap0_id` |  | 6 |
| `/market/production` | Sub-national crop production | per season, annual revisions | `source`, `country`, `admin1`, `admin2`, `fnid`, `product`, `crop_system`, `season` | needs `country` or `crop` | 3 |
| `/market/fao-inputs` | FAO fertilizer + input statistics | annual | `source`, `country`, `dataset`, `element`, `item`, `unit` | needs `country` or `item` | 1 |
| `/market/fao-crops` | FAO crop statistics | annual | `source`, `country`, `dataset`, `element`, `item`, `unit` | needs `country` or `item` | 1 |
| `/market/regulatory` | Regulatory + legal signals | weekly, Saturday | `source`, `jurisdiction`, `country`, `commodity`, `regulation_type`, `instrument_type` |  | 18 |

Filter vocabulary worth knowing: fertilizer is `commodity=fertilizer` plus `variety=dap|urea|npk|can|mop|tsp|sulphate_of_ammonia|ammonia_anhydrous`; the continent-wide layers use ISO3 country codes (`ken`, `tza`, `uga`, `rwa`); annual statistics are stamped 1 January of the year they describe, so query them with a multi-year window. `/farm/soil-baseline` deliberately has no pH, organic carbon or N/P/K: modelled values cannot support a fertilizer decision, and current fertility comes only from a soil test.

## Ready-made analyses

Questions with a measured answer, one call each, under `https://api.nuasense.com/api/partner/v1/market`. Same key, same header. Each is one unit and priced as an analysis.

| Question | Path | Parameters | Example |
|---|---|---|---|
| What can this API do, and what are the valid names? | `/meta` | none |  |
| Which counties, regions and districts can I ask about? | `/units` | `country` | `?country=tz` |
| What does DAP cost right now, and where? | `/fertilizer/price` | `variety`, `county`, `field`, `window_days` | `?variety=dap&county=nakuru` |
| Which counties are dearest and which cheapest? | `/fertilizer/rank` | `variety`, `field`, `order`, `window_days` | `?variety=dap&order=desc` |
| What does it cost in each individual market inside a county? | `/fertilizer/markets` | `variety`, `county`, `field`, `source`, `window_days` | `?variety=dap&county=kakamega` |
| Is the price rising or falling, and by how much? | `/fertilizer/trend` | `variety`, `county`, `field`, `window_days` | `?variety=dap` |
| Which month of the year is cheapest to buy? | `/fertilizer/seasonality` | `variety`, `county`, `field` | `?variety=dap` |
| Would that seasonal rule actually have made money? | `/fertilizer/backtest` | `variety`, `county`, `field` | `?variety=dap` |
| Where is the retail-minus-wholesale markup fattest? | `/fertilizer/margin` | `variety`, `window_days` | `?variety=dap` |
| Do the official prices and the online asking prices agree? | `/fertilizer/source-compare` | `variety`, `county`, `window_days` | `?variety=dap` |
| How does the local price compare to the world market? | `/fertilizer/global-benchmark` | `variety` | `?variety=dap` |
| Can farmers here actually afford fertilizer this season? | `/fertilizer/affordability` | `variety`, `window_days` | `?variety=dap` |
| Which counties are building demand right now? | `/fertilizer/demand-board` | `country`, `limit` | `?country=ke` |
| Is demand rising in this one county, and how strongly? | `/fertilizer/demand-signal` | `county`, `country` | `?county=nakuru` |
| Give me everything about one county in a single call. | `/fertilizer/county-brief` | `county`, `country`, `variety` | `?county=nakuru&country=ke&variety=dap` |
| What is the farmer in this county actually earning? | `/fertilizer/crop-economy` | `county` | `?county=nakuru` |
| How big is the fertilizer market in this country? | `/fertilizer/market-size` | `country` | `?country=ke` |
| Who ships fertilizer into the country, and how much? | `/trade/imports` | `country`, `months` | `?country=ke` |
| When in the year does inventory get built up? | `/trade/seasonality` | `country` | `?country=ke` |
| Is importing worth it, and where does the margin sit? | `/trade/landed-cost` | `variety` | `?variety=dap` |
| Does fertilizer pass through Kenya to its neighbours? | `/trade/transit` | none |  |
| Where can I buy cheap and sell dear — and does it cover the lorry? | `/analytics/spread` | `commodity`, `window_days`, `transport_cost_kes_per_kg`, `limit` | `?commodity=maize_dry&transport_cost_kes_per_kg=8` |
| When Nairobi moves, how long until my market follows? | `/analytics/price-lag` | `commodity`, `reference`, `window_days`, `max_lag_days` | `?commodity=maize_dry&reference=nairobi` |
| Which counties are getting expensive fastest? | `/analytics/inflation` | `commodity`, `window_days` | `?commodity=maize_dry` |
| How reliable is this county's harvest, and which years failed? | `/analytics/yield-risk` | `county`, `product`, `season` | `?county=uasin_gishu&product=maize` |
| Has the season started here — early or late, and is the rain that starts one coming? | `/analytics/season` | `county`, `country`, `index` | `?county=nakuru` |
| What is registered against this pest on my crop, and how long before harvest? | `/crop-protection` | `crop`, `pest`, `country` | `?crop=tomato&pest=tuta absoluta` |
| How much fertilizer for my crop, and what does it cost me today? | `/fertilizer/recommendation` | `county`, `crop`, `altitude_m`, `level` | `?county=nakuru&crop=maize&altitude_m=1850` |
| Can I use this on my crop and still export to the EU? | `/export-residue` | `crop`, `active`, `limit` | `?crop=french_bean&active=lambda-cyhalothrin` |
| Which varieties are released for my altitude, and how long do they take? | `/varieties` | `crop`, `altitude_m`, `max_maturity_months`, `seed_company`, `limit` | `?crop=maize&altitude_m=1800&max_maturity_months=5` |
| What does coffee grade AA earn over the market? | `/analytics/coffee-grades` | `sales` | `?sales=20` |
| Which tea factory beats its neighbours? | `/analytics/tea-league` | `grade`, `sales`, `min_sales` | `?grade=all` |
| How is one county, region or district doing right now? | `/county-summary` | `county`, `country` | `?county=nakuru&country=ke` |
| What is happening in the market right now? | `/news` | `commodity`, `county`, `country`, `signal_type`, `trust`, `days` | `?commodity=fertilizer&days=14` |
| The same news signals as an RSS feed, for a reader or an inbox | `/news/feed.xml` | `api_key`, `keywords`, `commodity`, `county`, `trust`, `days` |  |
| Your standing watches — list them, or add a price watch | `/alerts` | none |  |
| Watch a county for a turn in demand | `/alerts/demand` | none |  |
| Watch for a high-trust news signal | `/alerts/news` | none |  |
| A recurring news digest by email | `/alerts/news-digest` | none |  |
| Remove a watch | `/alerts/:id` | none |  |

## MCP server

`https://mcp.nuasense.com/mcp` (Streamable HTTP). Sign-in is the console account; the tools carry read-only and destructive hints, and the server's own instructions tell the model when data is thin. Claude.ai and Claude Desktop: Settings → Connectors → add the URL. Claude Code: `claude mcp add --transport http nuasense https://mcp.nuasense.com/mcp`. Listed in the MCP Registry as `com.nuasense/agri-data`.

## Bring your own station

Any station can feed the farm layer; the first three on an account connect free. In the console under **External stations** (https://platform.nuasense.com/stations) add a station and choose how it sends:

- **Console with a custom-server screen** (Ecowitt, Froggit, Ambient, Wunderground mode): four values, server `ingest.nuasense.com`, path `/station/<token>`, port 80, interval 60 s.
- **A sensor you build** (ESP32, Arduino, Raspberry Pi; choose *I built it myself*): `POST https://api.nuasense.com/station/<token>` with JSON such as `{"device_id": "garden-pi", "temperature": 21.4, "soil_moisture": 34}`, no key. Weather, soil, water, greenhouse, beehive, storage and more; names and units: https://github.com/nuasense/station-schema. In Python: `pip install nuasense`, then `nuasense.send("<token>", "garden-pi", temperature=21.4, soil_moisture=34)`.
- **LoRaWAN**: a webhook from The Things Stack or ChirpStack to `POST https://api.nuasense.com/lorawan/<token>`.
- **Your own code, with past timestamps**: `POST https://api.nuasense.com/api/nuasense/v1/ingest/readings` with `{station_id, readings:[{time, temperature, humidity, pressure, light, wind_speed, wind_gusts, wind_direction, rain_mm}]}` (funded account, `ingest:write`).
- **Home Assistant, Node-RED, ioBroker, weewx, n8n, Python**: packages under https://github.com/nuasense; Python on PyPI as `nuasense`.

What comes back: `GET https://api.nuasense.com/api/nuasense/v1/ingest/first-look?station_id=` (tonight's low, the next calm dry daylight window, a plausibility check of the latest reading, the garden's watering need) `GET https://api.nuasense.com/api/nuasense/v1/ingest/derived?station_id=` (ET0, VPD, delta T, leaf wetness, spray quality, degree days) and `GET https://api.nuasense.com/api/nuasense/v1/ingest/disease-risk?station_id=&crop=&planted_on=` (disease and pest risk per threat for a named crop from the station's own hours; threats it cannot judge, such as soil-borne ones without a soil probe, come back not_judged with no level). Reading your own station is free.

## Your data, and what you may do with ours

- When you connect a station, NuaSense stores its readings and computes your forecast, spray windows and risks from them.
- The readings are used aggregated and anonymised to improve forecasts and models for everyone; they are never passed on individually without your opt-in, and positions on public maps are blurred.
- You can disconnect the station at any time and have all its data deleted.

The price of a read buys use, not ownership. You may use everything you pull inside your own product, analysis and reporting, for as long as you like. You may not resell it, republish it or pass it on to a third party as data; if that is what you need, write to info@nuasense.com. Some sources beneath the platform carry their own terms, and those travel with the rows: `GET https://api.nuasense.com/api/nuasense/v1/attributions` lists the credits, readable without a key.

## Help

info@nuasense.com, a person reads it. Console: https://platform.nuasense.com. Status of your own key and budget: `GET https://api.nuasense.com/api/nuasense/v1/usage`.

