Weenat Developers' API V3

Quickstart

New to the Weenat API? This guide walks you through your first API call in a few minutes — no prior Weenat knowledge required. Whether you're a developer, a project manager, or just curious about what's possible, you'll have live sensor data in front of you by the end.

Authorization: Weenat-Api-Key <your-api-key>

curl https://api-prod.weenat.com/v3/devices \
  -H "Authorization: Weenat-Api-Key <your-api-key>"

{
  "count": 123,
  "next": "https://api-prod.weenat.com/v3/devices/?offset=100&limit=100",
  "previous": null,
  "results": [{
    "id": 17892,
    "brand": "Weenat",
    "serial_number": "W700349",
    "model": "CAPA-60-6",
    "model_label": "Soil capacitance probe",
    "sensor_brand": "HydrWize",
    "available_metrics": ["T_CAPA", "U_CAPA"],
    "registered_by": {
      "id": 1484,
      "name": "Atlantic Cooperative"
    },
    "location": [47.01407, -2.28703],
    "location_text": "Noirmoutier-en-l'Île, Vendée",
    "broadcast_network_provider": "LoRa",
    "latest_measurement_broadcast": "2024-07-24T09:21:40Z",
    "timezone": "Europe/Paris"
  }]
}

curl "https://api-prod.weenat.com/v3/data/devices/17892?timespan=hour&begin=2024-07-24T00:00:00Z&end=2024-07-24T23:59:59Z" \
  -H "Authorization: Weenat-Api-Key <your-api-key>"

Introduction

We are glad to introduce you the Weenat Developers API. We work hard to let you handle your own data the way you want and cover more use cases than the ones you can enjoy in our web and mobile apps.

Who is it made for?

We've made the Weenat Developers API for organizations that dispose of development capacities and can rely on one or more developers.

It can also be used by people using AI platforms and willing to exploit the full potential of this API.

Prerequisites

In order to use the Weenat Developers API, you will need:

• A Weenat App account - Create it here
• A Weenat Developers API key — Create it here
• It can be someone else's API key or yours. But if it's yours, you have to be a member of the farms or networks of farms from which you want to retrieve data.

Basic Principles

• All calls must be done on base URL: https://api-prod.weenat.com
• All values must be encoded in UTF-8.
• Time is represented using ISO 8601 timestamps such as: 2024-12-10T09:04:34Z
• Timestamps are expressed in UTC (Z). Not in local time.
• Main concepts: farms, plots, devices, data.
• All data uses the metric system. Imperial conversions must be done on your side.
• Positions use latitude and longitude [lat, long] coordinates. Some old sensors do not provide coordinates. However, geojson attributes are in MKT standard: [long, lat].

Authentication & API Keys

The API relies on API keys for authentication. Generate one in the app:

1. Sign in at app.weenat.com/auth/login
2. Go to My account
3. Navigate to Account management → API
4. Click Create a key, give it a name, and save.

Key rules

• API keys are user-based, not farm-based, nor network-based. One key can access all farms, plots and sensors one can have access to.
• Keys have no duration limit.
• Once deleted, the key is immediately invalidated.
• You can create up to 20 keys.
• API limits are per user, shared across all your keys. - View limits
• If you want to take the most advantage of the API keys limits, ask a member in each one of the farms from which you want to retrieve data to give you a key.

What can you do with it?

You can retrieve the list of affiliate farms of a network.

You can retrieve the detailed information of a farm. Whether is it an independant farm or an affiliate of a network.

You can retrieve a list of plots.

You can retrieve a list of sensors.

You can scope the list of plots per farm.

You can scope the list of sensors per farm.

You can retrieve details of a sensor per serial number.

For each plot or sensor, you can retrieve data (measurements).

The data can be retrieved at a specific timespan for a specific period.

At plot level, you always have more data because Weenat adds more metrics and several sensors can be linked to a plot.

Depending if you fetch data at plot level or sensor level, the metric name can change. Ex: T_CAL-20 at sensor level can be named T_SOIL_BY_HORIZON-20 at plot level.

Each "data" is a timestamped dataset representing a point in the history of your plot/sensor. Example:

{
  "timestamp": "2024-12-10T09:04:34Z",
  "T":   35.1,
  "U":   59.2,
  "RR":  0,
  "FF":  2.6,
  "FXY": 11.3
}

By cumulating timestamps you can rebuild a data table, convert it into a graph, understand the current situation, and make projections.

Metrics Reference

All measurements you may find in API responses:

Sensor Model Names

Both name and type are exposed in API responses.

Weenat sensors

CoRHIZE sensors

Ongoing fault events

Both ongoing fault events name and type are exposed in API responses. The timestamp is the moment when the event started.

Ongoing fault events are only exposed on Weenat sensors, not the other brands.

Events which are over are not exposed in the response.

