25:["$","title",null,{"children":"API workflow for users | Vincent Guilbaud | Observable"}] 49:T74d,html`

The API returns values in fixed units. We use the international system of units where applicable so that you can convert it on you side with ease. Here are the various units we use:

RAIN_FALL: pluviometry measured in millimiters (mm)
TEMPERATURE: temperature measured in degree Celsius (°C)
RELATIVE_HUMIDITY: relative humidity measured in percentage (%)
WIND_SPEED/WIND_GUST: wind measured in kilometers per hour (km·h−1)
WIND_DIRECTION: wind direction angle with the North in angular degrees (°) within a 0 to 360 range (360 excluded), for instance, a value of 0 means a wind coming from the North and directed to the South
WET_TEMPERATURE: wet bulb temperature in degree Celsius (°C)
LEAF_WETNESS: amount of wetness time in minutes
LEAF_SENSOR_CONDUCTIVITY: conductivity of the leaf sensor in millivolts (mV)

Please note that the old counter intuitive name (WIND_MAX, WIND_MEAN, RH_AIR_H1, TEMP_AIR_H1, RAIN_TIC) are still supported but deprecated. We will probably remove those measures in a near future.

`4a:[] 29:{"id":"0e7ae541ed09439e","slug":null,"title":"API workflow for users","thumbnail":"ccb66a236045452f992e0c0b75ef5152ec75c23a41ab700955bd709facdbe535","access_level":"public","create_time":"$D2022-01-27T14:33:38.123Z","update_time":"$D2026-10-20T08:52:05.189Z","view_time":null,"first_public_time":"$D2022-01-28T15:27:16.975Z","has_unpublished_edits":null,"fork":true,"stars":0,"starred":false,"owner":{"type":"team","id":"85625e66d2fbc546","login":"57ac0233e9966902","name":"Vincent Guilbaud","avatar_url":"https://avatars-next.observableusercontent.com/dd84ce72859446a472a0b18cc29cebf901ec4c0dbb35cbfd1aac1ca95c5424df","tier":"starter_2024","bio":"","followed_by_you":false,"follows_you":false},"version":1039,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"57ac0233e9966902","login":"57ac0233e9966902","name":"Vincent Guilbaud","avatar_url":"https://avatars-next.observableusercontent.com/dd84ce72859446a472a0b18cc29cebf901ec4c0dbb35cbfd1aac1ca95c5424df","tier":null,"bio":"","followed_by_you":false,"follows_you":false}],"members":[{"type":"individual","id":"57ac0233e9966902","login":"57ac0233e9966902","name":"Vincent Guilbaud","avatar_url":"https://avatars-next.observableusercontent.com/dd84ce72859446a472a0b18cc29cebf901ec4c0dbb35cbfd1aac1ca95c5424df","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":false,"trashed":false,"lapsed":null,"subscribed":null,"forks":2,"collection":{"id":"4949f9c3b8762911","slug":"sencrop-api-documentation","title":"Sencrop API Documentation","owner":{"id":"85625e66d2fbc546","login":"57ac0233e9966902","name":"Vincent Guilbaud"}},"type":"notebook","body":{"titling":"auto","title":"API workflow for users","cells":[{"id":0,"value":"# API workflow for users","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":644,"value":"html`

Hello fellow Sencroper! If you want to quickly learn how to use our API, you have come to the right place.

In this section you will be able to not only understand how it works but you can already try it yourself to have a clear idea on how your data will look like.

First contact

Below is the main endpoint to use for all the requests.

To check that our API is ready to go, you can first try it with this endpoint: https://api.sencrop.com/v1/ping

Otherwise, you can do a request such as below:

Now, to be able to use our API, you will first need to get your credentials, meaning the application id as well as the application secret. In order to get those, please contact us at api@sencrop.com

⚠️ Beware that your application credentials are to be kept secret and stored in a safe way. You must not use it your frontend applications. Also note that once issued, we cannot access to your application secret so take care to not loose it. ⚠️

Once you get the credentials, you will be able to use them to get your token, you can use them in the boxes below to try the API right away:

↑ First step: get your token

You will have to first get your token to start retrieving your data, we would advise you to automatically make the request below to retrieve it regularly as the token expires after a certain delay.

You can see when the token expires in the response (accessData.expires_in)

Now you can use our API using this access token

Otherwise, if you already received a token from another place, or if you impersonating as a Sencrop partner, you can replace the access token in the variable declaration above with it

↑ Get your user information

Now let start with an easy one that does not need any paramaters: request your personal data

↑ List your devices

Here you can list the devices from which you have access to, using your user id in the query

Or below you have an endpoint to get info from a specific device

↑ Organisation Devices

This request will not apply to everyone, but if you are part of several organisations, you can list the your devices depending on which organisation they are part of

In the query, you will have to choose which organisation you want the device from, how many device you want to retrieve, as well as the index in the results

↑ Daily Data

Now let's get down to business!

In this request, you will be able to retrieve the daily data from a specific device you have access to. In the query, you will need the device id, the date to retrieve the data from, the amount of days you want to retrieve (limited to the values below), and the measures you need. Optionnaly, you can specify in the query if it must include device replacements or not, the timezone of the data, weather the calibration of rain falls must be taken in count, and if you want them patched (augmenting the data with internal algorithms), which is set to true by default. More details here.

Please note that the API only accepts and gives dates in ISODate format (e.g:\"2022-01-28T01:00:00+01:00\")

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":30,"value":"viewof deviceId = Inputs.select([...devicesIds], {\n label: \"select the id of the device you want to get the data from\"\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":45,"value":"viewof startDate = Inputs.date({label: \"The date before which the data starts being retrieved\", required: true, value: new Date()})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":48,"value":"viewof nbDays = Inputs.select([7,30, 60, 90], {label: \"number of days to retrieve\"})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":53,"value":"viewof measures = Inputs.checkbox(\n [\n \"RELATIVE_HUMIDITY\",\n \"TEMPERATURE\",\n \"WET_TEMPERATURE\",\n \"RAIN_FALL\",\n \"WIND_SPEED\",\n \"WIND_GUST\",\n \"WIND_DIRECTION\",\n \"MOVE\",\n \"LEAF_SENSOR_CONDUCTIVITY\",\n \"RH_AIR_H1\",\n \"TEMP_AIR_H1\",\n \"RAIN_TIC\",\n \"WIND_MEAN\",\n \"WIND_MAX\",\n \"LEAF_WETNESS\"\n ],\n { label: \"Measures to retrieve\", value: \"TEMPERATURE\" }\n)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":58,"value":"viewof patched = Inputs.toggle({ label: \"Patched\", value: true })","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":68,"value":"dailyData = fetch(\n `${endPoint}/users/${userId}/devices/${deviceId}/data/daily?beforeDate=${new Date(\n startDate\n ).toISOString()}&days=${nbDays}&measures=${\n measures.length > 0 ? measures.toString() : \"TEMPERATURE\"\n }&patched=${patched}`,\n {\n headers: {\n Authorization: `Bearer ${accessToken}`\n }\n }\n).then((response) => {\n return response.json();\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":566,"value":"html`(obviously, if you selected a windcrop and are trying to retrieve the rainfall count, you might be disappointed with your data 🧐)

Also note that the index 0 will be the oldest value, and the last item will therefore be the most recent data

↑ Hourly Data

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":573,"value":"html`Quite similar as above, except that this time you get the data per hour`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":85,"value":"viewof deviceIdHourly = Inputs.select([...devicesIds], {\n label: \"select the id of the device you want to get the data from\"\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":88,"value":"viewof startDateHourly = Inputs.date({\n label: \"The date before which the data starts being retrieved\",\n required: true,\n value: new Date()\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":93,"value":"viewof nbDaysHourly = Inputs.select([1, 2, 7, 20, 30], {\n label: \"number of days to retrieve\"\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":97,"value":"viewof measuresHourly = Inputs.checkbox(\n [\n \"RELATIVE_HUMIDITY\",\n \"TEMPERATURE\",\n \"TEMPERATURE_MIN\",\n \"TEMPERATURE_MAX\",\n \"LEAF_SENSOR_CONDUCTIVITY\",\n \"RAIN_FALL\",\n \"WIND_SPEED\",\n \"WIND_GUST\",\n \"WIND_DIRECTION\",\n \"LEAF_WETNESS\"\n ],\n { label: \"Measures to retrieve\", value: \"TEMPERATURE\" }\n)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":100,"value":"viewof patchedHourly = Inputs.toggle({ label: \"Patched\", value: true })","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":103,"value":"hourlyData = fetch(\n `${endPoint}/users/${userId}/devices/${deviceIdHourly}/data/hourly?beforeDate=${new Date(\n startDateHourly\n ).toISOString()}&days=${nbDaysHourly}&measures=${\n measuresHourly.length > 0 ? measuresHourly.toString() : \"TEMPERATURE\"\n }&patched=${patchedHourly}`,\n {\n headers: {\n Authorization: `Bearer ${accessToken}`\n }\n }\n).then((response) => {\n return response.json();\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":110,"value":"rawDataTitle = html`

↑ Raw Data

Here you can retrieve the data in an uncompiled way, the query being really similar to the previous ones

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":122,"value":"viewof deviceIdRaw = Inputs.select([...devicesIds], {\n label: \"select the id of the device you want to get the data from\"\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":113,"value":"viewof startDateRaw = Inputs.date({\n label: \"The date before which the data starts being retrieved\",\n required: true,\n value: new Date()\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":116,"value":"viewof size = Inputs.select([10, 50, 100, 500, 1000], {\n label: \"number of data to retrieve\"\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":119,"value":"viewof measuresRaw = Inputs.checkbox(\n [\n \"RELATIVE_HUMIDITY\",\n \"TEMPERATURE\",\n \"LEAF_SENSOR_CONDUCTIVITY\",\n \"RAIN_FALL\",\n \"WIND_SPEED\",\n \"WIND_GUST\",\n \"WIND_DIRECTION\"\n ],\n { label: \"Measures to retrieve\" }\n)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":125,"value":"rawData = fetch(\n `${endPoint}/users/${userId}/devices/${deviceIdRaw}/data/raw?size=${size}&beforeDate=${new Date(\n startDateRaw\n ).toISOString()}&measures=${\n measuresRaw.length > 0 ? measuresRaw.toString() : \"TEMPERATURE\"\n }`,\n {\n headers: {\n Authorization: `Bearer ${accessToken}`\n }\n }\n).then((response) => {\n return response.json();\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":625,"value":"html`

If the discarded field is set to true, it means that our algorithm detected that the measure was wrong. It can be due to many different issues (hardware failure, bad installation, network failures etc...).

↑ Data by geolocation

The geobased data provides your insights around a given position instead of a single device. Indeed, during its usage, a device may be moved or shutdown. Also, some devices can provide you rain measures while others will instead give you wind data.\n\nFor that purpose, you may prefer get available data for a given place in your Sencrop network.

Here we've set the location to the address registered with your account, but feel free to use another one to give it a try.

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":149,"value":"viewof userLongitude = Inputs.text({\n label: \"insert longitude\",\n value: userData.places[Object.keys(userData.places)[0]].contents.longitude\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":166,"value":"viewof userLatitude = Inputs.text({\n label: \"insert latitude\",\n value: userData.places[Object.keys(userData.places)[0]].contents.latitude\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":169,"value":"viewof startDateGeo = Inputs.date({\n label: \"The date before which the data starts being retrieved\",\n required: true,\n value: new Date()\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":172,"value":"viewof nbDaysGeo = Inputs.select([7, 30, 60, 90], {\n label: \"number of days to retrieve\"\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":175,"value":"viewof measuresGeo = Inputs.checkbox(\n [\n \"RELATIVE_HUMIDITY\",\n \"TEMPERATURE\",\n \"TEMPERATURE_MIN\",\n \"TEMPERATURE_MAX\",\n \"LEAF_SENSOR_CONDUCTIVITY\",\n \"RAIN_FALL\",\n \"WIND_SPEED\",\n \"WIND_GUST\",\n \"WIND_DIRECTION\",\n \"LEAF_WETNESS\"\n ],\n { label: \"Measures to retrieve\", value: \"TEMPERATURE\" }\n)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":178,"value":"geoData = fetch(\n `${endPoint}/users/${userId}/data/daily?latitude=${userLatitude}&longitude=${userLongitude}&beforeDate=${new Date(\n startDateGeo\n ).toISOString()}&days=${nbDaysGeo}&measures=${\n measuresGeo.length > 0 ? measuresGeo.toString() : \"TEMPERATURE\"\n }`,\n {\n headers: {\n Authorization: `Bearer ${accessToken}`\n }\n }\n).then((response) => {\n return response.json();\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":640,"value":"html`

You can notice a new property called precision that tells you how precise is the result. Indeed, the devices on which are based the data may not be at the exact position you provided but instead in a ten kilometers ring around it.\n\nThis precision field goes from 0 to 100 and is based on statistical studies we made upfront. That precision may vary depending on the kind of measure. It may also change since we will probably reshape our statistical algorithms for more sharp results.\n\nNote that the days query parameter is mandatory and limited to a few values. Check out the API reference for more information.

↑ Statistics

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":770,"value":"viewof deviceIdStats = Inputs.select([...devicesIds], {\n label: \"select the id of the device you want to get the data from\"\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":773,"value":"viewof startDateStats = Inputs.date({\n label: \"The date after which the data starts being retrieved\",\n required: true,\n value: new Date()\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":776,"value":"viewof endDateStats = Inputs.date({\n label: \"The date before which the data are being retrieved\",\n required: true,\n value: new Date()\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":779,"value":"viewof measuresStats = Inputs.checkbox(\n [\n \"RELATIVE_HUMIDITY\",\n \"TEMPERATURE\",\n \"TEMPERATURE_MIN\",\n \"TEMPERATURE_MAX\",\n \"LEAF_SENSOR_CONDUCTIVITY\",\n \"RAIN_FALL\",\n \"WIND_SPEED\",\n \"WIND_GUST\",\n \"WIND_DIRECTION\",\n \"LEAF_WETNESS\"\n ],\n { label: \"Measures to retrieve\", value: \"TEMPERATURE\" }\n)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":782,"value":"viewof intervalStats = Inputs.select([\"15m\", \"1h\", \"1d\"], {\n label: \"interval\"\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":767,"value":"statisticData = fetch(\n `${endPoint}/users/${userId}/devices/${deviceIdStats}/statistics?startDate=${new Date(\n startDateStats\n ).toISOString()}&endDate=${new Date(endDateStats).toISOString()}&measures=${\n measuresStats.length > 0 ? measuresStats.toString() : \"TEMPERATURE\"\n }&interval=${intervalStats}`,\n {\n headers: {\n Authorization: `Bearer ${accessToken}`\n }\n }\n).then((response) => {\n return response.json();\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":694,"value":"glossaryTitle = html`

↑ Glossary

Thank you for bearing with us through this documentation, we hope you got everything you need to do good use of our API. \nYou can also check our API reference for more details.

If you got any issue do not hesitate to contact us at api@sencrop.com and we will sort it out.