The events exposed are those ongoing at the time of the call. A call a few seconds later may change the response.

By default, the with_ongoing_fault_events query param is not set and results do not contain the ongoing_fault_events[] array. By setting it to 'true', the response will filter devices with ongoing fault events.

Soil Texture Types

We use USDA soil texture classes, exposed in /plots and /plots/{id} responses as an ID only. Use this table to map them:

Why are metrics different between /data/devices/id and /data/plots/id?

At plot level, we have more information than at device level: soil texture, environment (open field or greenhouse), substrate type (for fertigation probes).

One of the most required metrics is U_CAPA at device level. We cannot provide it at device level because a sensor can be related to more than one plot, and each plot can have a different soil texture (and a different calibration equation (selector in the plot context panel)).

We manufacture sensors with two capacitance probe brands: HSTI (exposed as "HydrWize") and Aquacheck (exposed as "AquaChck"). Fetch the probe brand from the /plots response.

Equation

Where Y = U_CAPA (soil water content, the target value) and x = SF_CAPA (from /data/devices/{id}).

HSTI — HydrWize probes

Aquacheck — AquaChck probes

Soil Temperatures

We expose different soil temperature metrics depending on the sensor type.

T_SOIL

Temperature measured by either a Soil thermometer (T_MINI) or a Fertigation probe (EC), at the depth the sensor is installed — most of the time 5 to 10 cm deep. In the app, you cannot define any installation depth for Fertigation probes.

T_CAL-xx & T_CAPA-xx

Calibration temperatures from tensiometers and capacitive probes respectively. They are not an exact soil temperature — however, the coefficient is so small that the difference with the actual temperature is marginal.

T_SOIL_BY_HORIZON-xx

Soil temperatures from tensiometers and capacitive probes. For each horizon with multiple tensiometers, the value is the average of all tensiometers at that depth.

At data response level on /data/plots/{id}:

• If it's T_SOIL → source is a soil thermometer or fertigation probe.
• If it's T_SOIL_BY_HORIZON-xx → source is a capacitive probe or one or more tensiometers.

You can cross-reference the "devices": [] array in /plots or /plots/{id} responses to confirm the sensor type.

Broadcast Timespans

Most Weenat sensors emit every 15 minutes. Some exceptions:

Leaf Wetness Intensity (LW_I)

Leaf Wetness Intensity is derived from Leaf Wetness voltage (LW_V), but as the metric by itself is difficult to analyse we applied a mapping table. 0 being dry and 10 very very wet:

Data Model

The ultimate level of data container is a farm. A farm contains zero, one, or several plots. A device is a sensor — related to one, several, or no plot at all.

Depending on its type, each device transmits a dataset that differs in structure and timespan.

Networks & Affiliates

Both a farm and a network of farms are organizations in Weenat's database. A network can include several farms, referred to as affiliates.

Being a member of a network gives you access to data from all affiliated farms. Being a member of a single farm restricts access to that farm only.

Specific network case: shared_sensors

Most networks are flagged shared_sensors = true (by default). Some are set to false.

shared_sensors = true (default)

The network organization and all affiliate organizations share sensors and sensor data with each other — including between affiliates themselves.

shared_sensors = false

The network shares its sensors with affiliates, and affiliates share theirs back with the network. However, affiliate organizations do not share sensors between each other.

shared_sensors = true

shared_sensors = false

Members & Roles

Farms are composed of members with the following roles:

• owner — always at least one per farm
• administrator
• reader
• agent
• advisor — extra role on network-level farms, applies to all affiliates

Your role determines the same level of visibility whether you use the Weenat app or the API.

Organization endpoints recap

Geolocation

Sensor and plot positions are represented as [longitude, latitude] coordinates:

"location": [
  -1.539275561720065,
  47.272403197936285
]

GeoJSON

You can retrieve plots as GeoJSON files from: /farms, /farms/{id}, /plots, /plots/{id}.

Add the query parameter output_format=geojson. The higher the level, the more plot shapes are included in the response. All plot metadata is in the properties object in the geojson.

Rate Limits & Quotas

To balance shared resources, we enforce the following limits (per user, shared across all his API keys):

Throttling uses a sliding window. Throttled responses are not counted toward the limits.

Data periods for /data endpoints

You cannot retrieve one year of data at raw timespan in one call. But, you can do it in 25 calls.

You can retrieve one year of data at daily timespan in one call.

If you need the raw data, we recommend you store it on your side so you don't have to retrieve them again and it will not decrease a lot your limited number of authorized calls.

If you need to retrieve raw data, we advise you to do it one per day per sensor/plot. That's 1 call for 96 timestamps.

This API is not made for real time.

Caching recommendations

• /v3/plots, /v3/devices — structural data, rarely changes
• /v3/data/plots/{id}, /v3/data/devices/{id} — only changes as the requested time period extends

Frequently Asked Questions

Other Links