INTRODUCTION

Welcome to Pessl Instruments GmbH RESTful API. It allows you to manage your account, devices and its data.

Our API is following all the standards of the RESTful services therefore implementation should be straight forward in any language you may be using.

Before you start we recommend checking if you are using latest version of the API.
We recommend using latest version and also migrate to it when ready to make that step because we extend features only for latest major version.

Documentation overview

On your left side you will find your main navigation bar. The navigation bar will show you topic pages and RESTful API requests grouped. Middle pane reflects the content and specifications depending on your selected topic. The right pane will provide you code examples, input and output schemas if any.

API How to start

We recommend going trough the documentation to establish your footing.

  1. Go trough info and authentication section
  2. Select your authentication method that suit your needs
  3. Go over requests routes, to see what is possible
  4. Check examples present in right pane
  5. If some questions can not be answered withing this documentation do not hesitate contacting us via ticketing http://support.metos.at or via email api@metos.at

How To connect with API

Examples how to connect with our API using Javascript, PHP, Python and Dart Available on our public https://bitbucket.org/pesslinstrumentsgmbh/api-examples/src/master/

Postman collection

We have a Postman collection which will be update constantly https://docsdev.fieldclimate.com/#intro

Rate limiter

The rate limiter is in the testing phase, but our recommendation is not to exceed an hourly quota of 8000 per request and per station and a daily quota of 192000. If you exceed, you might be blocked.

Support

Create a ticket at http://support.metos.at

What good support tickets should contain:

  1. Username of account you are using
  2. HMAC Public key or OAuth 2.0 Application name if existing
  3. If you are experiencing issues with station or data itself please specify the STATION ID and period which is troubling you
  4. Full request information (Request method, URL and JSON of the data which you are sending )
  5. Full response information (Response code, message or result it self)
  6. Your input and expected output
{
    "version" : {
        "title" : "2.0",
        "url"   : "https://api.fieldclimate.com/v2"
        "doc"   : "https://api.fieldclimate.com/v2/docs/"
    },
    "status"  : "Production (latest version); v1 is still supported as well"
    "release_date" : "04.02.2019",
    "changelog" : {
        "/user/stations" : "returns empty list [] in case of missing stations instead of 204 (No Content)"
        "/data/" : "returns empty list [] in case of missing data instead of 204 (No Content)"
        "/data/" : "FORMAT optimized is default, normal does not exist anymore"
        "/data/" : "Single and consistent output format (POST & GET), all data on same level (forecast, disease models, station)",
        "/data/" : "Combine disease models, and weather station data",
        "/data/" : "Retrieve multiple disease models in one call",
        "/data/" : "Soil moisture values with applied calibrations according to configuration on https://ng.fieldclimate.com" 
        "Disease model data" : "/disease routes removed, disease models can be retrieved via /data POST calls",
        "Disease model data" : "All disease models ported/migrated to new system",
        "/forecast" : "Removed irrelevant aggregations from URL, hourly forecast is default"
        "Forecast data" : "Forecast data options now in 3 day and 7 day forecast",
        "Forecast data" : "New forecast images",
        "Forecast data" : "Added forecast based work planning services from iMeteoPRO, POST",
        "Charting" : "Predefined charts supported only",
        "API" : "Unified error codes and messages",
        "oAuth 2.0" : "Support for OpenID",
    }
}

Weather station

Each weather station is supplied with unique ID that is always 8 characters long (we call it Station ID or serial number, example: 00000146).

There are many types of stations that we support. Most of them can use all of the station specific functionalities offered by the API, but
some are limited (Example CropView stations are only able to use CropView functionalities).

Station types:

  • 0 = iMetos 1
  • 1 = iMetos 1
  • 2 = iMetos 2
  • 3 = iMetos SD
  • 4 = iMetos AOS
  • 5 = iMetos 3
  • 6 = iMetos D2
  • 7 = iMetos 3.3
  • 8 = iMetos ECO D3
  • 28 = iMetos ICA
  • 40 = iMetos Track
  • 41 = Active Tracker
  • 42 = Object Tracker
  • 49 = uMetos CLIMA (NBIoT)
  • 50 = uMetos
  • 51 = uMetos NBIoT
  • 52 = uMetos LoRa
  • 53 = LoRATH (LoRaWAN)
  • 55 = LoRAIN SOIL (LoRaWAN)
  • 56 = LoRATH SOIL (LoRaWAN)
  • 57 = uMetos SOIL (NBIoT)
  • 58 = LoRAIN (NBIoT)
  • 59 = LoRATH (NBIoT)
  • 60 = LoRAIN SOIL (NBIoT)
  • 61 = LoRATH SOIL (NBIoT)
  • 70 = CropVIEW
  • 71 = CropVIEW Zoom
  • 72 = iSCOUT
  • 73 = CropVIEW Panorama
  • 76 = nMetos80
  • 77 = nMETOS100+
  • 78 = SolAntenna

Device architecture related to the API

  • DEVICE - Station itself identified by 8 chars long unique ID
  • SENSOR - 100+ sensors can be connected to the station and each one is identified by sensor code
  • SENSOR GROUP - Sensor group code is identifier of sensors with same specification (For example same functionality but different manufacturer)
  • CHANNEL - Sensors connected to the device are using CH as connection identifier with the device. CH themselves are dynamically assigned to the sensor, only few are fixed and are unique each time.
  • CHAIN - Chains are extension cables that allow us to connect more sensors to the station.
  • MAC - Wireless nodes that act as a device and are connected to main device can have also sensors connected to them. They are identified using MAC address.
  • SERIAL - Sensors with multiple outputs are normally having unique serial number to identify the sensor itself as a whole
  • AGGREGATION - Each sensors output the data in one of the aggregations (time, last, sum, min, max, avg, user)

Workflows

Most common workflows explained to help you understand the possibilities and best practices to integrate our API into your environment.

Fetching station data

User can have multiple devices assigned to his account. Therefore first call we make is to get list of the user stations that he has.
Second thing that we need to know is min and max date of the data available to us. For that reason we make a call for station information
which gives us necessary dates. When we have dates all we need to do is request the data for required time period.

  1. GET - /user/stations
  2. GET - /station/STATION-ID
  3. GET - /data/STATION-ID/GROUP-BY/from/TIMESTAMP/to/TIMESTAMP

Above approach can be used to fetch data into your own database by tracking dates in your database and our and just fetch missing parts.

Timestamps

iMetos devices always operate and provides data in local station time. You can configurable the station time via this FieldClimate API or using the FieldClimate portal. Note that the device has to pickup the configured time from the server, which depends on the the configured transfer interval.

Some API routes contain timestamps, those are UNIX epochs (originally defined as GMT) but in this case can be used directly as if they would be local station time.

Feed widget

You wish to display latest temperature, wind speed ... all you need todo is to call last 1 to get latest entry of a station and
display it.

  1. GET - /user/stations
  2. GET - /data/STATION-ID/GROUP-BY/last/1

Specifications

Request

RESTful requests should be made following latest RESTful standards.

Headers

  • Authorization -> Required for oAuth2 authentication
  • Date -> Required for oAuth2 and HMAC authentication
  • Accept -> application/json only supported

Methods

  • GET - Reading
  • PUT - Updating
  • POST - Creating
  • DELETE - Removing
  • OPTIONS - All the options that call has

Response

RESTful responses are being made by following latest RESTful standards.

HTTP Response Status Codes most relevant for this API

  • 200 - OK
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 405 - Method Not Allowed
  • 406 - Not Acceptable
  • 409 - Conflict
  • 500 - Internal Server Error

If you are experiencing HTTP code 500 please contact support with all details of the request.

Response formats

We only support JSON format for the response.

JSON Schemas

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents.

Advantages

  • describes your existing data format
  • clear, human- and machine-readable documentation
  • complete structural validation, useful for describing and validating data inputs

JSON Schema specifications can be found HERE

Where can i find your schemas?

Depending of version you are using all our schemas can be found at https://api.fieldclimate.com/**version**/schemas/

NOTE: Mostly requests that require POST, PUT methods are using JSON schema. When you are browsing trough routes you will notice that in the right pane there is a tab Schema and Body, this two tabs contain JSON schema and example.

{
  "title": "Station Name Update Schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "mac": {
      "type": "string",
      "description": "MAC address or Station ID as X (X indicates default station)"
    }
  },
  "required": [
    "name",
    "mac"
  ],
  "additionalProperties": false,
  "description": "additionalProperties means that no new property can be created ... Data updated as whole object will overwrite whole set in database. Required property needs to be specified. Pattern is pattern in regex"
}
{
  "title": "User ",
  "type": "object",
  "properties": {
    "custom_name": {
      "type": "string",
      "pattern": "^[a-zA-Z\\s\\d]{0,35}$",
      "description": "Only characters, numbers, spaces and max length 35"
    }
  },
  "additionalProperties": false,
  "description": "additionalProperties means that no new property can be created .... Data updated as whole object will overwrite whole set in database. Required property needs to be specified. Pattern is pattern in regex"
}

RESTful API routing

We grouped our routes into meaningful groups that may help you travers the API.

List of groups

List of groups is sorted by most common to less and by recommended usage.

  1. SYSTEM
    Calls that give you in depth information regarding system itself. Which sensors are supported ...
  2. USER
    User related operations like get user information, update it, user stations...
  3. STATION
    Before you do data calls it is nice to know more about the device itself.
  4. DATA
    Requesting data which your device generates.
  5. FORECAST
    Requesting forecast data of your devices position.
  6. CHART
    Visualize any data, weather station, disease model and forecast data.
  7. FEED
    Intended for feed widgets to get information of specific sensors for last week or day...
  8. DEV
    Are you creating large scale application that uses Pessl Instruments GmbH user base.
    To manage your application, users and theirs stations we provide necessary calls.

Authentication

Our API supports two methods for authentication, authorization and data encryption. The first one, HMAC (Keyed-hash message authentication code), is widely used and easy to implement.
HMAC uses a cryptographic secure hash algorithm (SHA-256 in our case) to encode messages based on concatenation with a secret key. You need your public and private FieldClimate API account key pair before you can use this method.
The second method, OAuth 2.0, is an open standard for authorizing 3rd-party client applications to access server resources on behalf of a user without exchanging user credentials with clients.
OAuth requires registration of the client application with name and redirect URI (protected with TLS security). After successful registration the authorization service provides a client ID and a client secret.

Requesting API access

  • HMAC
    1. Visit FieldClimate
    2. Go to User menu > API services
    3. Click GENERATE NEW and copy the keys
  • OAuth 2.0

    Contact api@metos.at and provide the specified information:

    1. Username of the Fieldclimate account that will handle oAuth 2.0 application/s and it's users
    2. Application name(s)
    3. Redirect URI(s)

Security

The following techniques are used to protect your data and ensure secure communication with our services:

  1. HTTPS
    (also called HTTP over TLS, HTTP over SSL, and HTTP Secure) is a protocol for secure communication over a computer network which is widely used on the Internet.
  2. HTTP Header and Methods validation
    Requests need to pass header validations and method needs to be supported
  3. Authentication
    HMAC or OAuth
  4. Password encryption
    All passwords are encrypted in our database with BCRYPT cost 12.
  5. Event logging
    Logging all important events
  6. Rate Limit
    At the moment disabled, limits the number of requests in a specific time period
  7. Access points
    Different access points to API admin, developer (OAuth) and user

HMAC

HMAC, or Hash Message Authentication Code, provides an easy mechanism for verifying both user authenticity and that a message hasn't
been tampered. This protocol uses a public and a private key which can be generated in FieldClimate. HMAC is also widely
supported by different kinds of programming languages and for that reason please refer to your preferred programming language documentation
regarding HMAC authentication. In this documentation we will just explain when to use HMAC and when not.

Benefit and Motivation

Easiest way to interact with our API. It is supported by most programming languages. HMAC access point in our case is on user
level in which you are able to access his/her information (user, station, data ... ) and not users out of scope.

If user handling is not top priority of yours and your focus is on data, this is the authentication method for you.

NOTE: DEV routes are not available if using HMAC

HMAC Integration

We provide you with public and private key. Public key is known to everyone however private key is only known
to the user and the API service provider. Private key is being used to generate encoded signature which is afterwards
included in authorization header.

Mandatory HTTP header fields
Header field name
value
Authorization hmac {PUBLIC-KEY}:{SIGNATURE}
Date Wed, 09 Aug 2017 20:32:38 GMT

Signature
The HTTP header authorization signature is generated using the cryptographic SHA-256 algorithm based on
HTTP method, API route, current timestamp in RFC2616 format, and public key concatenated with the private key.

Find some examples in the section on the right.

Requesting HMAC API access

1. Visit [FieldClimate](https://ng.fieldclimate.com)
2. Go to User menu > API services
3. Click GENERATE NEW and copy the keys
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/data/{STATION-ID}/raw/last/5";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;
const API = {
    async getFetch(params) {
      const method = params.method
      const body = params.body
      const public_key = "YOUR-PUBLIC-KEY";
      const private_key = "YOUR-PRIVATE-KEY";
      const baseurl = "https://api.fieldclimate.com/v2";
      const timestamp = new Date().toUTCString(); 
      const content_to_sign = params.method + params.request + timestamp + public_key;
      const signature = CryptoJS.HmacSHA256(content_to_sign, private_key);
      const hmac_str = 'hmac ' + public_key + ':' + signature;
      const url = baseurl + params.request;
      const parameters = {
          headers:{
              "Accept":"application/json",
              "Authorization": hmac_str,
              "Request-Date": timestamp,
          },
          method,
          body
      };
  
      return await fetch(url, parameters)
          .then(data => { return data.json() })
          .then((resp) => {
              return resp;
          })
          .catch(error => console.log(error))
    },
      getStations() {
          let params = {
              "method" : "GET",
              "request": "/user/"
          }
          API.getFetch(params)
          .then((result) => {
              result.map((userData, key) => {
                  console.log(userData);
              })
          })
      },
  }
  
package com.company;

import org.apache.commons.codec.binary.Hex;
import org.apache.http.HttpEntity;
import org.apache.http.HttpHeaders;
import org.apache.http.HttpHost;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpUriRequest;
import org.apache.http.client.methods.RequestBuilder;
import org.apache.http.client.utils.DateUtils;
import org.apache.http.config.Registry;
import org.apache.http.config.RegistryBuilder;
import org.apache.http.conn.ConnectTimeoutException;
import org.apache.http.conn.socket.ConnectionSocketFactory;
import org.apache.http.conn.socket.PlainConnectionSocketFactory;
import org.apache.http.conn.ssl.SSLConnectionSocketFactory;
import org.apache.http.conn.ssl.TrustSelfSignedStrategy;
import org.apache.http.conn.ssl.TrustStrategy;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.impl.conn.PoolingHttpClientConnectionManager;
import org.apache.http.protocol.HttpContext;
import org.apache.http.ssl.SSLContextBuilder;
import org.apache.http.ssl.SSLContexts;
import org.apache.http.util.EntityUtils;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.net.ssl.SSLContext;
import javax.net.ssl.SSLSocket;
import javax.net.ssl.SSLSocketFactory;
import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.lang.reflect.InvocationTargetException;
import java.net.InetSocketAddress;
import java.net.Socket;
import java.security.GeneralSecurityException;
import java.security.cert.CertificateException;
import java.security.cert.X509Certificate;
import java.util.Date;

    public class HMacExample {

        public static void main(String[] args) throws IOException, GeneralSecurityException {

            String publicKey = "YOUR PUBLIC HMAC KEY";
            String privateKey = "YOUR PRIVATE HMAC KEY";

            SSLContextBuilder builder = new SSLContextBuilder();
            builder.loadTrustMaterial(null, new TrustStrategy() {
                    @Override
                    public boolean isTrusted(X509Certificate[] chain, String authType) throws CertificateException {
                    return true;
                }
            });

            SSLConnectionSocketFactory sslSF = new SSLConnectionSocketFactory(builder.build(),
            SSLConnectionSocketFactory.ALLOW_ALL_HOSTNAME_VERIFIER);

            HttpClient client = HttpClients.custom().setSSLSocketFactory(sslSF).build();

            String method = "GET";
            String path = "/data/SPECIFY YOUR STATION ID/raw/last/5";
            // Creating date in appropriate format (RFC 1123) that is accepted by http header; apache http client library is used
            String date = DateUtils.formatDate(new Date(System.currentTimeMillis()));

            String contentToSign = method + path + date + publicKey;

            String signature = generateHmacSHA256Signature(contentToSign, privateKey);
            String authorizationString = "hmac " + publicKey + ":" + signature;

            // Creating request by using RequestBuilder from apache http client library; headers are set in this step as well
            HttpUriRequest request = RequestBuilder.get().setUri("https://api.fieldclimate.com/THIS-VERSION" + path)
            .setHeader(HttpHeaders.ACCEPT, "application/json")
            .setHeader(HttpHeaders.AUTHORIZATION, authorizationString)
            .setHeader(HttpHeaders.DATE, date).build();

            HttpResponse response = client.execute(request);
            HttpEntity entity = response.getEntity();
            System.out.println(response.getStatusLine());

            //EntityUtils.consume(entity);
            String responseString = EntityUtils.toString(entity, "UTF-8");
            System.out.println(responseString);
    }

    // Static method that generates HmacSHA256 signiture as a hexademical string
    public static String generateHmacSHA256Signature(String data, String key) throws GeneralSecurityException {
        byte[] hmacData = null;

        try
        {
            SecretKeySpec secretKey = new SecretKeySpec(key.getBytes("UTF-8"), "HmacSHA256");
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(secretKey);
            return Hex.encodeHexString(mac.doFinal(data.getBytes("UTF-8")));

        } catch (UnsupportedEncodingException e) {
            throw new GeneralSecurityException(e);
        }
    }
}
import requests
from requests.auth import AuthBase
from Crypto.Hash import HMAC
from Crypto.Hash import SHA256
from datetime import datetime,
from dateutil.tz import tzlocal


# Class to perform HMAC encoding
class AuthHmacMetosGet(AuthBase):
    # Creates HMAC authorization header for Metos REST service GET request.
    def __init__(self, apiRoute, publicKey, privateKey):
        self._publicKey = publicKey
        self._privateKey = privateKey
        self._method = 'GET'
        self._apiRoute = apiRoute

    def __call__(self, request):
        dateStamp = datetime.utcnow().strftime('%a, %d %b %Y %H:%M:%S GMT')
        print("timestamp: ", dateStamp)
        request.headers['Date'] = dateStamp
        msg = (self._method + self._apiRoute + dateStamp + self._publicKey).encode(encoding='utf-8')
        h = HMAC.new(self._privateKey.encode(encoding='utf-8'), msg, SHA256)
        signature = h.hexdigest()
        request.headers['Authorization'] = 'hmac ' + self._publicKey + ':' + signature
        return request


# Endpoint of the API, version for example: v1
apiURI = 'https://api.fieldclimate.com/ENTER-VERSION'

# HMAC Authentication credentials
publicKey = 'PROVIDED BY SERVICE PROVIDER'
privateKey = 'PROVIDED BY SERVICE PROVIDER'

# Service/Route that you wish to call
apiRoute = '/user'

auth = AuthHmacMetosGet(apiRoute, publicKey, privateKey)
response = requests.get(apiURI+apiRoute, headers={'Accept': 'application/json'}, auth=auth)
print(response.json())
Tested and working with following:
- Python 2.7
- Python 3.5

python-dateutil==2.7.2
pycrypto==2.6.1
requests==2.18.4
require 'net/http'
require 'digest/hmac'
require 'time'

# User public and private key
public_key = 'PROVIDED BY SERVICE PROVIDER';
private_key = 'PROVIDED BY SERVICE PROVIDER';

# Define the request parameters
method = 'GET';
call = '/data/{STATION-ID}/raw/last/5';
now = Time.now.httpdate # Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

# Concatenate the request into single string
content_to_sign = method + call + now + public_key

# Calc
ulate signature
signature = Digest::HMAC.hexdigest(content_to_sign, private_key, Digest::SHA256)

# Prepare and make http request
url = URI.parse('https://api.fieldclimate.com/THIS-VERSION' + call)
request = Net::HTTP::Get.new(url.to_s)

# Add required headers
request['Accept'] = 'application/json'

# Authorization: hmac public_key:signature
# Date: Wed, 25 Nov 2014 12:45:26 GMT
request['Authorization'] = 'hmac ' + public_key + ':' + signature
request['Date'] = now

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
response = http.request(request)

# Parse response as json and work on it
# ...
# ...

# output response
puts response.body
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Security.Cryptography;
using System.Text;
using System.Threading;
using System.Threading.Tasks;


namespace Demo.Metos.API
{
    internal class Program
    {
        /// 
        /// Just executes the async function and waits until ready
        /// 
        /// 
        private static void Main(string[] args)
        {
            RunAsync().Wait();
        }

        /// 
        /// The asynchronous function prepares the HTTP client hander, 
        /// calls the API and processes the response.
        /// 
        /// Task
        private static async Task RunAsync()
        {
            var httpHandler = new MetosHttpHandler(new HttpClientHandler());
            httpHandler.PublicKey = "ENTER YOUR public HMAC key";
            httpHandler.PrivateKey = "ENTER YOUR private HMAC key";
            var httpClient = new HttpClient(httpHandler) { BaseAddress = httpHandler.ApiUri };
            httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
            
            var response = await httpClient.GetAsync("/user/stations");
 
            Console.WriteLine("Status {0}:{1} \n", response.StatusCode, await response.Content.ReadAsStringAsync());
        }
    }

    /// 
    /// Custom HTTP handler with required setters
    /// 
    public class MetosHttpHandler : DelegatingHandler
    {
        private static readonly CultureInfo _enUsCulture = new CultureInfo("en-us");
        private static readonly Uri _apiBaseAddress = new Uri("https://api.fieldclimate.com/v1");

        /// 
        /// FieldClimate account: public HMAC key to access METOS station data and services 
        /// 
        public string PublicKey { get; set; }

        /// 
        /// FieldClimate account: private HMAC key to access METOS station data and services 
        /// 
        public string PrivateKey { get; set; }

        /// 
        /// Defaults to https://api.fieldclimate.com/v1
        /// 
        public Uri ApiUri { get; set; }

        /// 
        /// Default initialization
        /// 
        /// 
        public MetosHttpHandler(HttpMessageHandler handler)
        {
            base.InnerHandler = handler;
            ApiUri = _apiBaseAddress;
        }

        /// 
        /// Provides custom HTTP header modification
        /// 
        /// 
        /// 
        /// 
        protected override async Task SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
        {
            HttpResponseMessage response = null;

            // recover missing version part (e.g. /v1)
            var requestRoute = request.RequestUri.AbsolutePath;
            string combinedPath = ApiUri.AbsolutePath + requestRoute;
            request.RequestUri = new Uri(ApiUri, combinedPath);
            // adjust HTTP authorization header
            var requestHttpMethod = request.Method.Method;
            var date = DateTimeOffset.UtcNow;
            request.Headers.Date = date;
            var requestTimeStamp = date.ToString("ddd, dd MMM yyyy HH:mm:ss 'GMT'", _enUsCulture);
            var signatureRawData = $"{requestHttpMethod}{requestRoute}{requestTimeStamp}{PublicKey}";
            var privateKeyByteArray = Encoding.UTF8.GetBytes(PrivateKey);
            var signature = Encoding.UTF8.GetBytes(signatureRawData);
            using (var hmac = new HMACSHA256(privateKeyByteArray))
            {
                var signatureBytes = hmac.ComputeHash(signature);
                var requestSignatureString = ByteArrayToString(signatureBytes);
                request.Headers.Authorization = new AuthenticationHeaderValue("hmac",
                    $"{PublicKey}:{requestSignatureString}");
            }

            response = await base.SendAsync(request, cancellationToken);
            return response;
        }

        /// 
        /// Helper function to produce a hex string
        /// 
        /// 
        /// 
        private static string ByteArrayToString(IReadOnlyCollection ba)
        {
            var hex = new StringBuilder(ba.Count * 2);
            foreach (var b in ba)
                hex.AppendFormat("{0:x2}", b);
            return hex.ToString();
        }
    }
}
import 'dart:async';
import 'dart:convert';

import 'package:http/http.dart' as http;
import 'package:crypto/crypto.dart';
import 'package:intl/intl.dart';

void main() {
    String publicKey = "YOUR-PUBLIC-KEY";
    String privateKey = "YOUR-PRIVATE-KEY";
    String method = "GET";
    String path = "/user";
    var f = DateFormat('EEE, dd MMM yyyy HH:mm:ss');
    var date = "${f.format(DateTime.now().toUtc())} GMT";
    String contentToSign = '$method$path$date$publicKey';
    var key = utf8.encode(privateKey);
    var bytesG = utf8.encode(contentToSign);
    var hmacSha256 = Hmac(sha256, key);
    var digest = hmacSha256.convert(bytesG);
    var signature = digest;
 
    String authorizationString = "hmac $publicKey:$signature";
    fetchAlbum(authorizationString, date);
}

Future fetchAlbum(authorizationString, date) async {
  String collection;
  Map headers = {
    "Content-type": "application/json",
    "Accept": "application/json",
    "Authorization": authorizationString,
    "Request-Date": date
    };
  // CONNECT WITH USER ENDPOINT
  var request = await http.Request('GET',Uri.parse('https://api.fieldclimate.com/v2/user'));
  request.headers.addAll(headers);
 
  http.StreamedResponse streamedResponse = await request.send();
  var response = await http.Response.fromStream(streamedResponse);
  print(response.body);
}

OAuth 2.0

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 supersedes the work done on the original OAuth protocol created in 2006. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.
In this documentation we will not cover how to integrate into your language of choice as you need to refer to its documentation instead. We will cover when to decide for it and required specifications.

In the right pane you can find an example in PHP for authorization code grant workflow.

NOTE: Below you can find our OAuth 2.0 server specifications that you will require to make it work.

Useful Links

  1. Official OAuth2 standard
  2. Introductory tutorial
  3. A bit more extensive (and more useful) tutorial
  4. Library and commands

Benefit and Motivation

Applications build on top our oAuth 2.0 authentication server can make use of Pessl Instruments GmbH user base(PI). To do so you need to have a registered account in our user base which you consider to be administrator account of your application or applications. When such account exists you are able to create multiple oAuth 2.0 applications which are manageable.
When users come visit your application you do not need to store private data of a user (username, password ...), all is handled by our authorization server, oAuth 2.0 workflow are predefined and should be followed. Then after the authorization you are able to handle user data via API.

oAuth 2.0 structure

Access level structure

Your administrator account (PI user base) ----> Applications (oAuth 2.0 ID) <---> Users (PI user base)

To explain administrator account can have multiple manageable applications, each with their own user base. On the end administrator account is able to manage those applications, users in them and the data. But keep in mind this should be used only for management purposes and not as authentication of end users.
For that oAuth 2.0 workflow should be followed and users should authenticate them self.

Basic oAuth 2.0 Workflow

USER (of PI user base) ----> YOUR APPLICATION ----> OAUTH 2.0 AUTHENTICATION SERVER (of PI) <----> YOUR APPLICATION <----> API (of PI)

The workflow starts with the user visiting your application, it can be online, desktop or even mobile. Then after user wishes to authenticate himself in which case you contact our authorization server and follow oAuth 2.0 standard workflow. After the successful authorization you will receive a token for that particular user which you can use then after to make API requests related to him.

Advantages

  • Manage your applications
  • Manage application users
  • Manage application user stations
  • Access basic user information (not passwords)
  • Access user stations
  • Access user stations data
  • Disallow or allow access to other applications using same user base

Please check routes DEV for available options.

OAuth 2.0 Server specification

Service URL
OAuth 2.0 Server https://oauth.fieldclimate.com
OAuth 2.0 Authorize https://oauth.fieldclimate.com/authorize
OAuth 2.0 Token https://oauth.fieldclimate.com/token
Supported grants Authentication grant, Client credentials, Refresh token

Requesting oAuth 2.0

Contact api@metos.at with username of the account that will handle the application, application name and oauth 2.0 redirect url/s.

session_start();

//sample working client
$clientId = "PROVIDED BY SERVICE PROVIDER";
$clientSecret = "PROVIDED BY SERVICE PROVIDER";


// if token is already in session one can make api calls, by passing the access token value in the header
if (isset($_SESSION['access_token'])){
    echo "Access token is already in the session. Trying to make a sample API call (https://api.fieldclimate.com/station/00000146)... ";

    $accessToken = $_SESSION['access_token'];

    $sampleApiCall = "https://api.fieldclimate.com/THIS-VERSION/station/00000146";
    $curl = curl_init( $sampleApiCall );
    curl_setopt($curl, CURLOPT_HEADER, true);
    curl_setopt( $curl, CURLOPT_HTTPHEADER, array( 'Accept: application/json', 'Authorization: Bearer ' .$accessToken) );
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
    $redirect = curl_exec( $curl );
    $http_status_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);

    //optional step for automatic refreshing of tokens, since access token is expired in 1 hour (3600 seconds)
    //first we check if token is expired the refresh token is sent and exchanged for new access token
    if ($http_status_code == "401"){
        if (isset($_SESSION['refresh_token'])){
            $refreshToken = $_SESSION['refresh_token'];
            $postFields = array('grant_type' => 'refresh_token', 'refresh_token' => $refreshToken);

            $accessTokenUrl = "https://oauth.fieldclimate.com/token";
            $r = curl_init($accessTokenUrl);
            curl_setopt($r, CURLOPT_USERPWD, "{$clientId}:{$clientSecret}");
            curl_setopt($r, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($r, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($r, CURLOPT_POST, true);
            curl_setopt($r, CURLOPT_POSTFIELDS, $postFields);

            // Download the given URL, and return output
            $output = curl_exec($r);

            // Close the cURL resource, and free system resources
            curl_close($r);
        }else {
            print_r('something is wrong');
            die;
        }
    }
} else {
    //there is no access token in the session, user is redirected to the form
    //checking if there is an authorization code in the URL then client can exchange this authorization code for the token
    if ($_GET['code']){
        $accessTokenUrl = "https://oauth.fieldclimate.com/token";
        $authCode = $_GET['code'];

        $postFields = array('grant_type' => 'authorization_code', 'code' => $authCode);

        $r = curl_init($accessTokenUrl);
        curl_setopt($r, CURLOPT_USERPWD, "{$clientId}:{$clientSecret}");
        curl_setopt($r, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($r, CURLOPT_POST, true);
        curl_setopt($r, CURLOPT_POSTFIELDS, $postFields);

        // Download the given URL, and return output
        $output = curl_exec($r);

        // Close the cURL resource, and free system resources
        curl_close($r);

        $json = json_decode($output);

        $_SESSION['access_token'] = $json->access_token;
        $_SESSION['refresh_token'] = $json->refresh_token;
        echo "Refresh token: ". $json->refresh_token ." Access token was not set in the session, but now it is. Just reload the page and you should see the results from the sample api call.";
    } else {
        //there is not token or authorization code, so user should ask for authorization code first. For this client needs to pass these three
        //parameters to fieldclimate authorization server
        header("Location: https://oauth.fieldclimate.com/authorize?response_type=code&client_id=".$clientId. "&state=xyz");
    }
}

ROUTES - SYSTEM

System routes gives you all information you require to understand the system and what is supported.

Schemas

N/A

Routes

HTTP Method Endpoint URL Params Function
GET /system/status None System running correctly
GET /system/sensors None Supported sensors
GET /system/groups None Supported sensor groups
GET /system/group/sensors None Sensors organized in groups
GET /system/types None Type of devices
GET /system/countries None Countries for the languages
GET /system/timezones None Timezones
GET /system/diseases None Disease models

URL Parameters

N/A

System status:

GET /system/status

Checking system status.

Specifications

Specification Value
method GET
request /system/status

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
401 Unauthorized

Response values

Values are self explanatory.

{
    BOOLEAN
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/system/status";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

List of system sensors:

GET /system/sensors

Reading the list of all system sensors. Each sensor has unique sensor code and belongs to group with common specifications.

Specifications

Specification Value
method GET
request /system/sensors

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No sensors found
401 Unauthorized

Response values

Values that are not listed in table below are self explanatory.

Value Description
unit Default unit
units Supported units
group Check understanding your device section
code Check understanding your device section
aggr Check understanding your device section
vals Range of sensor reading
{
    "0": {
        "name": "Air temperature",
        "unit": "°C",
        "units": [
            "°C",
            "°F"
        ],
        "code": 0,
        "group": 1,
        "decimals": 1,
        "divider": 10,
        "vals": {
            "min": -400,
            "max": 900
        },
        "aggr": {
            "avg": 1,
            "max": 1,
            "min": 1
        }
    },
    "1": {
        "name": "Relative humidity",
        "unit": "%",
        "units": [
            "%"
        ],
        "code": 1,
        "group": 2,
        "decimals": 0,
        "divider": 1,
        "vals": {
            "min": 0,
            "max": 100
        },
        "aggr": {
            "avg": 1
        }
    },
    "2": {
        "name": "Solar radiation",
        "unit": "W/m2",
        "units": [
            "W/m2",
            "J/m2",
            "kJ/m2",
            "MJ/m2"
        ],
        "code": 2,
        "group": 4,
        "decimals": 0,
        "divider": 1,
        "vals": {
            "min": 0,
            "max": 32767
        },
        "aggr": {
            "avg": 1
        }
    },...
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/system/sensors";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

List of system sensor groups:

GET /system/groups

Reading the list of all system groups. Each sensor belongs to a group which indicates commons specifications.

Specifications

Specification Value
method GET
request /system/groups

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No groups found
401 Unauthorized

Response values

Values that are not listed in table below are self explanatory.

Value Description
name Name of the group
group Group code
{
    "1": {
        "name": "Air temperature",
        "group": 1
    },
    "2": {
        "name": "Relative humidity",
        "group": 2
    },
    "3": {
        "name": "Soil temperature",
        "group": 3
    },
    "4": {
        "name": "Solar radiation",
        "group": 4
    },
    "5": {
        "name": "Precipitation",
        "group": 5
    },...
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/system/groups";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

List of groups and sensors:

GET /system/group/sensors

Reading the list of all system groups and sensors belonging to them. Each sensor belongs to a group which indicates commons specifications.

Specifications

Specification Value
method GET
request /system/group/sensors

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No groups found
401 Unauthorized

Response values

All values explained in routes: system/sensors and system/groups

{
    "1": {
        "name": "Air temperature",
        "group": 1,
        "sensors": {
            "0": {
                "name": "Air temperature",
                "unit": "°C",
                "units": [
                    "°C",
                    "°F"
                ],
                "code": 0,
                "group": 1,
                "decimals": 1,
                "divider": 10,
                "vals": {
                    "min": -400,
                    "max": 900
                },
                "aggr": {
                    "avg": 1,
                    "max": 1,
                    "min": 1
                }
            },
            "51": {
                "name": "Si7021 Temperature",
                "unit": "°C",
                "units": [
                    "°C",
                    "°F"
                ],
                "code": 51,
                "group": 1,
                "decimals": 2,
                "divider": 100,
                "vals": {
                    "min": -4000,
                    "max": 12500
                },
                "aggr": {
                    "avg": 1,
                    "max": 1,
                    "min": 1
                }
            },...
    },
    "2": {
        "name": "Relative humidity",
        "group": 2,
        "sensors": {
            "1": {
                "name": "Relative humidity",
                "unit": "%",
                "units": [
                    "%"
                ],
                "code": 1,
                "group": 2,
                "decimals": 0,
                "divider": 1,
                "vals": {
                    "min": 0,
                    "max": 100
                },
                "aggr": {
                    "avg": 1
                }
            },
            "46": {
                "name": "Water meter 100L",
                "unit": false,
                "units": [
                    "%"
                ],
                "code": 46,
                "group": 2,
                "decimals": 0,
                "divider": 1,
                "vals": {
                    "min": 0,
                    "max": 4294967295
                },
                "aggr": {
                    "sum": 1
                }
            },...
    },...
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/system/group/sensors";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Type of devices:

GET /system/types

Reading the list of all devices system supports.

Specifications

Specification Value
method GET
request /system/types

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
401 Unauthorized

Response values

Values that are not listed in table below are self explanatory.

Value Description
index ID of a device
value Name of the device
{
    "0": "iMetos 1",
    "1": "iMetos 1",
    "2": "iMetos 2",
    "3": "iMetos SD",
    "4": "iMetos AOS",
    "5": "iMetos 3",
    "6": "iMetos D2",
    "7": "iMetos 3.3",
    "8": "iMetos Eco D3",
    "28": "iMetos ICA",
    "50": "uMetos",
    "70": "CropView"
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/system/types";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

System countries support:

GET /system/countries

Reading the list of all countries that system supports.

Specifications

Specification Value
method GET
request /system/countries

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No countries found
401 Unauthorized

Response values

Values are self explanatory.

[
    {
        "name": {
            "english": "Afghanistan",
            "native": ""
        },
        "phoneCode": "93",
        "iso": {
            "639-1": "AF",
            "639-2": "AFG"
        }
    },
    {
        "name": {
            "english": "Aland Islands",
            "native": ""
        },
        "phoneCode": "+358-18",
        "iso": {
            "639-1": "AX",
            "639-2": "ALA"
        }
    },
    {
        "name": {
            "english": "Albania",
            "native": ""
        },
        "phoneCode": "355",
        "iso": {
            "639-1": "AL",
            "639-2": "ALB"
        }
    },
    {
        "name": {
            "english": "Algeria",
            "native": ""
        },
        "phoneCode": "213",
        "iso": {
            "639-1": "DZ",
            "639-2": "DZA"
        }
    },...
]
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/system/countries";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

System timezones support:

GET /system/timezones

Reading the list of timezones system supports.

Specifications

Specification Value
method GET
request /system/timezones

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
401 Unauthorized

Response values

Values are self explanatory.

{
    "Pacific/Midway": {
        "Name": "Pacific, Midway",
        "GMT": "GMT-11:00",
        "Minutes": -660
    },
    "Pacific/Niue": {
        "Name": "Pacific, Niue",
        "GMT": "GMT-11:00",
        "Minutes": -660
    },
    "Pacific/Pago_Pago": {
        "Name": "Pacific, Pago Pago",
        "GMT": "GMT-11:00",
        "Minutes": -660
    },
    "Pacific/Honolulu": {
        "Name": "Pacific, Honolulu",
        "GMT": "GMT-10:00",
        "Minutes": -600
    },
    "Pacific/Johnston": {
        "Name": "Pacific, Johnston",
        "GMT": "GMT-10:00",
        "Minutes": -600
    },
    "Pacific/Rarotonga": {
        "Name": "Pacific, Rarotonga",
        "GMT": "GMT-10:00",
        "Minutes": -600
    },...
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/system/timezones";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

System diseases support:

GET /system/diseases

Reading the list of all disease models system currently supports.

Note that KEY returned with model itself is being used to fetch disease model data in requests data, disease, chart and ag-grid.

Specifications

Specification Value
method GET
request /system/diseases

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No disease models
401 Unauthorized

Response values

Values are self explanatory.

[
    {
        "group": "Apple",
        "models": [
            {
                "key": "GeneralAphidRisk",
                "name": "Aphid Risk",
                "version": "2.0",
                "settings": {
                    "period": "2d",
                    "resolution": "hourly"
                }
            },
            {
                "key": "GeneralRainModel4mm",
                "name": "Rain pesticide wash off",
                "version": "1.0",
                "settings": {
                    "period": "14d",
                    "resolution": "hourly"
                }
            },
            {
                "key": "GeneralFireblight",
                "name": "Fireblight",
                "version": "1.0",
                "settings": {
                    "period": "1m",
                    "resolution": "daily"
                }
            },...
        ],
        "title": "Apple",
        "active": true
    },
    {
        "group": "ApricotPlum",
        "models": [
            {
                "key": "GeneralAphidRisk",
                "name": "Aphid risk",
                "version": "2.0",
                "settings": {
                    "period": "2d",
                    "resolution": "hourly"
                }
            },
            {
                "key": "GeneralRainModel4mm",
                "name": "Rain pesticide wash off",
                "version": "1.0",
                "settings": {
                    "period": "14d",
                    "resolution": "daily"
                }
            },
            {
                "key": "GeneralJBlossomInfection",
                "name": "Xanthomonas arboricola infection",
                "version": "1.0",
                "settings": {
                    "period": "2d",
                    "resolution": "hourly"
                }
            },...
        ],
        "title": "Apricot, Plum, Prune and Mirabelle",
        "active": true
    },...
]
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/system/diseases";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

ROUTES - USER

User routes enables you to manage information regarding user you used to authenticate with.

Schemas

Schema Function
schemas/UserUpdate.json Updating user information

Routes

HTTP Method Endpoint URL Params Function
GET /user None Read user information
PUT /user None Update user information
DELETE /user None Delete user account
GET /user/stations None Read list of stations of a user
GET /user/licenses None Read user licenses

URL Parameters

N/A

User information:

GET /user

Reading user information.

Specifications

Specification Value
method GET
request /user

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 OK
401 Unauthorized

Response values

Values that are not listed in table below are self explanatory.

Value Description
created_by By which application user was created
unit_system Metric or Imperial
{
    "username": "",
    "info": {
        "name": "",
        "lastname": "",
        "title": "",
        "email": "",
        "phone": "",
        "cellphone": "",
        "fax": ""
    },
    "company": {
        "name": "",
        "profession": "",
        "department": ""
    },
    "address": {
        "street": "",
        "city": "",
        "district": "",
        "zip": "",
        "country": ""
    },
    "settings": {
        "language": "en",
        "newsletter": false,
        "unit_system": "metric"
    },
    "created_by": "",
    "create_time": "",
    "last_access": ""
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/user";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Update user information:

PUT /user

Updating user information.

Specifications

Specification Value
method PUT
request /user

URL Parameters

N/A

Body & Schema

Schema Function
schemas/UserUpdate.json Updating user information

Response

Response codes

HTTP CODE Description
200 Success
204 No changes have been made
400 Validation errors
401 Unauthorized
409 Username already exists

Response values

Values are self explanatory.

// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method  = "PUT";
$request = "/user";
// Body that you send needs to be JSON schema validated
$body    = [
  "username" => "dummyUsername",
  "info.name" => "Dummy Name"
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;
{
  "title": "User Update",
  "description" : "Update user information",
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "pattern": "(*UTF8)^[[:alnum:]]+(?:[-_ ]?[[:alnum:]]+)*$",
      "description": "Chars, Numbers, space, _, - but no other special chars"
    },
    "password": {
      "type": "string",
      "description": "Password"
    },
    "info.name": {
      "type": "string"
    },
    "info.lastname": {
      "type": "string"
    },
    "info.title": {
      "type": "string"
    },
    "info.email": {
      "type": "string"
    },
    "info.phone": {
      "type": "string"
    },
    "info.cellphone": {
      "type": "string"
    },
    "info.fax": {
      "type": "string"
    },
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "profession": {
          "type": "string"
        },
        "department": {
          "type": "string"
        },
        "customer_id": {
          "type": "integer"
        },
        "vat_id": {
          "type": "string"
        }
      },
      "required": [
        "name"
      ],
      "additionalProperties": false,
      "description": "Data updated as whole object will overwrite whole set in database"
    },
    "address.street": {
      "type": "string"
    },
    "address.city": {
      "type": "string"
    },
    "address.district": {
      "type": "string"
    },
    "address.zip": {
      "type": "string"
    },
    "address.country": {
      "type": "string"
    },
    "settings.language": {
      "type": "string",
      "pattern": "^[a-z]{2,2}$",
      "description": "Language has to be in ISO 639-1 format"
    },
    "settings.newsletter": {
      "type": "boolean",
      "description": "Wanna receive newsletter"
    },
    "settings.unit_system": {
      "type": "string",
      "enum": ["metric", "imperial"],
      "description": "Must be one of metric, imperial"
    }
  },
  "additionalProperties": false
}
{
    "username" :"",
    "password" : "",
    "info.name" : "",
    "info.lastname": "",
    "info.title": "",
    "info.email": "",
    "info.phone": "",
    "info.cellphone": "",
    "info.fax": "",
    "company": {
        "name": "",
        "profession": "",
        "department": "",
        "customer_id": "",
        "vat_id": ""
    },
    "address.street": "",
    "address.city": "",
    "address.district": "",
    "address.zip": "",
    "address.country": "",
    "settings.unit_system" : ""
    "settings.language": "",
    "settings.newsletter": "",
    "settings.unit_system": "",
}

Delete user account:

DELETE /user

User himself can remove his own account.

Specifications

Specification Value
method DELETE
request /user

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 Already removed
401 Unauthorized - Login required
403 No permissions - No rights

Response values

Values are self explanatory.

// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "DELETE";
$request = "/user";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

List of user devices:

GET /user/stations

Reading list of user devices. Returned value may not be used by your application.

Specifications

Specification Value
method GET
request /user/stations

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
401 Unauthorized

Response values

Values that are not listed in table below are self explanatory.

Most commonly used: name, info, dates, position, licenses

Value Description
name.original Station ID and can not be changed
warnings.sensors Warning per sensor code and channel
licenses.model Disease model licenses
licenses.forecast Weather forecast license
[
    {
        "name": {
            "original": "",
            "custom": ""
        },
        "rights": "rw",
        "info": {
            "device_id": 7,
            "device_name": "iMetos 3.3",
            "uid": "2401010657289D25",
            "firmware": "08.200.20170529",
            "hardware": "29-0503",
            "description": "iMetos 3.3, hw: 29-0503, fw: 08.200.20170529",
            "max_time": null
        },
        "dates": {
            "min_date": "2005-03-08 12:50:00",
            "max_date": "2017-07-05 12:30:09",
            "created_at": "2007-01-22 08:59:42",
            "last_communication": "2017-07-05 11:22:57"
        },
        "position": {
            "geo": {
                "coordinates": [
                    15.444533,
                    47.0648576
                ]
            },
            "altitude": 359
        },
        "config": {
            "timezone_offset": 60,
            "dst": false,
            "precision_reduction": 0.2,
            "scheduler": 1398096,
            "schedulerOld": "505515000000000000000000000000000000000000000000",
            "fixed_transfer_interval": 0,
            "rain_monitor": 0,
            "water_level_monitor": 0,
            "data_interval": 0,
            "activity_mode": 0,
            "emergency_sms_number": "+123124123123123",
            "measuring_interval": 10,
            "logging_interval": 15,
            "x_min_transfer_interval": false
        },
        "metadata": {
            "last_battery": "6009"
        },
        "networking": {
            "mnc": "",
            "mcc": "",
            "apn": "",
            "username": "",
            "password": "",
            "country": "",
            "provider": "",
            "type": "GPRS",
            "imei": "",
            "simid": ""
        },
        "warnings": {
            "sensors": [
                "0,16,0,0",
                "0,16,0,-15",
            ],
            "sms_numbers": [
                {
                    "num": "",
                    "name": "",
                    "active": true
                },
                {
                    "num": "",
                    "name": "",
                    "active": true
                }
            ]
        },
        "flags": {
            "imeteopro": true
        },
        "licenses": {
            "models": [
            ],
            "Forecast": true
        }
    },...
]
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/user/stations";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

List of user licenses:

GET /user/licenses

Reading all licenses that user has for each of his device.

Specifications

Specification Value
method GET
request /user/licenses

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No licenses
401 Unauthorized

Response values

Values are self explanatory.

{
    "models": {
        "CROP": {
            "STATION-ID": [
                {
                    "from": "DATE-TIME",
                    "to": "DATE-TIME"
                }
            ],
             "STATION-ID": [
               {
                   "from": "DATE-TIME",
                   "to": "DATE-TIME"
               }
            ],...
        },
        "CROP": {
            "STATION-ID": [
                {
                    "from": "DATE-TIME",
                    "to": "DATE-TIME"
                }
            ],
             "STATION-ID": [
               {
                   "from": "DATE-TIME",
                   "to": "DATE-TIME"
               }
            ],...
        },...
    },
    "Forecast": {
        "STATION-ID": [
            {
                "from": "DATE-TIME",
                "to": "DATE-TIME"
            }
        ],
        "STATION-ID": [
            {
                "from": "DATE-TIME",
                "to": "DATE-TIME"
            }
        ],...
    }
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/user/licenses";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
"Accept: application/json",
"Authorization: hmac {$public_key}:{$signature}",
"Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

ROUTES - STATION

All the information that is related to your device.

Schemas

Schema Function
schemas/NodeUpdate.json Updating station name or node
schemas/StationUpdate.json Updating station settings
schemas/UserStationInsert.json Adding station to account
schemas/StationSensorUpdate.json Updating specific sensor of a station
schemas/SensorSerialUpdate.json Updating sensor serial name

Routes

HTTP Method Endpoint URL Params Function
GET /station/{{STATION-ID}} STATION-ID Read station information
PUT /station/{{STATION-ID}} STATION-ID Update station information
GET /station/{{STATION-ID}}/sensors STATION-ID Get list of sensors of a station
PUT /station/{{STATION-ID}}/sensors STATION-ID Update station sensor name
GET /station/{{STATION-ID}}/nodes STATION-ID Get list of nodes (wireless devices) connected to a station
PUT /station/{{STATION-ID}}/nodes STATION-ID Update the name of a node itself
GET /station/{{STATION-ID}}/serials STATION-ID List of serials (of a sensor) and their names
PUT /station/{{STATION-ID}}/serials STATION-ID Update sensor with serial the name
POST /station/{{STATION-ID}}/{{STATION-KEY}} STATION-ID, STATION-KEY Add station to user account
DELETE /station/{{STATION-ID}}/{{STATION-KEY}} STATION-ID, STATION-KEY Remove station from user account
GET /station/{{STATION-ID}}/proximity/{{RADIUS}} STATION-ID, RADIUS Stations in close proximity of specified station
GET /station/{{STATION-ID}}/events/last/{{AMOUNT}}/{{SORT}} STATION-ID, AMOUNT, SORT Last station events
GET /station/{{STATION-ID}}/events/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}}/{{SORT}} STATION-ID, FROM-UNIX-TIMESTAMP, TO-UNIX-TIMESTAMP, SORT Station events from to
GET /station/{{STATION-ID}}/history/{{FILTER}}/last/{{AMOUNT}}/{{SORT}} STATION-ID, FILTER, AMOUNT, SORT Last station communication history filter
GET /station/{{STATION-ID}}/history/{{FILTER}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP }}/{{SORT}} STATION-ID, FILTER, FROM-UNIX-TIMESTAMP, TO-UNIX-TIMESTAMP, SORT Station communication history from to filter
GET /station/{{STATION-ID}}/licenses STATION-ID Station licenses for disease models or forecast

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
STATION-KEY Required Key 1, Key 2 Key 1 = RW, Key 2 = R and are supplied with a device
RADIUS Required Xm, Xkm Xm = miles, Xkm = Kilometers, X = Number
AMOUNT Required INTEGER Elements
FILTER Optional unknown, success, resync, registration, no_data, xml_error, fw_update, apn_update Filter out station history by its flag
SORT Optional asc, desc asc = ascended sort, desc = descended sort
FROM-UNIX-TIMESTAMP Required Unix timestamp Date/Time in unix timestamp
TO-UNIX-TIMESTAMP Required Unix timestamp Date/Time in unix timestamp

Station information:

GET /station/{{STATION-ID}}

Reading station information.

Specifications

Specification Value
method GET
request /station/{{STATION-ID}}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
400 Wrong parameters
401 Unauthorized
403 No permissions - No rights
500 Something went wrong server side, contact support with all required details

Response values

Values that are not listed in table below are self explanatory or not commonly used.

Value Description
name.original STATION-ID, unique identifier of a device
info.device_id Check System types, its unique ID of a device type
dates.min_date Data available from
dates.max_date Data available till
{
    "name": {
        "original": "STATION-ID",
        "custom": ""
    },
    "rights": "rw",
    "info": {
        "device_id": 7,
        "device_name": "iMetos 3.3",
        "uid": "2401010657289D25",
        "firmware": "08.200.20170529",
        "hardware": "29-0503",
        "description": "iMetos 3.3, hw: 29-0503, fw: 08.200.20170529",
        "max_time": null
    },
    "dates": {
        "min_date": "2012-01-01 00:00:00",
        "max_date": "2017-07-17 12:00:09",
        "created_at": "2007-01-22 08:59:42",
        "last_communication": "2017-07-17 10:10:41"
    },
    "position": {
        "geo": {
            "coordinates": [
                15.6353239,
                47.2056821
            ]
        },
        "altitude": 443
    },
    "config": {
        "timezone_offset": 60,
        "dst": false,
        "precision_reduction": 0.2,
        "scheduler": 1398096,
        "schedulerOld": "505515000000000000000000000000000000000000000000",
        "fixed_transfer_interval": 0,
        "rain_monitor": 0,
        "water_level_monitor": 0,
        "data_interval": 0,
        "activity_mode": 0,
        "emergency_sms_number": "NUMBER",
        "measuring_interval": 10,
        "logging_interval": 15,
        "x_min_transfer_interval": false
    },
    "metadata": {
        "last_battery": "6009"
    },
    "networking": {
        "mnc": "1",
        "mcc": "MCC",
        "apn": "APN",
        "username": "EMAIL",
        "password": "PASS",
        "country": "Austria",
        "provider": "PROVIDER",
        "type": "GPRS",
        "imei": "IMEI",
        "simid": "SIMID"
    },
    "warnings": {
        "sms_numbers": [
            {
                "num": "NUMBER",
                "name": "NAME",
                "active": true
            },...
        ],
        "sensors": [
            "0,16,0,0",
            "0,16,0,-15",...
        ]
    },
    "flags": {
        "imeteopro": true
    },
    "licenses": {
        "models": [
            "Apple",
            "ApricotPlum",
            "Viticulture",...
        ],
        "Forecast": true
    }
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/station/{{STATION-ID}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Update Station Information:

PUT /station/{{STATION-ID}}

Updating station information/settings.

Specifications

Specification Value
method PUT
request /station/{{STATION-ID}}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device

Body & Schema

Schema Function
schemas/StationUpdate.json Updating station information

Response

Response codes

HTTP CODE Description
200 Success
204 No changes have been made
400 Validation errors
401 Unauthorized
403 No permissions - No rights

Response values

Values are self explanatory.

// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method  = "PUT";
$request = "/station/{{STATION-ID}}";
// Body that you send needs to be JSON schema validated
$body    = [
    "name" => "New station name",
    "position" => [
        "geo" => [
            "coordinates" =>  [
                11.030232,
                45.480726
            ]
        ],
        "altitude" => 84
    ]
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
// in case of Update station you shoud use curl_setopt( $ch, CURLOPT_CUSTOMREQUEST, 'PUT' )  
// instead of curl_setopt( $ch, CURLOPT_POST, TRUE );
if ($method == 'PUT) {
    curl_setopt( $ch, CURLOPT_CUSTOMREQUEST, 'PUT' )
} else {
    curl_setopt( $ch, CURLOPT_POST, TRUE );
}

curl_setopt( $ch, CURLOPT_POSTFIELDS, $body );

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;
{
  "title": "Station Update",
  "description" : "Update station configuration",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "position": {
      "type": "object",
      "properties": {
        "geo": {
          "type": "object",
          "properties": {
            "coordinates": {
              "type": "array",
              "items": {
                "type": "number"
              },
              "minItems": 2,
              "maxItems": 2
            }
          },
          "required": [
            "coordinates"
          ]
        },
        "altitude": {
          "type": "number"
        },
        "timezoneCode": {
          "type": "string",
          "description": "Timezone code, has priority over timezone offset as it is more informative and can be used for DST auto-adjust"
        }
      },
      "required": [
        "geo",
        "altitude"
      ]
    },
    "config.timezone": {
      "type": "integer",
      "minimum": -720,
      "maximum": 840,
      "description": "Timezone in minutes. GMT + 1 = 60"
    },
    "config.precision_reduction": {
      "type": "number",
      "description": "Precision reduction (0.1, 0.2, 0.5, 1). Rain gauge resolution."
    },
    "config.activity_mode": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2,
      "description": "0 = Station is gathering and sending data, 1 = Station is gathering but not sending data, 2 = Station is not gathering and not sending data"
    },
    "config.monitor.water_level": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1,
      "description": "Water level monitoring 0 (Off), 1(On)"
    },
    "config.monitor.rain": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1,
      "description": "Rain monitoring 0 (Off), 1 (On)"
    },
    "config.interval.logging": {
      "type": "integer",
      "minimum": 15,
      "maximum": 120,
      "description": "Logging interval (Intervals  = 15,30,60,120 minutes). Used for data grouping and aggregations."
    },
    "config.interval.measurement": {
      "type": "object",
      "patternProperties": {
        "^[0-9]\\d*$": {
          "type": "integer",
          "minimum": 1,
          "maximum": 60
        }
      },
      "additionalProperties": false,
      "description": "Measurement interval (sampling) 5 min by default for all stations. Per chain measurement interval only for EcoD3 and Metos 3.3 stations ( intervals are 5, 15, 30, 60 minutes but need to be less then logging interval)."
    },
    "config.upload.scheduler": {
      "type": "string",
      "description": "Schedule transfer data to server. 24h schedule format = 100000000000000000000001 (0 = Not sending, 1 = Sending). Example is transferring data at 01:00 and 24:00."
    },
    "config.upload.transfer_fixed": {
      "type": "integer",
      "description": "Only for iMetos 3.3, iMetos Eco D3 and iMetos Eco D2 fixed transfer interval 15 min. 0 (Off) or 1 (On)."
    },
    "config.cam1.active": {
      "type": "integer",
      "description": "Only for CropVIEW stations - Camera On/Off switch (1/0)"
    },
    "config.cam2.active": {
      "type": "integer",
      "description": "Only for CropVIEW stations - Camera On/Off switch (1/0)"
    },
    "config.cam1.auto_exposure": {
      "type": "integer",
      "description": "Only for CropVIEW stations - Automatic/Manual exposure (1/0)"
    },
    "config.cam2.auto_exposure": {
      "type": "integer",
      "description": "Only for CropVIEW stations - - Automatic/Manual exposure (1/0)"
    },
    "config.cam1.brightness_ref": {
      "type": "integer",
      "description": "Only for CropVIEW stations - Brightness reference for automatic exposure (default: 750)"
    },
    "config.cam2.brightness_ref": {
      "type": "integer",
      "description": "Only for CropVIEW stations - Brightness reference for automatic exposure (default: 750)"
    },
    "config.cam1.global_gain": {
      "type": "integer",
      "description": "Only for CropVIEW stations - Global gain for manual exposure (default: 6208)"
    },
    "config.cam2.global_gain": {
      "type": "integer",
      "description": "Only for CropVIEW stations - Global gain for manual exposure (default: 6208)"
    },
    "config.cam1.integration_time": {
      "type": "integer",
      "description": "Only for CropVIEW stations - Integration time for manual exposure (default: 1000)"
    },
    "config.cam2.integration_time": {
      "type": "integer",
      "description": "Only for CropVIEW stations - Integration time for manual exposure (default: 1000)"
    },
    "config.cam1.max_integration_time": {
      "type": "integer",
      "description": "Only for CropVIEW stations - Maximal integration time for automatic exposure (default: 2300)"
    },
    "config.cam2.max_integration_time": {
      "type": "integer",
      "description": "Only for CropVIEW stations - Maximal integration time for automatic exposure (default: 2300)"
    },
    "config.cam1.square_spots": {
      "type": "integer",
      "description": "Only for CropVIEW stations - 8 bit converted to dec (8 bits = 8 measure points)"
    },
    "config.cam2.square_spots": {
      "type": "integer",
      "description": "Only for CropVIEW stations - 8 bit converted to dec (8 bits = 8 measure points)"
    },
    "warnings.sms_numbers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "num": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          }
        }
      },
      "description": "List of phone numbers that receive a text message upon warning alert (if a phone number is not active it will not receive the warning message)."
    },
    "warnings.sensors": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Warning sensors values: array of strings => 'sensor channel, sensor code, minmax(0/1), value'"
    }
  },
  "additionalProperties": false
}
{
  "name" : "",
  "position": {
    "geo": {
      "coordinates": [
		11.030232,
		45.480726
      ]
    },
    "altitude": 84
  },
  "config.timezone" : 120,
  "config.precision_reduction" : 0.2,
  "config.activity" : 0,
  "config.monitor.water_level" : 0,
  "config.monitor.rain" : 0,
  "config.interval.logging" : 60,
  "config.interval.measurement" : {
    "0": 5,
    "1" : 5,
    "2" : 5
  },
  "config.upload.scheduler" : "111111111111111111111111",
  "config.upload.transfer_fixed" : 0,
  "warnings.sensors" : [
	"1,143,0,5.6",
	"2,600,0,105.80",...
  ]
}

Station sensors:

GET /station/{{STATION-ID}}/sensors

Reading the list of all sensors that your device has/had.

Specifications

Specification Value
method GET
request /station/{{STATION-ID}}/sensors

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No sensors found
401 Unauthorized
403 No permissions - No rights

Response values

Values that are not listed in table below are self explanatory.

Value Description
unit Default unit
units Available units for specified sensor
ch On which channel on a board is sensor present
code Unique ID of a sensor
group Sensors with common specs/behavior belong to same group
mac Nodes connected to a main station are identified by MAC. X marks no serial and is base station.
serial Sensor with multiple outputs can be identify by using serial number. X marks no serial.
aggr Sensors send data to a server with specific aggregation or aggregations (min, max, avg, last, sum, time)
registered When sensor was registered by the system
isActive Currently active sensor, there may be old sensors that are not currently active
[
    {
        "name": "Wind direction",
        "name_custom": null,
        "color": "#1a1a1a",
        "decimals": 0,
        "divider": 1,
        "unit": "deg",
        "units": [
            "deg"
        ],
        "ch": 1,
        "code": 143,
        "group": 16,
        "mac": "X",
        "serial": "X",
        "vals": {
            "min": 0,
            "max": 360
        },
        "aggr": {
            "avg": 1,
            "last": 1
        },
        "registered": "2017-06-30 18:00:00",
        "isActive": true
    },
    {
        "name": "Solar radiation",
        "name_custom": null,
        "color": "#ffff99",
        "decimals": 0,
        "divider": 1,
        "unit": "W/m2",
        "units": [
            "W/m2",
            "J/m2",
            "kJ/m2",
            "MJ/m2"
        ],
        "ch": 2,
        "code": 600,
        "group": 4,
        "mac": "X",
        "serial": "X",
        "vals": {
            "min": 0,
            "max": 32767
        },
        "aggr": {
            "avg": 1
        },
        "registered": "2017-06-30 18:00:00",
        "isActive": true
    },
    {
        "name": "Solar Panel",
        "name_custom": null,
        "color": "#ff7f00",
        "decimals": 0,
        "divider": 1,
        "unit": "mV",
        "units": [
            "mV",
            "V"
        ],
        "ch": 4,
        "code": 30,
        "group": 7,
        "mac": "X",
        "serial": "X",
        "vals": {
            "min": 0,
            "max": 32767
        },
        "aggr": {
            "last": 1
        },
        "registered": "2017-06-30 18:00:00",
        "isActive": true
    },...
]
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/station/{{STATION-ID}}/sensors";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Station sensor update:

PUT /station/{{STATION-ID}}/sensors

Updating station sensor name, unit ...

Specifications

Specification Value
method PUT
request /station/{{STATION-ID}}/sensors

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device

Body & Schema

Schema Function
schemas/StationSensorUpdate.json Updating station information

Response

Response codes

HTTP CODE Description
200 Success
204 No changes have been made
400 Validation errors
401 Unauthorized
403 No permissions - No rights

Response values

Values are self explanatory.

// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method  = "PUT";
$request = "/station/{{STATION-ID}}/sensors";
// Body that you send needs to be JSON schema validated
$body    = [
    "name" => "New sensor name",
    "channel" => "SENSOR-CHANNEL",
    "code" => "SENSOR-CODE",
    "color" => "#000"
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt( $ch, CURLOPT_POST, TRUE );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $body );

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;
{
  "title": "Station sensor update",
  "description" : "Update specific sensor of a station",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "channel": {
      "type": "integer"
    },
    "code": {
      "type": "integer"
    },
    "color": {
      "type": "string",
      "description": "Format has to be in HEX"
    },
    "unit": {
      "type": "string"
    }
  },
  "required": [
    "channel",
    "code",
    "unit",
    "color"
  ],
  "additionalProperties": false
}
{
    "name"  : "New sensor name",
    "channel" : "SENSOR-CHANNEL",
    "code" : "SENSOR-CODE",
    "color" : "#000"
}

Station nodes:

GET /station/{{STATION-ID}}/nodes

Station nodes are wireless nodes connected to base station (STATION-ID). Here you can list custom names if any of a node has custom name.
To get list of nodes we suggest using call /station/{{STATION-ID}}/sensors and each sensor has MAC address.

Specifications

Specification Value
method GET
request /station/{{STATION-ID}}/nodes

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No nodes settings
401 Unauthorized
403 No permissions - No rights

Response values

Values that are not listed in table below are self explanatory or not commonly used.

Value Description
name Custom name of a node or base station
{
    "NODE-MAC": {
        "name": "Each node that is not base station (STATION-ID) has MAC address"
    },
    "X": {
        "name": "Base station MAC address is X (STATION-ID)"
    }
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/station/{{STATION-ID}}/nodes";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Change node name:

PUT /station/{{STATION-ID}}/nodes

Updating station sensor name, unit ...

Specifications

Specification Value
method PUT
request /station/{{STATION-ID}}/nodes

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device

Body & Schema

Schema Function
schemas/NodeUpdate.json Updating the node

Response

Response codes

HTTP CODE Description
200 Success
204 No changes have been made
400 Validation errors
401 Unauthorized
403 No permissions - No rights

Response values

Values are self explanatory.

// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method  = "PUT";
$request = "/station/{{STATION-ID}}/nodes";
// Body that you send needs to be JSON schema validated
$body    = [
    "name" => "New node name",
    "mac" => "MAC-ADDRESS-OF-A-NODE"
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt( $ch, CURLOPT_POST, TRUE );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $body );

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;
{
  "title": "Node update",
  "description": "Update the name of a node. Node is wireless device connected to base station.",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "mac": {
      "type": "string",
      "description": "MAC address or Station ID as X (X indicates default station)"
    }
  },
  "required": [
    "name",
    "mac"
  ],
  "additionalProperties": false
}
{
    "name" : "New node name",
    "mac"  : "MAC-ADDRESS-OF-A-NODE"
}

Station serials:

GET /station/{{STATION-ID}}/serials

Sensor serials settings. If there are no settings we get no content response.
To get list of all sensors serials we suggest using call /station/{{STATION-ID}}/sensors where each sensor has serial tag.
Serial is normally used by drill and drop sensors where we get for one sensor 6 or more sensor outputs as drill and drop
contains multiple sensors at specific depth. To identify this sensor as a whole we introduced serial.

Specifications

Specification Value
method GET
request /station/{{STATION-ID}}/serials

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No serials settings
401 Unauthorized
403 No permissions - No rights

Response values

Values that are not listed in table below are self explanatory or not commonly used.

Value Description
name Custom name of a serial of a sensor
{
    "SERIAL": {
        "name": "SERIAL-NAME"
    },...
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/station/{{STATION-ID}}/serials";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Change serial name:

PUT /station/{{STATION-ID}}/serials

Updating sensor serial information.

Specifications

Specification Value
method PUT
request /station/{{STATION-ID}}/serials

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device

Body & Schema

Schema Function
schemas/SensorSerialUpdate.json Updating sensor serial

Response

Response codes

HTTP CODE Description
200 Success
204 No changes have been made
400 Validation errors
401 Unauthorized
403 No permissions - No rights

Response values

Values are self explanatory.

// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method  = "PUT";
$request = "/station/{{STATION-ID}}/serials";
// Body that you send needs to be JSON schema validated
$body    = [
    "name" => "New serial name",
    "serial" => "SENSOR-SERIAL"
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt( $ch, CURLOPT_POST, TRUE );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $body );

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;
{
  "title": "Sensor serial update",
  "description" : "Update sensor serial",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "serial": {
      "type": "string",
      "description": "If there is none put X"
    }
  },
  "required": [
    "name",
    "serial"
  ],
  "additionalProperties": false
}
{
 "name": "New serial name",
 "serial" : "SENSOR-SERIAL"
}

Add station to account:

POST /station/{{STATION-ID}}/{{STATION-KEY}}

Adding station to user account. Key 1 and Key 2 are supplied with device itself.
If you add station with key 1 then that user has RW permissions for that station (configuration ... ) else with key 1 only read permissions.

RIGHTS:
Key 1: RW
key 2: R

Specifications

Specification Value
method POST
request /station/{{STATION-ID}}/{{STATION-KEY}}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
STATION-KEY Required STRING Unique key 1 or 2 of a device

Body & Schema

Schema Function
schemas/UserStationInsert.json Adding station to user account

Response

Response codes

HTTP CODE Description
200 Success
204 User already has this station
400 Validation errors
401 Unauthorized
403 No permissions - No rights

Response values

Values are self explanatory.

// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method  = "POST";
$request = "/station/{{STATION-ID}}/{{STATION-KEY}}";
// Body that you send needs to be JSON schema validated
$body    = [
    "name" => "Custom station name"
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt( $ch, CURLOPT_POST, TRUE );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $body );

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;
{
  "title": "User station insert",
  "description" : "Add a station to an user",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-zA-Z\\s\\d]{0,35}$",
      "description": "Only characters, numbers, spaces and max length 35"
    }
  },
  "additionalProperties": false
}
{
    "name" : "Custom name of a station"
}

Remove station from account:

DELETE /station/{{STATION-ID}}/{{STATION-KEY}}

Removing station from current account. The keys come with device itself.

If station has been added with Key 1, key 1 has to be used to remove it.
If station has been added with Key 2, key 1 or key 2 has to be used to remove it.

Specifications

Specification Value
method DELETE
request /station/{{STATION-ID}}/{{STATION-KEY}}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
STATION-KEY Required STRING Unique key 1 or 2 of a device

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 Nothing to be removed
401 Unauthorized - Login required
403 No permissions - No rights or incorrect key

Response values

Values are self explanatory.

// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "DELETE";
$request = "/station/{{STATION-ID}}/{{STATION-KEY}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Stations in proximity:

GET /station/{{STATION-ID}}/proximity/{{RADIUS}}

Find stations in proximity of specified station.

Specifications

Specification Value
method GET
request /station/{{STATION-ID}}/proximity/{{RADIUS}}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
RADIUS Required Xm, Xkm Xm = miles, Xkm = Kilometers, X = Number

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No stations found in proximity
400 Validation error
401 Unauthorized
403 No permissions - No rights

Response values

Values are self explanatory.

{
    "STATION-ID": {
        "Longitude": Longitude,
        "Latitude": latitude
    },
    "STATION-ID": {
        "Longitude": Longitude,
        "Latitude": latitude
    },
    "STATION-ID": {
        "Longitude": Longitude,
        "Latitude": latitude
    },...
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/station/{{STATION-ID}}/proximity/{{RADIUS}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Station last events:

GET /station/{{STATION-ID}}/events/last/{{AMOUNT}}/{{SORT}}

Read last X amount of station events. Optionally you can also sort them ASC or DESC.

Specifications

Specification Value
method GET
request /station/{{STATION-ID}}/events/last/{{AMOUNT}}/{{SORT}}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
AMOUNT Required INTEGER Elements
SORT Optional asc, desc asc = ascended sort, desc = descended sorts

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No events found
401 Unauthorized
403 No permissions - No rights
500 System can not read event code

Response values

Values are self explanatory.

[
    {
        "dateTime": "2016-10-09 11:01:22",
        "code": 12,
        "keyword": "SYSEVENT_CODE_SYSTEM_RESET_EXT",
        "description": "External reset\n"
    },
    {
        "dateTime": "2016-10-10 06:31:21",
        "code": 12,
        "keyword": "SYSEVENT_CODE_SYSTEM_RESET_EXT",
        "description": "External reset\n"
    },
    {
        "dateTime": "2016-10-11 07:06:31",
        "code": 12,
        "keyword": "SYSEVENT_CODE_SYSTEM_RESET_EXT",
        "description": "External reset\n"
    },
    {
        "dateTime": "2016-10-11 07:36:30",
        "code": 12,
        "keyword": "SYSEVENT_CODE_SYSTEM_RESET_EXT",
        "description": "External reset\n"
    },
    {
        "dateTime": "2016-10-20 05:01:22",
        "code": 12,
        "keyword": "SYSEVENT_CODE_SYSTEM_RESET_EXT",
        "description": "External reset\n"
    }
]
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/station/{{STATION-ID}}/events/last/{{AMOUNT}}/{{SORT}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Station events between:

GET /station/{{STATION-ID}}/events/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}}/{{SORT}}

Read station events between time period you select. Optionally you can also sort them ASC or DESC.

Specifications

Specification Value
method GET
request /station/{{STATION-ID}}/events/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}}/{{SORT}}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
FROM-UNIX-TIMESTAMP Required Unix timestamp Date/Time in unix timestamp
TO-UNIX-TIMESTAMP Required Unix timestamp Date/Time in unix timestamp
SORT Optional asc, desc asc = ascended sort, desc = descended sorts

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No events found
401 Unauthorized
403 No permissions - No rights
500 System can not read event code

Response values

Values are self explanatory.

[
    {
        "dateTime": "2016-10-09 11:01:22",
        "code": 12,
        "keyword": "SYSEVENT_CODE_SYSTEM_RESET_EXT",
        "description": "External reset\n"
    },
    {
        "dateTime": "2016-10-10 06:31:21",
        "code": 12,
        "keyword": "SYSEVENT_CODE_SYSTEM_RESET_EXT",
        "description": "External reset\n"
    },
    {
        "dateTime": "2016-10-11 07:06:31",
        "code": 12,
        "keyword": "SYSEVENT_CODE_SYSTEM_RESET_EXT",
        "description": "External reset\n"
    },
    {
        "dateTime": "2016-10-11 07:36:30",
        "code": 12,
        "keyword": "SYSEVENT_CODE_SYSTEM_RESET_EXT",
        "description": "External reset\n"
    },
    {
        "dateTime": "2016-10-20 05:01:22",
        "code": 12,
        "keyword": "SYSEVENT_CODE_SYSTEM_RESET_EXT",
        "description": "External reset\n"
    }
]
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/station/{{STATION-ID}}/events/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}}/{{SORT}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Station transmission history last:

GET /station/{{STATION-ID}}/history/{{FILTER}}/last/{{AMOUNT}}/{{SORT}}

Read last X amount of station transmission history. Optionally you can also sort them ASC or DESC and filter.

Specifications

Specification Value
method GET
request /station/{{STATION-ID}}/history/{{FILTER}}/last/{{AMOUNT}}/{{SORT}}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
FILTER Optional unknown, success, resync, registration, no_data, xml_error, fw_update, apn_update Filter out station history by its flag
AMOUNT Required INTEGER Elements
SORT Optional asc, desc asc = ascended sort, desc = descended sort

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No communication history
401 Unauthorized
403 No permissions - No rights

Response values

Values are self explanatory.

[
    {
        "dateTime": "2016-10-26 11:02:00",
        "xml_s": 6975,
        "http_s": 7355,
        "ip": "IP-ADDRESS",
        "flags": [
            "no_data",
            "resync"
        ],
        "df_st": "2016-10-25 20:50:00",
        "df_end": "2016-10-26 14:00:00"
    },
    {
        "dateTime": "2016-10-26 10:01:46",
        "xml_s": 6973,
        "http_s": 7353,
        "ip": "IP-ADDRESS",
        "flags": [
            "no_data",
            "resync"
        ],
        "df_st": "2016-10-25 19:50:00",
        "df_end": "2016-10-26 13:00:00"
    },...
]
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/station/{{STATION-ID}}/history/{{FILTER}}/last/{{AMOUNT}}/{{SORT}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;
s
// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Station transmission history between:

GET /station/{{STATION-ID}}/history/{{FILTER}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}}/{{SORT}}

Read transmission history for specific time period. Optionally you can also sort them ASC or DESC and filter.

Specifications

Specification Value
method GET
request /station/{{STATION-ID}}/history/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}}/{{SORT}}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
FILTER Optional unknown, success, resync, registration, no_data, xml_error, fw_update, apn_update Filter out station history by its flag
FROM-UNIX-TIMESTAMP Required Unix timestamp Date/Time in unix timestamp
TO-UNIX-TIMESTAMP Required Unix timestamp Date/Time in unix timestamp
SORT Optional asc, desc asc = ascended sort, desc = descended sort

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No communication history
401 Unauthorized
403 No permissions - No rights

Response values

Values are self explanatory.

[
    {
        "dateTime": "2016-10-26 09:01:51",
        "xml_s": 6983,
        "http_s": 7363,
        "ip": "IP-ADDRESS",
        "flags": [
            "success"
        ],
        "df_st": "2016-10-25 18:50:00",
        "df_end": "2016-10-26 12:00:00"
    },
    {
        "dateTime": "2016-10-26 08:02:11",
        "xml_s": 6985,
        "http_s": 7365,
        "ip": "IP-ADDRESS",
        "flags": [
            "success"
        ],
        "df_st": "2016-10-25 17:50:00",
        "df_end": "2016-10-26 11:00:00"
    },
    {
        "dateTime": "2016-10-26 07:01:55",
        "xml_s": 6993,
        "http_s": 7373,
        "ip": "IP-ADDRESS",
        "flags": [
            "success"
        ],
        "df_st": "2016-10-25 16:50:00",
        "df_end": "2016-10-26 10:00:00"
    },
    {
        "dateTime": "2016-10-26 05:21:40",
        "xml_s": 5947,
        "http_s": 6327,
        "ip": "IP-ADDRESS",
        "flags": [
            "success"
        ],
        "df_st": "2016-10-25 15:10:00",
        "df_end": "2016-10-26 08:20:00"
    },...
]
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/station/{{STATION-ID}}/history/{{FILTER}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}}/{{SORT}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;
s
// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Station licenses:

GET /station/{{STATION-ID}}/licenses

Retrieve all the licenses of your device. They are separated by the service (models, forecast ...).

Specifications

Specification Value
method GET
request /station/{{STATION-ID}}/licenses

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No licenses
401 Unauthorized
403 No permissions - No rights

Response values

Values are self explanatory.

{
    "models": {
        "Apple": [
            {
                "from": "2010-01-01 00:00:00",
                "to": "2020-01-01 00:00:00"
            }
        ],
        "ApricotPlum": [
            {
                "from": "2010-01-01 00:00:00",
                "to": "2020-01-01 00:00:00"
            }
        ],
        "Viticulture": [
            {
                "from": "2010-01-01 00:00:00",
                "to": "2020-01-01 00:00:00"
            }
        ],...
    },
    "Forecast": [
        {
            "from": "2010-01-01 00:00:00",
            "to": "2020-01-01 00:00:00"
        }
    ]
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/station/{{STATION-ID}}/licenses";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

ROUTES - TRACKERS

All routes related with trackers.
TrackerID AKA StationID

Schemas

Schema Function
schemas/TripsModel.json Update or insert trip

Routes

HTTP Method Endpoint URL Params Function
GET /tracker/{{TrackerID}}/trips/from/{{From}}/to/{{To}} TRACKERID , TIMESTAMPFROM, TIMESTAMPTO Responsible for make trips on the fly based in the Station ID and a start and end timestamp

URL Parameters

Value Optional/Required Options Description
TRACKER-*ID Required STRING Unique identifier of a device
FROM-UNIX-TIMESTAMP Required Unix timestamp Date/Time in unix timestamp
TO-UNIX-TIMESTAMP Required Unix timestamp Date/Time in unix timestamp

Station nodes:

GET /station/{{STATION-ID}}/nodes

Station nodes are wireless nodes connected to base station (STATION-ID). Here you can list custom names if any of a node has custom name.
To get list of nodes we suggest using call /station/{{STATION-ID}}/sensors and each sensor has MAC address.

Specifications

Specification Value
method GET
request /station/{{STATION-ID}}/nodes

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No nodes settings
401 Unauthorized
403 No permissions - No rights

Response values

Values that are not listed in table below are self explanatory or not commonly used.

Value Description
name Custom name of a node or base station
{
    "NODE-MAC": {
        "name": "Each node that is not base station (STATION-ID) has MAC address"
    },
    "X": {
        "name": "Base station MAC address is X (STATION-ID)"
    }
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/station/{{STATION-ID}}/nodes";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

ROUTES - DATA

Retrieving your measured and calculated historic data.

You are limited to retrieve MAX 10.000 data points.

Advanced VIEW options are available for customized data retrieval (see VIEW examples).

Schemas

Returning JSON schema is similar for all /data calls, no matter if it was initiated via GET or POST requests.
The two resulting root elements are:

{
"dates": ...
"data": ...
}
  • "dates" lists all the dates and times for requested data.

  • "data" contains all measured and requested calculated data.The data is listed in the same chronological order as the dates/times. So, for example, the first data listed
    (for each category) was measured at the first listed date and time.

  • Daily ET0 is delivered within GET response if required sensors are present.

Schema Function
schemas/View.json Select your view

Routes

HTTP Method Endpoint URL Params Function
GET /data/{{STATION-ID}} STATION-ID Min and Max date of data availability
GET /data/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}} FORMAT, STATION-ID, DATA-GROUP, TIME-PERIOD Reading last data
GET /data/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}} FORMAT, STATION-ID, DATA-GROUP, FROM-UNIX-TIMESTAMP, TO-UNIX-TIMESTAMP Reading data of specific time period
POST /chart/{{STATION-ID}}/{{DATA-GROUP}} TYPE, STATION-ID, DATA-GROUP Works only for forecast VIEWs
POST /data/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}} FORMAT, STATION-ID, DATA-GROUP, TIME-PERIOD Select your VIEW
POST /data/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}} FORMAT, STATION-ID, DATA-GROUP, FROM-UNIX-TIMESTAMP, TO-UNIX-TIMESTAMP Select your VIEW

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
DATA-GROUP Required raw, hourly, daily, monthly Device data grouped
TIME-PERIOD Required Xh, Xd, Xw, Xm, X X = Number, h = hours, d = days, w = weeks, m = months
FROM-UNIX-TIMESTAMP Required Unix timestamp Date/Time in unix timestamp
TO-UNIX-TIMESTAMP Optional Unix timestamp Date/Time in unix timestamp, if not specified data will be taken till last available
# 1. Filter data 5 - Wind speed, 4 - Leaf Wetness, 506 - Air temperature, 507 - Relative humidity
# 2. Data comes in imperial units
{
  "sensors": {
    "filter": {
      "sensor-5": true,
      "sensor-4": true,
      "sensor-506": true,
      "sensor-507": true
    }
  },
  "data": {
     "unit_system": "imperial"
  }
}
{
  "properties": {
    "description": "Pre-defined, combined or custom name",
    "name": {
      "type": "string"
    },
    "sensors": {
      "properties": {
        "filter": {
          "description": "Filter by group, sensor, mac or serial and optionally specify aggregation",
          "properties": {
            "group-7": {
              "items": {
                "type": "string"
              },
              "type": "array",
              "enum": [
                "avg",
                "min",
                "max",
                "sum",
                "time",
                "last",
                "user"
              ]
            },
            "mac-MAC_ADDRESS": {
              "type": "boolean"
            },
            "sensor-506": {
              "items": {
                "type": "string"
              },
              "type": "array",
              "enum": [
                "avg",
                "min",
                "max",
                "sum",
                "time",
                "last",
                "user"
              ]
            },
            "serial-SERIAL": {
              "type": "boolean"
            }
          },
          "type": "object"
        },
        "settings": {
          "description": "Configure sensor output",
          "properties": {
            "group-7": {
               "unit": "Custom unit",
               "type": "string"
            },
            "sensor-506": {
               "unit": "Custom unit",
               "type": "string"
            }
          },
          "type": "object"
        }
      },
      "type": "object"
    },
    "data": {
      "properties": {
        "model": {
          "description": "Disease model name",
          "type": "string"
        },
        "sunrise_sunset": {
          "description": "Get sunrise and sunset dates for specified period",
          "type": "boolean"
        },
        "unit_system": {
          "type": "string",
          "description": "One of",
          "enum": [
            "imperial",
            "metric"
          ]
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
{
  # VIEW NAME: Pre-Defined, Combined, Custom
  "name": "PRE-DEFINED, COMBINED OR CUSTOM ... NAME,
  "sensors": {
    "filter": {
      # Filter out specific sensor
      "sensor-506": 1,
      # Filter out specific sensor and its aggregation
      "sensor-506": [
        "avg"
      ],
      # Filter out specific sensors of a group
      "group-7": 1,
      # Filter out specific sensors of a group and its aggragation
      "group-7": [
        "avg"
      ],
      # Filter out sensors on MAC
      "mac-MAC_ADDRESS": true,
      # Filter out sensors with Serial
      "serial-SERIAL": true
    },
    "settings" : {
       # Configure output of a sensor, by changing the unit manually
       "sensor-506": [
            "unit" : "sec"
       ],
       # Configure output of a sensor group, by changing the unit manually
       "group-7": [
            "unit" : "sec"
       ]
    }
  },
  "data": {
    # UNIT SYSTEM: matric, imperial
    "unit_system": "imperial",
    # Sunrise and sunset dates
    "sunrise_sunset" : true,
    # DISEASE MODEL DATA
    "model": "DISEASE-MODEL"
  }
}

Min, Max date/time of data:

GET /data/{{STATION-ID}}

Retrieve min and max date of device data availability. This request can be used to check if device has sent new data which you
can retrieve, by just memorizing last max_date and compare it with current one.

Specifications

Specification Value
method GET
request /data/{{STATION-ID}}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 OK
401 Unauthorized
403 Forbidden - CropView type of stations do not support this call

Response values

Values are self explanatory.

{
    "min_date": "2012-01-01 00:00:00",
    "max_date": "2017-07-21 06:00:10"
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/data/{{STATION-ID}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Get last data

GET /data/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}}

Retrieve last data that device sends. We recommend calling /data/{{STATION-ID}} first so you can see if
there is any new data.

NOTE that time period gives you flexibility:

  • Read only X amount of elements
  • Read Xh which means X amount of hours
  • Read Xd which means X amount of days
  • Read Xw which means X amount of weeks
  • Read Xm which means X amount of months

You are limited to retrieve MAX 10.000 data points.

Specifications

Specification Value
method GET
request /data/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
DATA-GROUP Required raw, hourly, daily, monthly Device data grouped
TIME-PERIOD Required Xh, Xd, Xw, Xm, X X = Number, h = hours, d = days, w = weeks, m = months

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 OK
400 Data over limit
401 Unauthorized
403 No permissions - No rights
406 Specified params are not acceptable

Response values

Values are self explanatory.

# NORMAL
# Data and sensors come separated and can be connected using unique TAG
# Dates and data are on the same level
# 1_X_X_143_avg tag is = CH_MAC_SERIAL_CODE_AGGREGATION
{
    "sensors": [
        {
            "name": "Wind direction",
            "name_custom": false,
            "decimals": 0,
            "unit": "deg",
            "ch": 1,
            "chain": 1,
            "code": 143,
            "group": 16,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 360
            },
            "aggr": {
                "avg": 1,
                "last": 1
            },
            "registered": "2017-06-30 18:00:00"
        },
        {
            "name": "Solar radiation",
            "name_custom": false,
            "decimals": 0,
            "unit": "W/m2",
            "ch": 2,
            "chain": 1,
            "code": 600,
            "group": 4,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 32767
            },
            "aggr": {
                "avg": 1
            },
            "registered": "2017-06-30 18:00:00"
        },..
    ],
    "data": [
        {
            "date": "2017-07-21 05:00:00",
            "1_X_X_143_avg": 39,
            "1_X_X_143_last": 39,
            "2_X_X_600_avg": 0,
            "4_X_X_30_last": 0,...
        },
        {
            "date": "2017-07-21 05:15:00",
            "1_X_X_143_avg": 117,
            "1_X_X_143_last": 117,
            "2_X_X_600_avg": 0,
            "4_X_X_30_last": 0,...
        },...
    ]
}
# OPTIMIZED - Recommended
# Data can come in several aggravations inside the sensor information AGGR
# Dates come separated from the data but are in the same order
# All other information is sensor related information
# We recommend this format because of its simplicity and output size is smaller then normal one
# 1_X_X_143 tag is = CH_MAC_SERIAL_CODE
{
    "dates": [
        "2017-07-21 05:00:00",
        "2017-07-21 05:15:00",
        "2017-07-21 05:30:00",
        "2017-07-21 05:45:00",
        "2017-07-21 06:00:00"
    ],
    "data": {
        "1_X_X_143": {
            "name": "Wind direction",
            "name_custom": false,
            "decimals": 0,
            "unit": "deg",
            "ch": 1,
            "code": 143,
            "group": 16,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 360
            },
            "aggr": {
                "avg": [
                    39,
                    117,
                    85,
                    74,
                    74
                ],
                "last": [
                    39,
                    117,
                    85,
                    74,
                    74
                ]
            },
            "registered": "2017-06-30 18:00:00"
        },
        "2_X_X_600": {
            "name": "Solar radiation",
            "name_custom": false,
            "decimals": 0,
            "unit": "W/m2",
            "ch": 2,
            "code": 600,
            "group": 4,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 32767
            },
            "aggr": {
                "avg": [
                    0,
                    0,
                    0,
                    0,
                    0
                ]
            },
            "registered": "2017-06-30 18:00:00"
        },...
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/data/{{FORMAT}}/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Get data between period

GET /data/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP }}

Retrieve data between specified time periods. We recommend calling /data/{{STATION-ID}} first so you can see if
there is any new data. Times from and to need to be specified in unix timestamp.

You are limited to retrieve MAX 10.000 data points.

Specifications

Specification Value
method GET
request /data/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP }}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
DATA-GROUP Required raw, hourly, daily, monthly Device data grouped
FROM-UNIX-TIMESTAMP Required Unix timestamp Date/Time in unix timestamp
TO-UNIX-TIMESTAMP Optional Unix timestamp Date/Time in unix timestamp, if not specified data will be taken till last available

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 OK
400 Data over limit
401 Unauthorized
403 No permissions - No rights
406 Specified params are not acceptable

Response values

Values are self explanatory.

# NORMAL
# Data and sensors come separated and can be connected using unique TAG
# Dates and data are on the same level
# 1_X_X_143_avg tag is = CH_MAC_SERIAL_CODE_AGGREGATION
{
    "sensors": [
        {
            "name": "Wind direction",
            "name_custom": false,
            "decimals": 0,
            "unit": "deg",
            "ch": 1,
            "chain": 1,
            "code": 143,
            "group": 16,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 360
            },
            "aggr": {
                "avg": 1,
                "last": 1
            },
            "registered": "2017-06-30 18:00:00"
        },
        {
            "name": "Solar radiation",
            "name_custom": false,
            "decimals": 0,
            "unit": "W/m2",
            "ch": 2,
            "chain": 1,
            "code": 600,
            "group": 4,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 32767
            },
            "aggr": {
                "avg": 1
            },
            "registered": "2017-06-30 18:00:00"
        },..
    ],
    "data": [
        {
            "date": "2017-07-21 05:00:00",
            "1_X_X_143_avg": 39,
            "1_X_X_143_last": 39,
            "2_X_X_600_avg": 0,
            "4_X_X_30_last": 0,...
        },
        {
            "date": "2017-07-21 05:15:00",
            "1_X_X_143_avg": 117,
            "1_X_X_143_last": 117,
            "2_X_X_600_avg": 0,
            "4_X_X_30_last": 0,...
        },...
    ]
}
# OPTIMIZED - Recommended
# Data can come in several aggravations inside the sensor information AGGR
# Dates come separated from the data but are in the same order
# All other information is sensor related information
# We recommend this format because of its simplicity and output size is smaller then normal one
# 1_X_X_143 tag is = CH_MAC_SERIAL_CODE
{
    "dates": [
        "2017-07-21 05:00:00",
        "2017-07-21 05:15:00",
        "2017-07-21 05:30:00",
        "2017-07-21 05:45:00",
        "2017-07-21 06:00:00"
    ],
    "data": {
        "1_X_X_143": {
            "name": "Wind direction",
            "name_custom": false,
            "decimals": 0,
            "unit": "deg",
            "ch": 1,
            "code": 143,
            "group": 16,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 360
            },
            "aggr": {
                "avg": [
                    39,
                    117,
                    85,
                    74,
                    74
                ],
                "last": [
                    39,
                    117,
                    85,
                    74,
                    74
                ]
            },
            "registered": "2017-06-30 18:00:00"
        },
        "2_X_X_600": {
            "name": "Solar radiation",
            "name_custom": false,
            "decimals": 0,
            "unit": "W/m2",
            "ch": 2,
            "code": 600,
            "group": 4,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 32767
            },
            "aggr": {
                "avg": [
                    0,
                    0,
                    0,
                    0,
                    0
                ]
            },
            "registered": "2017-06-30 18:00:00"
        },...
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/data/{{FORMAT}}/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Get last data customized

POST /data/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}}

Retrieve last data that device sends in your liking. We recommend calling /data/{{STATION-ID}} first so you can see if
there is any new data.

NOTE that time period gives you flexibility:

  • Read only X amount of elements
  • Read Xh which means X amount of hours
  • Read Xd which means X amount of days
  • Read Xw which means X amount of weeks
  • Read Xm which means X amount of months

You are limited to retrieve MAX 10.000 data points.

Specifications

Specification Value
method POST
request /data/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
DATA-GROUP Required raw, hourly, daily, monthly Device data grouped
TIME-PERIOD Required Xh, Xd, Xw, Xm, X X = Number, h = hours, d = days, w = weeks, m = months

Body & Schema

Schema Function
schemas/View.json Customizing your data output

Response

Response codes

HTTP CODE Description
200 Success
204 No data for specified time period
400 Bad Request
401 Unauthorized
403 No permissions - No rights
406 Specified params are not acceptable

Response values

Values are self explanatory.

# NORMAL
# Data and sensors come separated and can be connected using unique TAG
# Dates and data are on the same level
# 1_X_X_143_avg tag is = CH_MAC_SERIAL_CODE_AGGREGATION
{
    "sensors": [
        {
            "name": "Wind direction",
            "name_custom": false,
            "decimals": 0,
            "unit": "deg",
            "ch": 1,
            "chain": 1,
            "code": 143,
            "group": 16,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 360
            },
            "aggr": {
                "avg": 1,
                "last": 1
            },
            "registered": "2017-06-30 18:00:00"
        },
        {
            "name": "Solar radiation",
            "name_custom": false,
            "decimals": 0,
            "unit": "W/m2",
            "ch": 2,
            "chain": 1,
            "code": 600,
            "group": 4,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 32767
            },
            "aggr": {
                "avg": 1
            },
            "registered": "2017-06-30 18:00:00"
        },..
    ],
    "data": [
        {
            "date": "2017-07-21 05:00:00",
            "1_X_X_143_avg": 39,
            "1_X_X_143_last": 39,
            "2_X_X_600_avg": 0,
            "4_X_X_30_last": 0,...
        },
        {
            "date": "2017-07-21 05:15:00",
            "1_X_X_143_avg": 117,
            "1_X_X_143_last": 117,
            "2_X_X_600_avg": 0,
            "4_X_X_30_last": 0,...
        },...
    ]
}
# OPTIMIZED - Recommended
# Data can come in several aggravations inside the sensor information AGGR
# Dates come separated from the data but are in the same order
# All other information is sensor related information
# We recommend this format because of its simplicity and output size is smaller then normal one
# 1_X_X_143 tag is = CH_MAC_SERIAL_CODE
{
    "dates": [
        "2017-07-21 05:00:00",
        "2017-07-21 05:15:00",
        "2017-07-21 05:30:00",
        "2017-07-21 05:45:00",
        "2017-07-21 06:00:00"
    ],
    "data": {
        "1_X_X_143": {
            "name": "Wind direction",
            "name_custom": false,
            "decimals": 0,
            "unit": "deg",
            "ch": 1,
            "code": 143,
            "group": 16,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 360
            },
            "aggr": {
                "avg": [
                    39,
                    117,
                    85,
                    74,
                    74
                ],
                "last": [
                    39,
                    117,
                    85,
                    74,
                    74
                ]
            },
            "registered": "2017-06-30 18:00:00"
        },
        "2_X_X_600": {
            "name": "Solar radiation",
            "name_custom": false,
            "decimals": 0,
            "unit": "W/m2",
            "ch": 2,
            "code": 600,
            "group": 4,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 32767
            },
            "aggr": {
                "avg": [
                    0,
                    0,
                    0,
                    0,
                    0
                ]
            },
            "registered": "2017-06-30 18:00:00"
        },...
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method  = "POST";
$request = "/data/{{FORMAT}}/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}}";

// Body that you send needs to be JSON schema validated
$body    = [
    "sensors" => [
        "filter" => [
            "sensor-506" => TRUE
        ]
    ]
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt( $ch, CURLOPT_POST, TRUE );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $body );

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;
{
  "properties": {
    "description": "Pre-defined, combined or custom name",
    "name": {
      "type": "string"
    },
    "sensors": {
      "properties": {
        "filter": {
          "description": "Filter by group, sensor, mac or serial and optionally specify aggregation",
          "properties": {
            "group-7": {
              "items": {
                "type": "string"
              },
              "type": "array",
              "enum": [
                "avg",
                "min",
                "max",
                "sum",
                "time",
                "last",
                "user"
              ]
            },
            "mac-MAC_ADDRESS": {
              "type": "boolean"
            },
            "sensor-506": {
              "items": {
                "type": "string"
              },
              "type": "array",
              "enum": [
                "avg",
                "min",
                "max",
                "sum",
                "time",
                "last",
                "user"
              ]
            },
            "serial-SERIAL": {
              "type": "boolean"
            }
          },
          "type": "object"
        },
        "settings": {
          "description": "Configure sensor output",
          "properties": {
            "group-7": {
               "unit": "Custom unit",
               "type": "string"
            },
            "sensor-506": {
               "unit": "Custom unit",
               "type": "string"
            }
          },
          "type": "object"
        }
      },
      "type": "object"
    },
    "data": {
      "properties": {
        "model": {
          "description": "Disease model name",
          "type": "string"
        },
        "sunrise_sunset": {
          "description": "Get sunrise and sunset dates for specified period",
          "type": "boolean"
        },
        "unit_system": {
          "type": "string",
          "description": "One of",
          "enum": [
            "imperial",
            "metric"
          ]
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
{
  # VIEW NAME: Pre-Defined, Combined, Custom
  "name": "PRE-DEFINED, COMBINED OR CUSTOM ... NAME,
  "sensors": {
    "filter": {
      # Filter out specific sensor
      "sensor-506": 1,
      # Filter out specific sensor and its aggregation
      "sensor-506": [
        "avg"
      ],
      # Filter out specific sensors of a group
      "group-7": 1,
      # Filter out specific sensors of a group and its aggragation
      "group-7": [
        "avg"
      ],
      # Filter out sensors on MAC
      "mac-MAC_ADDRESS": true,
      # Filter out sensors with Serial
      "serial-SERIAL": true
    },
    "settings" : {
       # Configure output of a sensor, by changing the unit manually
       "sensor-506": [
            "unit" : "sec"
       ],
       # Configure output of a sensor group, by changing the unit manually
       "group-7": [
            "unit" : "sec"
       ]
    }
  },
  "data": {
    # UNIT SYSTEM: matric, imperial
    "unit_system": "imperial",
    # Sunrise and sunset dates
    "sunrise_sunset" : true,
    # DISEASE MODEL DATA
    "model": "DISEASE-MODEL"
  }
}

Get data between period customized

POST /data/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP }}

Retrieve data between specified time periods in your liking. We recommend calling /data/{{STATION-ID}} first so you can see if
there is any new data. Times from and to need to be specified in unix timestamp.

You are limited to retrieve MAX 10.000 data points.

Specifications

Specification Value
method POST
request /data/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP }}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
DATA-GROUP Required raw, hourly, daily, monthly Device data grouped
FROM-UNIX-TIMESTAMP Required Unix timestamp Date/Time in unix timestamp
TO-UNIX-TIMESTAMP Optional Unix timestamp Date/Time in unix timestamp, if not specified data will be taken till last available

Body & Schema

Schema Function
schemas/View.json Customizing your data output

Response

Response codes

HTTP CODE Description
200 Success
204 No data for specified time period
400 Bad Request
401 Unauthorized
403 No permissions - No rights
406 Specified params are not acceptable

Response values

Values are self explanatory.

# NORMAL
# Data and sensors come separated and can be connected using unique TAG
# Dates and data are on the same level
# 1_X_X_143_avg tag is = CH_MAC_SERIAL_CODE_AGGREGATION
{
    "sensors": [
        {
            "name": "Wind direction",
            "name_custom": false,
            "decimals": 0,
            "unit": "deg",
            "ch": 1,
            "chain": 1,
            "code": 143,
            "group": 16,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 360
            },
            "aggr": {
                "avg": 1,
                "last": 1
            },
            "registered": "2017-06-30 18:00:00"
        },
        {
            "name": "Solar radiation",
            "name_custom": false,
            "decimals": 0,
            "unit": "W/m2",
            "ch": 2,
            "chain": 1,
            "code": 600,
            "group": 4,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 32767
            },
            "aggr": {
                "avg": 1
            },
            "registered": "2017-06-30 18:00:00"
        },..
    ],
    "data": [
        {
            "date": "2017-07-21 05:00:00",
            "1_X_X_143_avg": 39,
            "1_X_X_143_last": 39,
            "2_X_X_600_avg": 0,
            "4_X_X_30_last": 0,...
        },
        {
            "date": "2017-07-21 05:15:00",
            "1_X_X_143_avg": 117,
            "1_X_X_143_last": 117,
            "2_X_X_600_avg": 0,
            "4_X_X_30_last": 0,...
        },...
    ]
}
# OPTIMIZED - Recommended
# Data can come in several aggravations inside the sensor information AGGR
# Dates come separated from the data but are in the same order
# All other information is sensor related information
# We recommend this format because of its simplicity and output size is smaller then normal one
# 1_X_X_143 tag is = CH_MAC_SERIAL_CODE
{
    "dates": [
        "2017-07-21 05:00:00",
        "2017-07-21 05:15:00",
        "2017-07-21 05:30:00",
        "2017-07-21 05:45:00",
        "2017-07-21 06:00:00"
    ],
    "data": {
        "1_X_X_143": {
            "name": "Wind direction",
            "name_custom": false,
            "decimals": 0,
            "unit": "deg",
            "ch": 1,
            "code": 143,
            "group": 16,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 360
            },
            "aggr": {
                "avg": [
                    39,
                    117,
                    85,
                    74,
                    74
                ],
                "last": [
                    39,
                    117,
                    85,
                    74,
                    74
                ]
            },
            "registered": "2017-06-30 18:00:00"
        },
        "2_X_X_600": {
            "name": "Solar radiation",
            "name_custom": false,
            "decimals": 0,
            "unit": "W/m2",
            "ch": 2,
            "code": 600,
            "group": 4,
            "serial": "X",
            "mac": "X",
            "vals": {
                "min": 0,
                "max": 32767
            },
            "aggr": {
                "avg": [
                    0,
                    0,
                    0,
                    0,
                    0
                ]
            },
            "registered": "2017-06-30 18:00:00"
        },...
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method  = "POST";
$request = "/data/{{FORMAT}}/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}}";

// Body that you send needs to be JSON schema validated
$body    = [
    "sensors" => [
        "filter" => [
            "sensor-506" => TRUE
        ]
    ]
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt( $ch, CURLOPT_POST, TRUE );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $body );

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;
{
  "properties": {
    "description": "Pre-defined, combined or custom name",
    "name": {
      "type": "string"
    },
    "sensors": {
      "properties": {
        "filter": {
          "description": "Filter by group, sensor, mac or serial and optionally specify aggregation",
          "properties": {
            "group-7": {
              "items": {
                "type": "string"
              },
              "type": "array",
              "enum": [
                "avg",
                "min",
                "max",
                "sum",
                "time",
                "last",
                "user"
              ]
            },
            "mac-MAC_ADDRESS": {
              "type": "boolean"
            },
            "sensor-506": {
              "items": {
                "type": "string"
              },
              "type": "array",
              "enum": [
                "avg",
                "min",
                "max",
                "sum",
                "time",
                "last",
                "user"
              ]
            },
            "serial-SERIAL": {
              "type": "boolean"
            }
          },
          "type": "object"
        },
        "settings": {
          "description": "Configure sensor output",
          "properties": {
            "group-7": {
               "unit": "Custom unit",
               "type": "string"
            },
            "sensor-506": {
               "unit": "Custom unit",
               "type": "string"
            }
          },
          "type": "object"
        }
      },
      "type": "object"
    },
    "data": {
      "properties": {
        "model": {
          "description": "Disease model name",
          "type": "string"
        },
        "sunrise_sunset": {
          "description": "Get sunrise and sunset dates for specified period",
          "type": "boolean"
        },
        "unit_system": {
          "type": "string",
          "description": "One of",
          "enum": [
            "imperial",
            "metric"
          ]
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
{
  # VIEW NAME: Pre-Defined, Combined, Custom
  "name": "PRE-DEFINED, COMBINED OR CUSTOM ... NAME,
  "sensors": {
    "filter": {
      # Filter out specific sensor
      "sensor-506": 1,
      # Filter out specific sensor and its aggregation
      "sensor-506": [
        "avg"
      ],
      # Filter out specific sensors of a group
      "group-7": 1,
      # Filter out specific sensors of a group and its aggragation
      "group-7": [
        "avg"
      ],
      # Filter out sensors on MAC
      "mac-MAC_ADDRESS": true,
      # Filter out sensors with Serial
      "serial-SERIAL": true
    },
    "settings" : {
       # Configure output of a sensor, by changing the unit manually
       "sensor-506": [
            "unit" : "sec"
       ],
       # Configure output of a sensor group, by changing the unit manually
       "group-7": [
            "unit" : "sec"
       ]
    }
  },
  "data": {
    # UNIT SYSTEM: matric, imperial
    "unit_system": "imperial",
    # Sunrise and sunset dates
    "sunrise_sunset" : true,
    # DISEASE MODEL DATA
    "model": "DISEASE-MODEL"
  }
}

ROUTES - DISEASE

For retrieving disease model data for your device, you need specific licenses. Contact license@metos.at if you are interested.
Every call regarding disease model is a POST HTTP call.

No license is needed for Evapotranspiration (Daily ET0), which comes along together with measured and calculated historic data in the GET /data response.

The full list of available crops and disease models can be retrieved by requesting /system/diseases from which you use disease model KEY in the schema {"name":KEY} or {"diseases":[KEY, KEY]} for the body of the request. The response includes data series with a NAME as well indicated in RESULTS of the dedicated disease model.

Calculations that do not require license are:

  • Evapotranspiration

Routes

HTTP Method Endpoint URL Params Function
POST /data/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}} STATION-ID, DATA-GROUP, TIME-PERIOD Retrieve last specified disease model(s)
POST /data/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}} STATION-ID, DATA-GROUP, FROM-UNIX-TIMESTAMP, TO-UNIX-TIMESTAMP Retrieve specified disease model(s) for period

URL Parameters

You can either request last values or all values within a specified time period. Find the options in the table below.

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
DATA-GROUP Required raw, hourly, daily, monthly Target resolution for data aggregation
TIME-PERIOD Required Xh, Xd, Xw, Xm, X X = Number of events, h = last X hours, d = last X days, w = last X weeks, m = last X months; e.g. 4h means last 4 hours wheras 4 will return the last 4 datasets based on the given aggregation (raw, hourly, daily, monthly)
FROM-UNIX-TIMESTAMP Required Unix timestamp Date/Time in Unix epoch timestamp
TO-UNIX-TIMESTAMP Optional Unix timestamp Date/Time in unix timestamp, if not specified data will be taken till last available

Body & Schema

All payload data has to follow the form: {"Key":"Value"} or {"Key":["Value", "Value"]}

Key Values Description
name Exact key from /system/diseases | Single model response, e.g. {"name":"SugarBeet/BeetCast"}
diseases Exact keys from /system/diseases | Multiple model responses, e.g. {"diseases":["SugarBeet/BeetCast", "SugarBeet/Cercospora", "SugarBeet/Cercopri"]}
{
    "dates": [
        "2021-02-05 11:00:00",
        "2021-02-05 12:00:00",
        "2021-02-05 13:00:00",
        "2021-02-05 14:00:00",
        "2021-02-05 15:00:00",
        "2021-02-05 16:00:00",
        "2021-02-05 17:00:00",
        "2021-02-05 18:00:00",
    
    ],
    "data": [
        {
            "name": "Leaf Wetness",
            "name_original": "Leaf Wetness",
            "type": "Sensor",
            "decimals": 0,
            "unit": "min",
            "ch": 8,
            "code": 4,
            "group": 12,
            "serial": "x",
            "mac": "x",
            "registered": "2021-01-29 13:45:09",
            "vals": {},
            "aggr": [
                "time"
            ],
            "values": {
                "time": [
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                    0,
                ]
            }
        },
        {
            "name": "HC Air temperature",
            "name_original": "HC Air temperature",
            "type": "Sensor",
            "decimals": 2,
            "unit": "°C",
            "ch": 14,
            "code": 506,
            "group": 1,
            "serial": "x",
            "mac": "x",
            "registered": "2021-01-29 13:45:09",
            "vals": {},
            "aggr": [
                "avg",
                "max",
                "min"
            ],
            "values": {
                "avg": [
                    10.31,
                    9.96,
                    10.5,
                    10.78,
                    10.5,
                    9.81,
                    7.42,
                    5.27,
                    
                ],
                "max": [
                    10.45,
                    10.16,
                    10.87,
                    10.88,
                    10.6,
                    10.73,
                    8.47,
                    6.11,
                   
                ],
                "min": [
                    10.16,
                    9.83,
                    10.1,
                    10.63,
                    10.42,
                    8.84,
                    6.34,
                    4.46,
                ]
            }
        },
      [...]

ROUTES - FORECAST

For retrieving forecast services for your device, you need specific licenses. Contact license@metos.at if you are interested.
Every call regarding forecast, forecast fieldwork services, forecast animal services and forecast disease
models is a POST HTTP call. The response is an hourly forecast by default.

The specific forecast is selected via raw POST HTTP parameter in the body.
For example: {"name":"general3"}

Schemas

Returning JSON schema is similar for all /forecast calls.
The two root elements are:

{
"dates": ...
"data": ...
}
  • "dates" lists all the dates and times for data, which is basically covering 3, or 7x24 full hours depending on the payload parameter starting from the next full hour.

  • "data" contains all forecast data. All the calls return information for Precipitation,
    Probability of snow, Temperature, Meteoblue pictocode number, Wind speed, Wind direction,
    Relative humidity, Sea level pressure, Probability of precipitation, Cloud cover, Leaf wetness, Global
    radiation, Wind gust, Air surface pressure and then data for requested forecast service/model. The
    data is listed in the same chronological order as the dates/times. So, for example, the first data listed
    (for each category) was measured at the first listed date and time.

  • Find more details about the pictocodes in the day and night pictograms section.

Routes

HTTP Method Endpoint URL Params Function
POST /forecast/{{STATION-ID}}/{{DATA-GROUP}} STATION-ID, DATA-GROUP Forecast data package or image

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
DATA-GROUP Optional hourly, daily Hourly is default; this two forecast services support daily grouping as well

Body & Schema

All payload data has to follow the form:
{"Key":"Value"}

Key Values Description
name general3, general7 Get general weather forecast for the next 3 or 7 days
{u'data': [{u'name': u'Pictocode',
   u'type': u'Forecast',
   u'unit': u'',
   u'values': {u'result': [1, 1, 2]}},
  {u'name': u'temperature_max',
   u'type': u'Forecast',
   u'unit': u'\xb0C',
   u'values': {u'result': [16.7, 15.6, 13.2]}},
  {u'name': u'temperature_min',
   u'type': u'Forecast',
   u'unit': u'\xb0C',
   u'values': {u'result': [-1.6, 0.9, 2.9]}},
  {u'name': u'temperature_mean',
   u'type': u'Forecast',
   u'unit': u'\xb0C',
   u'values': {u'result': [6.1, 6.8, 7.3]}},
  {u'name': u'Wind direction',
   u'type': u'Forecast',
   u'unit': u'deg',
   u'values': {u'result': [270, 270, 270]}},
  {u'name': u'Probability of Prec.',
   u'type': u'Forecast',
   u'unit': u'%',
   u'values': {u'result': [0, 0, 28]}},
  {u'name': u'Precipitation',
   u'type': u'Forecast',
   u'unit': u'mm',
   u'values': {u'result': [0, 0, 0]}},
  {u'name': u'Probability of snow',
   u'type': u'Forecast',
   u'unit': u'',
   u'values': {u'result': [0, 0, 0]}},
  {u'name': u'windspeed_max',
   u'type': u'Forecast',
   u'unit': u'm/s',
   u'values': {u'result': [2.1, 2.7, 9.5]}},
  {u'name': u'windspeed_mean',
   u'type': u'Forecast',
   u'unit': u'm/s',
   u'values': {u'result': [1.3, 1, 4.9]}},
  {u'name': u'windspeed_min',
   u'type': u'Forecast',
   u'unit': u'm/s',
   u'values': {u'result': [0.5, 0.1, 1]}},
  {u'name': u'relativehumidity_max',
   u'type': u'Forecast',
   u'unit': u'%',
   u'values': {u'result': [73, 69, 85]}},
  {u'name': u'relativehumidity_min',
   u'type': u'Forecast',
   u'unit': u'%',
   u'values': {u'result': [42, 38, 63]}},
  {u'name': u'relativehumidity_mean',
   u'type': u'Forecast',
   u'unit': u'%',
   u'values': {u'result': [62, 57, 75]}},
  {u'name': u'Leaf Wetness',
   u'type': u'Forecast',
   u'unit': u'',
   u'values': {u'result': [0, 0, 0]}},
  {u'name': u'Global radiation - Sensible Heat Flux',
   u'type': u'Forecast',
   u'unit': u'W/m2',
   u'values': {u'result': [19, 5, 10]}},
  {u'name': u'Wind orientation',
   u'type': u'Calculation',
   u'unit': u'deg',
   u'values': {u'result': [270, 270, 270]}}],
 u'dates': [u'2019-02-26 00:00:00',
  u'2019-02-27 00:00:00',
  u'2019-02-28 00:00:00']}
URL_TO_DOWNLOAD_THE_IMAGE

Retrieve forecast image

POST /chart/image/{{STATION-ID}}

For retrieving forecast services for your device, you need specific licenses. Contact license@metos.at if you are interested.
Every call regarding forecast images is a POST HTTP call. The response includes a link to the image for download.

The specific forecast image type is selected via raw POST HTTP parameter in the body.
For example: {"name":"meteogram_agro"}

Specifications

Specification Value
method POST
request /chart/image/{{STATION-ID}}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device

Body & Schema

All payload data has to follow the form:
{"Key":"Value"}
Key Values Description
name pictoprint Get localized 7 days forecast pictoprint in JPG format
name meteogram_agro, meteogram_one, meteogram_14day Get localized 7 and 14 days forecast overviews in PNG format

Response

Response codes

HTTP CODE Description
200 Ok
401 Unauthorized
402 License is required for this service
403 Forbidden
404 Station not found
406 Specified params are not acceptable

Response values

URL to JPEG or PNG image for download

URL_TO_DOWNLOAD_THE_IMAGE

ROUTES - CHART

Retrieving charts or images of your device, forecast and disease model data with help of VIEW (Please refer to VIEW documentation under INFO section).

You are limited to retrieve MAX 10.000 data points.

Schemas

Schema Function
schemas/View.json Select your view

Routes

HTTP Method Endpoint URL Params Function
GET /chart/{{TYPE}}/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}} TYPE, STATION-ID, DATA-GROUP, TIME-PERIOD Charting last data
GET /chart/{{TYPE}}/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}} TYPE, STATION-ID, DATA-GROUP, FROM-UNIX-TIMESTAMP, TO-UNIX-TIMESTAMP Charting for period

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
TYPE Required image, images, highchart Target output: image, multiple images or highchart options
DATA-GROUP Required raw, hourly, daily, monthly Device data grouped
TIME-PERIOD Required Xh, Xd, Xw, Xm, X X = Number, h = hours, d = days, w = weeks, m = months
FROM-UNIX-TIMESTAMP Required Unix timestamp Date/Time in unix timestamp
TO-UNIX-TIMESTAMP Optional Unix timestamp Date/Time in unix timestamp, if not specified data will be taken till last available
# 1. Filter data 5 - Wind speed, 4 - Leaf Wetness, 506 - Air temperature, 507 - Relative humidity
# 2. Data comes in imperial units
{
  "sensors": {
    "filter": {
      "sensor-5": true,
      "sensor-4": true,
      "sensor-506": true,
      "sensor-507": true
    }
  },
  "data": {
     "unit_system": "imperial"
  }
}
{
  "properties": {
    "description": "Pre-defined, combined or custom name",
    "name": {
      "type": "string"
    },
    "sensors": {
      "properties": {
        "filter": {
          "description": "Filter by group, sensor, mac or serial and optionally specify aggregation",
          "properties": {
            "group-7": {
              "items": {
                "type": "string"
              },
              "type": "array",
              "enum": [
                "avg",
                "min",
                "max",
                "sum",
                "time",
                "last",
                "user"
              ]
            },
            "mac-MAC_ADDRESS": {
              "type": "boolean"
            },
            "sensor-506": {
              "items": {
                "type": "string"
              },
              "type": "array",
              "enum": [
                "avg",
                "min",
                "max",
                "sum",
                "time",
                "last",
                "user"
              ]
            },
            "serial-SERIAL": {
              "type": "boolean"
            }
          },
          "type": "object"
        },
        "settings": {
          "description": "Configure sensor output",
          "properties": {
            "group-7": {
               "unit": "Custom unit",
               "type": "string"
            },
            "sensor-506": {
               "unit": "Custom unit",
               "type": "string"
            }
          },
          "type": "object"
        }
      },
      "type": "object"
    },
    "data": {
      "properties": {
        "model": {
          "description": "Disease model name",
          "type": "string"
        },
        "sunrise_sunset": {
          "description": "Get sunrise and sunset dates for specified period",
          "type": "boolean"
        },
        "unit_system": {
          "type": "string",
          "description": "One of",
          "enum": [
            "imperial",
            "metric"
          ]
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
{
  # VIEW NAME: Pre-Defined, Combined, Custom
  "name": "PRE-DEFINED, COMBINED OR CUSTOM ... NAME,
  "sensors": {
    "filter": {
      # Filter out specific sensor
      "sensor-506": 1,
      # Filter out specific sensor and its aggregation
      "sensor-506": [
        "avg"
      ],
      # Filter out specific sensors of a group
      "group-7": 1,
      # Filter out specific sensors of a group and its aggragation
      "group-7": [
        "avg"
      ],
      # Filter out sensors on MAC
      "mac-MAC_ADDRESS": true,
      # Filter out sensors with Serial
      "serial-SERIAL": true
    },
    "settings" : {
       # Configure output of a sensor, by changing the unit manually
       "sensor-506": [
            "unit" : "sec"
       ],
       # Configure output of a sensor group, by changing the unit manually
       "group-7": [
            "unit" : "sec"
       ]
    }
  },
  "data": {
    # UNIT SYSTEM: matric, imperial
    "unit_system": "imperial",
    # Sunrise and sunset dates
    "sunrise_sunset" : true,
    # DISEASE MODEL DATA
    "model": "DISEASE-MODEL"
  }
}

Charting last data

GET /chart/{{TYPE}}/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}}

Retrieve chart from last data that device sends. We recommend calling /data/{{STATION-ID}} first so you can see if
there is any new data.

NOTE that time period gives you flexibility:

  • Read only X amount of elements
  • Read Xh which means X amount of hours
  • Read Xd which means X amount of days
  • Read Xw which means X amount of weeks
  • Read Xm which means X amount of months

You are limited to retrieve MAX 10.000 data points.

Specifications

Specification Value
method GET
request /chart/{{TYPE}}/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}}

URL Parameters

Value Optional/Required Options Description
TYPE Required image, images, highchart Type of output
STATION-ID Required STRING Unique identifier of a device
DATA-GROUP Required raw, hourly, daily, monthly Device data grouped
TIME-PERIOD Required Xh, Xd, Xw, Xm, X X = Number, h = hours, d = days, w = weeks, m = months

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No data for specified time period
400 Data over limit
401 Unauthorized
403 No permissions - No rights
406 Specified params are not acceptable

Response values

Values are self explanatory.

Depending on the selected TYPE:
- single IMAGE PATH
- Array of IMAGE PATHS
- HIGHCHARTS JSON
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/chart/{{TYPE}}/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Charting period

GET /chart/{{TYPE}}/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP }}

Charting data between specified time periods. We recommend calling /data/{{STATION-ID}} first so you can see if
there is any new data. Times from and to need to be specified in unix timestamp.

You are limited to retrieve MAX 10.000 data points.

Specifications

Specification Value
method GET
request /chart/{{TYPE}}/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP }}

URL Parameters

Value Optional/Required Options Description
TYPE Required image, images, highchart Type of output
STATION-ID Required STRING Unique identifier of a device
DATA-GROUP Required raw, hourly, daily, monthly Device data grouped
FROM-UNIX-TIMESTAMP Required Unix timestamp Date/Time in unix timestamp
TO-UNIX-TIMESTAMP Optional Unix timestamp Date/Time in unix timestamp, if not specified data will be taken till last available

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No data for specified time period
400 Data over limit
401 Unauthorized
403 No permissions - No rights
406 Specified params are not acceptable

Response values

Values are self explanatory.

Depending on the selected TYPE:
- single IMAGE PATH
- Array of IMAGE PATHS
- HIGHCHARTS JSON
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/chart/{{TYPE}}/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Charting customized last data

POST /chart/{{TYPE}}/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}}

Retrieve customized chart from last data that device sends. We recommend calling /data/{{STATION-ID}} first so you can see if
there is any new data.

NOTE that time period gives you flexibility:

  • Read only X amount of elements
  • Read Xh which means X amount of hours
  • Read Xd which means X amount of days
  • Read Xw which means X amount of weeks
  • Read Xm which means X amount of months

You are limited to retrieve MAX 10.000 data points.

Specifications

Specification Value
method POST
request /chart/{{TYPE}}/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}}

URL Parameters

Value Optional/Required Options Description
TYPE Optional image, images, highchart Type of output
STATION-ID Required STRING Unique identifier of a device
DATA-GROUP Required raw, hourly, daily, monthly Device data grouped
TIME-PERIOD Required Xh, Xd, Xw, Xm, X X = Number, h = hours, d = days, w = weeks, m = months

Body & Schema

see #diseases and #forecast

Response

Response codes

HTTP CODE Description
200 Success
204 No data for specified time period
400 Data over limit
401 Unauthorized
403 No permissions - No rights
406 Specified params are not acceptable

Response values

Values are self explanatory.

IMAGE PATH
IMAGES PATH
HIGHCHART
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method  = "POST";
$request = "/chart/{{TYPE}}/{{STATION-ID}}/{{DATA-GROUP}}/last/{{TIME-PERIOD}}";

// Body that you send needs to be JSON schema validated
$body    = [
    "sensors" => [
        "filter" => [
            "sensor-506" => TRUE
        ]
    ]
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt( $ch, CURLOPT_POST, TRUE );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $body );

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Charting customized for period

POST /chart/{{TYPE}}/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP }}

Charting customized data between specified time periods. We recommend calling /data/{{STATION-ID}} first so you can see if
there is any new data. Times from and to need to be specified in unix timestamp.

You are limited to retrieve MAX 10.000 data points.

Specifications

Specification Value
method POST
request /chart/{{TYPE}}/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP }}

URL Parameters

Value Optional/Required Options Description
TYPE Optional image, images, highchart Type of output
STATION-ID Required STRING Unique identifier of a device
DATA-GROUP Required raw, hourly, daily, monthly Device data grouped
FROM-UNIX-TIMESTAMP Required Unix timestamp Date/Time in unix timestamp
TO-UNIX-TIMESTAMP Optional Unix timestamp Date/Time in unix timestamp, if not specified data will be taken till last available

Body & Schema

see #diseases and #forecast

Response

Response codes

HTTP CODE Description
200 Success
204 No data for specified time period
400 Data over limit
401 Unauthorized
403 No permissions - No rights
406 Specified params are not acceptable

Response values

Values are self explanatory.

IMAGE PATH
IMAGES PATH
HIGHCHART
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method  = "POST";
$request = "/chart/{{TYPE}}/{{STATION-ID}}/{{DATA-GROUP}}/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP }}";

// Body that you send needs to be JSON schema validated
$body    = [
    "sensors" => [
        "filter" => [
            "sensor-506" => TRUE
        ]
    ]
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt( $ch, CURLOPT_POST, TRUE );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $body );

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

ROUTES - CAMERAS

All the information that is related to your camera device.

Schemas

N/A

Routes

HTTP Method Endpoint URL Params Function
GET /camera/{{STATION-ID}}/photos/info STATION-ID Read station information
GET /camera/{{STATION-ID}}/photos/last/{{AMOUNT}}/{{CAMERA}} STATION-ID, AMOUNT, CAMERA Last amount of pictures
GET /camera/{{STATION-ID}}/photos/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}}/{{CAMERA}} STATION-ID, FROM-UNIX-TIMESTAMP, TO-UNIX-TIMESTAMP, CAMERA Retrieve pictures for specified period

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
AMOUNT Required INTEGER Amount of last pictures you wish to have
CAMERA Optional 0, 1, 2 0 - Both cameras, 1 - Wide Camera, 2 - Zoom Camera
FROM-UNIX-TIMESTAMP Optional Unix timestamp Date/Time in unix timestamp
TO-UNIX-TIMESTAMP Optional Unix timestamp Date/Time in unix timestamp

Response Values and Coordinates

Field Description
new New detections
x Values in normalized coordinates [0...1]. Left border of the leftmost pixel column = 0. Right border of the rightmost pixel column = 1 (width [px])
y Values in normalized coordinates [0...1]. Upper border of the topmost pixel row = 0. Lower border of the bottommost pixel row = 1 (height [px])
probability Normalized value [0 1]. Certainty, 1 = 100%, of the found label.


Rectangle Coordinate System Location
[x_min], [y_min] Upper left corner
[x_max], [y_max] Lower right corner

Min, Max date/time of data:

GET /camera/{{STATION-ID}}/photos/info

Retrieve min and max date of device data availability. This request can be used to check if device has sent new data which you
can retrieve, by just memorizing last date and compare it with current one.

Specifications

Specification Value
method GET
request /camera/{{STATION-ID}}/photos/info

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No data
401 Unauthorized
403 No permissions - No rights
406 Device specified is not camera device

Response values

Values are self explanatory.

{
    "first": "YYYY-MM-DD HH:MM:SS",
    "last": "YYYY-MM-DD HH:MM:SS"
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/camera/YOUR-CAMERA-STATION/photos/info";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Get last photos

GET /camera/{{STATION-ID}}/photos/last/{{AMOUNT}}/{{CAMERA}}

Retrieve last data that device sends.

Specifications

Specification Value
method GET
request /camera/{{STATION-ID}}/photos/last/{{AMOUNT}}/{{CAMERA}}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
AMOUNT Required INTEGER Amount of last pictures you wish to have
CAMERA Optional 0, 1, 2 0 - Both cameras, 1 - Wide Camera, 2 - Zoom Camera

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No data
401 Unauthorized
403 No permissions - No rights
406 Device specified is not camera device or specified params are not acceptable

Response values

Values are self explanatory.

WARNINGS

The PNG file format is not supported anymore and the image is not being generated. The urlPNG property always returns null.

[
    {
        "time": "YYYY-MM-DD HH:MM:SS",
        "nm": "STATION-ID",
        "cam_id": 1,
        "pic_id": 456,
        "filename": "RAW-FILENAME",
        "rectangles": [
            {
                "x_min": 0.47980349344978,
                "y_min": 0.082605531295488,
                "x_max": 0.50982532751092,
                "y_max": 0.122634643377,
                "probability": 0.998,
                "label": "moth",
                "new" : "False",
                "generated_by": "system"
            },
            {
                "x_min": 0.2953056768559,
                "y_min": 0.13937409024745,
                "x_max": 0.3367903930131,
                "y_max": 0.19468704512373,
                "probability": 1,
                "label": "moth",
                "new" : "True",
                "generated_by": "user"
            },
            ...
        ],
        "url": "PATH-TO-THE-JPG-IMAGE",
        "urlPNG": null,
        "thumb": "PATH-TO-THE-JPG-IMAGE-THUMBNAIL"
    },
    ...
]
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/camera/{{STATION-ID}}/photos/last/{{AMOUNT}}/{{CAMERA}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Get photos between period

GET /camera/{{STATION-ID}}/photos/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}}/{{CAMERA}}

Retrieve photos between specified period that device sends.

Specifications

Specification Value
method GET
request /camera/{{STATION-ID}}/photos/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}}/{{CAMERA}}

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device
CAMERA Optional 0, 1, 2 0 - Both cameras, 1 - Wide Camera, 2 - Zoom Camera
FROM-UNIX-TIMESTAMP Optional Unix timestamp Date/Time in unix timestamp
TO-UNIX-TIMESTAMP Optional Unix timestamp Date/Time in unix timestamp

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 No data
401 Unauthorized
403 No permissions - No rights
406 Device specified is not camera device or specified params are not acceptable

Response values

Values are self explanatory.

WARNINGS

The PNG file format is not supported anymore and the image is not being generated. The urlPNG property always returns null.

[
    {
        "time": "YYYY-MM-DD HH:MM:SS",
        "nm": "STATION-ID",
        "cam_id": 1,
        "pic_id": 456,
        "filename": "RAW-FILENAME",
        "rectangles": [
            {
                "x_min": 0.47980349344978,
                "y_min": 0.082605531295488,
                "x_max": 0.50982532751092,
                "y_max": 0.122634643377,
                "probability": 0.998,
                "label": "moth",
                "new" : "False",
                "generated_by": "system"
            },
            {
                "x_min": 0.2953056768559,
                "y_min": 0.13937409024745,
                "x_max": 0.3367903930131,
                "y_max": 0.19468704512373,
                "probability": 1,
                "label": "moth",
                "new" : "True",
                "generated_by": "user"
            },
            ...
        ],
        "url": "PATH-TO-THE-JPG-IMAGE",
        "urlPNG": null,
        "thumb": "PATH-TO-THE-JPG-IMAGE-THUMBNAIL"
    },
    ...
]
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/camera/{{STATION-ID}}/photos/from/{{FROM-UNIX-TIMESTAMP}}/to/{{TO-UNIX-TIMESTAMP}}/{{CAMERA}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

ROUTES - WORKING PLANNING

Retrieve charts and grid information about working planning

Schemas

Returning JSON schema is similar for all /working-planning calls, always using POST requests and body parameters.
The two resulting root elements are:

{
"chartsOptions": ...
"grid": ...
}
  • "chartsOptions" complete Highcharts options for build our on chart.

  • "grid" contains all grid headers and values.

Route

HTTP Method Endpoint URL Params
GET /working-planning/{{STATION-ID}} STATION-ID

URL Parameters

Value Optional/Required Options Description
STATION-ID Required STRING Unique identifier of a device

Body parameters

{
    "name": ...
    "crop": ...
}
Value Optional/Required Options Description
name Required STRING Name of the working planning
crop Required not always STRING Name of the crop. Required only for specific models

Models Avaiable

Name Crop Description
plant-nutrition ------------------ Plant Nutrition
field-accessibility ------------------ Field Acessibility
tillage-ability ------------------ Tillage ability
sowning-window general Sowing Window - General
sowning-window potato Sowing Window - Potato
sowning-window sugarbeet Sowing Window - Sugar beet
sowning-window corn Sowing Window - Corn
sowning-window canola Sowing Window - Canola
sowning-window sunflower Sowing Window - Sunflower
sowning-window cotton Sowing Window - Cotton
plant-protection ----------------- Spraying Window
haverst-window fruit-grape Haverst Window - Fruit & grape
haverst-window sugar-beet-potato Haverst Window - Sugar, beet and potato
haverst-window combine-cereals Haverst Window - Small cereals
haverst-window hay-silage Haverst Window - Hay & Silage

Examples here: Postman examples

{
    "chartsOptions": [...],
    "grid": [...]
}
// complete example on postman collection https://bit.ly/working-planning-docs

ROUTES - FARM

All the information that is related to your farms.

Schemas

Schema Function

Routes

HTTP Method Endpoint URL Params Function
GET /farms None Read list of farms of a user
GET /farms/{{FARM-ID}} FARM-ID Read specific cropzone of a user
POST /farms None Create a farm for a user
PUT /farms/{{FARM-ID}} FARM-ID Update a farm of a user
DELETE /farms/{{FARM-ID}} FARM-ID Delete a farm of a user

URL Parameters

Value Optional/Required Options Description
FARM-ID Required STRING Unique identifier of a farm

List of all Farms:

GET /farms

Read list of farms of a user.

Specifications

Specification Value
method GET
request /farms

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 OK
401 Unauthorized

Response values

Values are self explanatory.

[
    {
    "name": "cropzone_name",
    "id": "5df221dc9dc6d623305c5dbd"
    },
    {
    "name": "cropzone_name2",
    "id": "5fc4aa973758376e5a020cf8"
    },
    ...
]
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/farms";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Get Farm by ID:

GET /farms/{{FARM-ID}}

Read specific cropzone of a user.

Specifications

Specification Value
method GET
request /farms/{{FARM-ID}}

URL Parameters

Value Optional/Required Options Description
FARM-ID Required STRING Unique identifier of a farm

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 OK
401 Unauthorized
404 Farm not found

Response values

Values are self explanatory.

{
    "name": "cropzone_name",
    "id": "5df221dc9dc6d623305c5dbd"
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/farms/{{FARM-ID}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Create Farm

POST /farms

Create a farm for a user

Specifications

Specification Value
method POST
request /farms

URL Parameters

N/A

Body & Schema

Schema Function
schemas/FarmInsert.json Farm creation schema

Response codes

HTTP CODE Description
201 Created successfully
400 Bad request
401 Unauthorized

Response values

Values are self explanatory.

"64632f000c6e463f6b0c125e"
{
  "title": "Farm Update Schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 50,
      "minLength": 3
    }
  }
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "POST";
$request = "/farms";
// Body that you send needs to be JSON schema validated
$body    = [
    "name" => "farm_name"
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt( $ch, CURLOPT_POST, TRUE );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $body );

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Update Farm:

PUT /farms/{{FARM-ID}}

Update a farm of a user

Specifications

Specification Value
method PUT
request /farms/{{FARM-ID}}

URL Parameters

Value Optional/Required Options Description
FARM-ID Required STRING Unique identifier of a farm

Body & Schema

Schema Function
schemas/FarmUpdate.json Farm update schema

Response

Response codes

HTTP CODE Description
200 Success
204 No changes have been made
400 Validation errors
401 Unauthorized
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method  = "PUT";
$request = "/farms/{{FARM-ID}}";
// Body that you send needs to be JSON schema validated
$body    = [
  "name" => "farm_name"
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;
{
  "title": "Farm Update Schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 50,
      "minLength": 3
    }
  }
}
{
    "name": "farm_name"
}

Remove Farm:

DELETE /farms/{{FARM-ID}}

Removing farm from a user.

Specifications

Specification Value
method DELETE
request /farms/{{FARM-ID}}

URL Parameters

Value Optional/Required Options Description
FARM-ID Required STRING Unique identifier of a farm

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 Nothing to be removed
401 Unauthorized - Login required
403 Forbidden - User does not own farm
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "DELETE";
$request = "/farms/{{FARM-ID}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

ROUTES - FIELD

All the information that is related to your fields.

Schemas

Routes

HTTP Method Endpoint URL Params Function
GET /fields None Read list of fields of a user
GET /farms/{{FARM-ID}}/fields FARM-ID Read list of fields of a specific farm of a user
POST /farms/{{FARM-ID}}/fields FARM-ID Create a field for a specific farm
PUT /farms/{{FARM-ID}}/fields/{{FIELD-ID}} FARM-ID, FIELD-ID Update a field of a user
DELETE /farms/{{FARM-ID}}/fields/{{FIELD-ID}} FARM-ID Delete a field of a user

URL Parameters

Value Optional/Required Options Description
FARM-ID Required STRING Unique identifier of a farm
FIELD-ID Required STRING Unique identifier of a field

List of all Fields:

GET /fields

Read list of fields of a user.

Specifications

Specification Value
method GET
request /fields

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 OK
401 Unauthorized

Response values

Values are self explanatory.

[
    {
        "name": "field_name1",
        "farm": {
            "name": "farm_name1",
            "id": "5ddf99749dc6d63a0645dc68"
        },
        "id": "5ddf99749dc6d617df5ddd90"
    },
    {
        "name": "field_name2",
        "farm": {
            "name": "farm_name1",
            "id": "5ddf99749dc6d63a0645dc68"
        },
        "id": "5df221dd9dc6d6236425ca3a"
    },
    ...
]
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/fields";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Get Fields of Farm:

GET /farms/{{FARM-ID}}/fields

Read list of fields of a user.

Specifications

Specification Value
method GET
request /farms/{{FARM-ID}}/fields

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 OK
401 Unauthorized

Response values

Values are self explanatory.

[
    {
        "name": "field_name1",
        "farm": {
            "name": "farm_name",
            "id": "6266de5a7b89135150031d81"
        },
        "id": "6266de5a65fc8423980785ac"
    },
    {
        "name": "field_name2",
        "farm": {
            "name": "farm_name",
            "id": "6266de5a7b89135150031d81"
        },
        "id": "6283ab2fe23ae3d8550cd56c"
    },
    ...
]
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/farms/{{FARM-ID}}/fields";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Create Field:

POST /farms/{{FARM-ID}}/fields

Create a field on a specific farm for a user

Specifications

Specification Value
method POST
request /farms/{{FARM-ID}}/fields

URL Parameters

Value Optional/Required Options Description
FARM-ID Required STRING Unique identifier of a farm

Body & Schema

Schema Function
schemas/FieldInsert.json Field creation schema

Response codes

HTTP CODE Description
201 Created successfully
400 Bad request
401 Unauthorized

Response values

Values are self explanatory.

"6463732f46242da803039dc5"
{
  "title": "Field Insert Schema",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 50,
      "minLength": 3
    }
  }
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "POST";
$request = "/farms/{{FARM-ID}}/fields";
// Body that you send needs to be JSON schema validated
$body    = [
    "name" => "field_name"
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt( $ch, CURLOPT_POST, TRUE );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $body );

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Update Field:

PUT /farms/{{FARM-ID}}/fields/{{FIELD-ID}}

Update a field of a specific farm

Specifications

Specification Value
method PUT
request /farms/{{FARM-ID}}/fields/{{FIELD-ID}}

URL Parameters

Value Optional/Required Options Description
FARM-ID Required STRING Unique identifier of a farm
FIELD-ID Required STRING Unique identifier of a field

Body & Schema

Schema Function
schemas/FieldUpdate.json Field update schema

Response

Response codes

HTTP CODE Description
200 Success
204 No changes have been made
400 Validation errors
401 Unauthorized
403 No permissions
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method  = "PUT";
$request = "/farms/{{FARM-ID}}/fields/{{FIELD-ID}}";
// Body that you send needs to be JSON schema validated
$body    = [
  "name" => "field_name"
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;
{
  "title": "Field Update Schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 50,
      "minLength": 3
    }
  }
}
{
    "name": "field_name"
}

Remove Farm:

DELETE /farms/{{FARM-ID}}/fields/{{FIELD-ID}}

Removing field of a specific farm.

Specifications

Specification Value
method DELETE
request /farms/{{FARM-ID}}/fields/{{FIELD-ID}}

URL Parameters

Value Optional/Required Options Description
FARM-ID Required STRING Unique identifier of a farm
FIELD-ID Required STRING Unique identifier of a field

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 Success
204 Nothing to be removed
401 Unauthorized - Login required
403 Forbidden - User does not own field
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "DELETE";
$request = "/farms/{{FARM-ID}}/fields/{{FIELD-ID}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

ROUTES - CROPZONE

All the information that is related to your cropzones.

Schemas

Schema Function
schemas/SentinelStatisticsBody.json Sentinel statistics body
schemas/SentinelValuesBody.json Sentinel value body
schemas/FittingCurveBody.json fitting curve body

Routes

HTTP Method Endpoint URL Params Function
GET /crop-zones None Read list of cropzones of a user
GET /crop-zones/{{CROPZONE-ID}} CROPZONE-ID Read specific cropzone of a user
POST /crop-zones/{{CROPZONE-ID}}/sentinel-statistics CROPZONE-ID Get sentinel statistics of a cropzone
POST /crop-zones/{{CROPZONE-ID}}/sentinel-values CROPZONE-ID Get sentinel values of a cropzone
POST /crop-zones/{{CROPZONE-ID}}/fitting-curve CROPZONE-ID Get fitting curve of sentinel statistics

URL Parameters

Value Optional/Required Options Description
CROPZONE-ID Required STRING Unique identifier of a cropzone

List of all Cropzones:

GET /crop-zones

Read list of cropzones of a user.

Specifications

Specification Value
method GET
request /crop-zones

URL Parameters

N/A

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 OK
401 Unauthorized

Response values

Values are self explanatory.

[
    {
        "name": "Cropzone name",
        "from": "YYYY-MM-DDTHH:MM:SS+00:00",
        "to": "YYYY-MM-DDTHH:MM:SS+00:00",
        "crop_name": "Beans",
        "boundary": {
            "type": "Polygon",
            "coordinates": [
                [
                    [
                        15.614301811458757,
                        46.540910701449185
                    ],
                    [
                        15.614709507229021,
                        46.54108965850714
                    ],
                    [
                        15.614301811458757,
                        46.540910701449185
                    ]
                ]
            ]
        },
        "cached_lai_stats": [],
        "cached_lai_values": [],
        "cached_ndvi_stats": [],
        "cached_ndvi_values": [],
        "soil": {
            "layers": [
                {
                    "depth": 10,
                    "field_capacity": 28,
                    "refill_point": 14,
                    "unit": "%"
                },
                {
                    "depth": 20,
                    "field_capacity": 28,
                    "refill_point": 14,
                    "unit": "%"
                },
                ...
            ],
            "root_restriction_depth": 2,
            "initial_soil_water_content": 0.4
        },
        "crop": {
            "id": "5a9d6990ecda8a0e1e68d00e",
            "emergence": "YYYY-MM-DDTHH:MM:SS+00:00",
            "fao56": {
                "K_ini": 0.5,
                "K_mid": 1.15,
                "K_end": 0.75,
                "L_ini": "YYYY-MM-DDTHH:MM:SS+00:00",
                "L_dev": "YYYY-MM-DDTHH:MM:SS+00:00",
                "L_mid": "YYYY-MM-DDTHH:MM:SS+00:00",
                "L_late": "YYYY-MM-DDTHH:MM:SS+00:00",
                "R_ini": 0.1
                "R_mid": 0.3
                "R_end": 0.6
            }
        },
        "rain_efficacies": [
            {
                "efficacy": "0.8",
                "lt": "5",
                "gte": "0"
            },
            {
                "efficacy": "0.7",
                "lt": "10",
                "gte": "5"
            },
            {
                "efficacy": "0.6",
                "lt": "999",
                "gte": "10"
            }
        ],
        "data_sources": [
            {
                "device_name": "002099E7",
                "device_id": 7,
                "source": {
                    "channel": 5,
                    "code": 6,
                    "group": 5,
                    "type": "SENSOR",
                    "aggr": "SUM"
                },
                "module": "IRRIMET"
            },
            {
                "device_name": "002099E7",
                "device_id": 7,
                "source": {
                    "id": "evapotranspiration",
                    "type": "MODEL",
                    "sensors": [
                        {
                            "group": 1,
                            "channel": 18,
                            "code": 506
                        },
                        {
                            "group": 2,
                            "channel": 19,
                            "code": 507
                        },
                        {
                            "group": 4,
                            "channel": 0,
                            "code": 600
                        },
                        {
                            "group": 6,
                            "channel": 4000,
                            "code": 16391
                        }
                    ]
                },
                "module": "IRRIMET"
            },
            {
                "device_name": "002099E7",
                "device_id": 7,
                "source": {
                    "type": "SOIL_MOISTURE_SENSOR_OR_PROBE",
                    "group": 25,
                    "layers": [
                        {
                            "code": 19201,
                            "channel": 12001,
                            "depth": 10,
                            "field_capacity": 23,
                            "refill_point": 14,
                            "unit": "",
                            "node": "253772",
                            "calibration_id": "SILT_LOAM"
                        },
                        {
                            "code": 19201,
                            "channel": 12002,
                            "depth": 20,
                            "field_capacity": 23,
                            "refill_point": 14,
                            "unit": "",
                            "node": "253772",
                            "calibration_id": "SILT_LOAM"
                        },
                        {
                            "code": 19201,
                            "channel": 12003,
                            "depth": 30,
                            "field_capacity": 23,
                            "refill_point": 14,
                            "unit": "",
                            "node": "253772",
                            "calibration_id": "SILT_LOAM"
                        },
                        {
                            "code": 19201,
                            "channel": 12004,
                            "depth": 40,
                            "field_capacity": 23,
                            "refill_point": 14,
                            "unit": "",
                            "node": "253772",
                            "calibration_id": "SILT_LOAM"
                        },
                        {
                            "code": 19201,
                            "channel": 12005,
                            "depth": 50,
                            "field_capacity": 23,
                            "refill_point": 14,
                            "unit": "",
                            "node": "253772",
                            "calibration_id": "SILT_LOAM"
                        },
                        {
                            "code": 19201,
                            "channel": 12006,
                            "depth": 60,
                            "field_capacity": 23,
                            "refill_point": 14,
                            "unit": "",
                            "node": "253772",
                            "calibration_id": "SILT_LOAM"
                        }
                    ]
                },
                "module": "SOIL_MOISTURE",
                "from": "2023-01-05T01:00:00+00:00",
                "to": "2023-12-23T01:00:00+00:00"
            }
        ],
        "irrigation_events": [
            {
                "title": "irrigation title",
                "from": "YYYY-MM-DDTHH:MM:SS+00:00",
                "to": "YYYY-MM-DDTHH:MM:SS+00:00",
                "duration": 60,
                "efficacy": 0.8,
                "type": "SPRINKLER",
                "amount": 10,
                "frequency": 24,
                "exceptions": []
            }
        ],
        "product_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "field": {
            "name": "field name",
            "id": "625edf1717eee784fd07feb5"
        },
        "farm": {
            "name": "farm name",
            "id": "625edf1717eee784fd07feb3"
        },
        "duplication_date": "YYYY-MM-DDTHH:MM:SS+00:00",
        "license_start_date": "YYYY-MM-DDTHH:MM:SS+00:00",
        "license_end_date": "YYYY-MM-DDTHH:MM:SS+00:00",
        "id": "626a45919dc74b586e09c2d5"
    },
    ...
]
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/crop-zones";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Get Cropzone by ID:

GET /crop-zones/{{CROPZONE-ID}}

Read specific cropzone of a user.

Specifications

Specification Value
method GET
request /crop-zones/{{CROPZONE-ID}}

URL Parameters

Value Optional/Required Options Description
CROPZONE-ID Required STRING Unique identifier of a cropzone

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 OK
401 Unauthorized

Response values

Values are self explanatory.

{
    "name": "Cropzone name",
    "from": "YYYY-MM-DDTHH:MM:SS+00:00",
    "to": "YYYY-MM-DDTHH:MM:SS+00:00",
    "crop_name": "Beans",
    "boundary": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                    15.614301811458757,
                    46.540910701449185
                ],
                [
                    15.614709507229021,
                    46.54108965850714
                ],
                [
                    15.614301811458757,
                    46.540910701449185
                ]
            ]
        ]
    },
    "cached_lai_stats": [],
    "cached_lai_values": [],
    "cached_ndvi_stats": [],
    "cached_ndvi_values": [],
    "soil": {
        "layers": [
            {
                "depth": 10,
                "field_capacity": 28,
                "refill_point": 14,
                "unit": "%"
            },
            {
                "depth": 20,
                "field_capacity": 28,
                "refill_point": 14,
                "unit": "%"
            },
            ...
        ],
        "root_restriction_depth": 2,
        "initial_soil_water_content": 0.4
    },
    "crop": {
        "id": "5a9d6990ecda8a0e1e68d00e",
        "emergence": "YYYY-MM-DDTHH:MM:SS+00:00",
        "fao56": {
            "K_ini": 0.5,
            "K_mid": 1.15,
            "K_end": 0.75,
            "L_ini": "YYYY-MM-DDTHH:MM:SS+00:00",
            "L_dev": "YYYY-MM-DDTHH:MM:SS+00:00",
            "L_mid": "YYYY-MM-DDTHH:MM:SS+00:00",
            "L_late": "YYYY-MM-DDTHH:MM:SS+00:00",
            "R_ini": 0.1
            "R_mid": 0.3
            "R_end": 0.6
        }
    },
    "rain_efficacies": [
        {
            "efficacy": "0.8",
            "lt": "5",
            "gte": "0"
        },
        {
            "efficacy": "0.7",
            "lt": "10",
            "gte": "5"
        },
        {
            "efficacy": "0.6",
            "lt": "999",
            "gte": "10"
        }
    ],
    "data_sources": [
        {
            "device_name": "002099E7",
            "device_id": 7,
            "source": {
                "channel": 5,
                "code": 6,
                "group": 5,
                "type": "SENSOR",
                "aggr": "SUM"
            },
            "module": "IRRIMET"
        },
        {
            "device_name": "002099E7",
            "device_id": 7,
            "source": {
                "id": "evapotranspiration",
                "type": "MODEL",
                "sensors": [
                    {
                        "group": 1,
                        "channel": 18,
                        "code": 506
                    },
                    {
                        "group": 2,
                        "channel": 19,
                        "code": 507
                    },
                    {
                        "group": 4,
                        "channel": 0,
                        "code": 600
                    },
                    {
                        "group": 6,
                        "channel": 4000,
                        "code": 16391
                    }
                ]
            },
            "module": "IRRIMET"
        },
        {
            "device_name": "002099E7",
            "device_id": 7,
            "source": {
                "type": "SOIL_MOISTURE_SENSOR_OR_PROBE",
                "group": 25,
                "layers": [
                    {
                        "code": 19201,
                        "channel": 12001,
                        "depth": 10,
                        "field_capacity": 23,
                        "refill_point": 14,
                        "unit": "",
                        "node": "253772",
                        "calibration_id": "SILT_LOAM"
                    },
                    {
                        "code": 19201,
                        "channel": 12002,
                        "depth": 20,
                        "field_capacity": 23,
                        "refill_point": 14,
                        "unit": "",
                        "node": "253772",
                        "calibration_id": "SILT_LOAM"
                    },
                    {
                        "code": 19201,
                        "channel": 12003,
                        "depth": 30,
                        "field_capacity": 23,
                        "refill_point": 14,
                        "unit": "",
                        "node": "253772",
                        "calibration_id": "SILT_LOAM"
                    },
                    {
                        "code": 19201,
                        "channel": 12004,
                        "depth": 40,
                        "field_capacity": 23,
                        "refill_point": 14,
                        "unit": "",
                        "node": "253772",
                        "calibration_id": "SILT_LOAM"
                    },
                    {
                        "code": 19201,
                        "channel": 12005,
                        "depth": 50,
                        "field_capacity": 23,
                        "refill_point": 14,
                        "unit": "",
                        "node": "253772",
                        "calibration_id": "SILT_LOAM"
                    },
                    {
                        "code": 19201,
                        "channel": 12006,
                        "depth": 60,
                        "field_capacity": 23,
                        "refill_point": 14,
                        "unit": "",
                        "node": "253772",
                        "calibration_id": "SILT_LOAM"
                    }
                ]
            },
            "module": "SOIL_MOISTURE",
            "from": "2023-01-05T01:00:00+00:00",
            "to": "2023-12-23T01:00:00+00:00"
        }
    ],
    "irrigation_events": [
        {
            "title": "irrigation title",
            "from": "YYYY-MM-DDTHH:MM:SS+00:00",
            "to": "YYYY-MM-DDTHH:MM:SS+00:00",
            "duration": 60,
            "efficacy": 0.8,
            "type": "SPRINKLER",
            "amount": 10,
            "frequency": 24,
            "exceptions": []
        }
    ],
    "product_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "field": {
        "name": "field name",
        "id": "625edf1717eee784fd07feb5"
    },
    "farm": {
        "name": "farm name",
        "id": "625edf1717eee784fd07feb3"
    },
    "duplication_date": "YYYY-MM-DDTHH:MM:SS+00:00",
    "license_start_date": "YYYY-MM-DDTHH:MM:SS+00:00",
    "license_end_date": "YYYY-MM-DDTHH:MM:SS+00:00",
    "id": "626a45919dc74b586e09c2d5"
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/crop-zones/{{CROPZONE-ID}}";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Get Cropzone of Field:

GET /farms/{{FARM-ID}}/fields/{{FIELD-ID}}/crop-zones

Read list of cropzones of a specific field.

Specifications

Specification Value
method GET
request /farms/{{FARM-ID}}/fields/{{FIELD-ID}}/crop-zones

URL Parameters

Value Optional/Required Options Description
FARM-ID Required STRING Unique identifier of a farm
FIELD-ID Required STRING Unique identifier of a field

Body & Schema

N/A

Response

Response codes

HTTP CODE Description
200 OK
401 Unauthorized

Response values

Values are self explanatory.

[
    {
        "name": "Cropzone name",
        "from": "YYYY-MM-DDTHH:MM:SS+00:00",
        "to": "YYYY-MM-DDTHH:MM:SS+00:00",
        "crop_name": "Beans",
        "boundary": {
            "type": "Polygon",
            "coordinates": [
                [
                    [
                        15.614301811458757,
                        46.540910701449185
                    ],
                    [
                        15.614709507229021,
                        46.54108965850714
                    ],
                    [
                        15.614301811458757,
                        46.540910701449185
                    ]
                ]
            ]
        },
        "cached_lai_stats": [],
        "cached_lai_values": [],
        "cached_ndvi_stats": [],
        "cached_ndvi_values": [],
        "soil": {
            "layers": [
                {
                    "depth": 10,
                    "field_capacity": 28,
                    "refill_point": 14,
                    "unit": "%"
                },
                {
                    "depth": 20,
                    "field_capacity": 28,
                    "refill_point": 14,
                    "unit": "%"
                },
                ...
            ],
            "root_restriction_depth": 2,
            "initial_soil_water_content": 0.4
        },
        "crop": {
            "id": "5a9d6990ecda8a0e1e68d00e",
            "emergence": "YYYY-MM-DDTHH:MM:SS+00:00",
            "fao56": {
                "K_ini": 0.5,
                "K_mid": 1.15,
                "K_end": 0.75,
                "L_ini": "YYYY-MM-DDTHH:MM:SS+00:00",
                "L_dev": "YYYY-MM-DDTHH:MM:SS+00:00",
                "L_mid": "YYYY-MM-DDTHH:MM:SS+00:00",
                "L_late": "YYYY-MM-DDTHH:MM:SS+00:00",
                "R_ini": 0.1
                "R_mid": 0.3
                "R_end": 0.6
            }
        },
        "rain_efficacies": [
            {
                "efficacy": "0.8",
                "lt": "5",
                "gte": "0"
            },
            {
                "efficacy": "0.7",
                "lt": "10",
                "gte": "5"
            },
            {
                "efficacy": "0.6",
                "lt": "999",
                "gte": "10"
            }
        ],
        "data_sources": [
            {
                "device_name": "002099E7",
                "device_id": 7,
                "source": {
                    "channel": 5,
                    "code": 6,
                    "group": 5,
                    "type": "SENSOR",
                    "aggr": "SUM"
                },
                "module": "IRRIMET"
            },
            {
                "device_name": "002099E7",
                "device_id": 7,
                "source": {
                    "id": "evapotranspiration",
                    "type": "MODEL",
                    "sensors": [
                        {
                            "group": 1,
                            "channel": 18,
                            "code": 506
                        },
                        {
                            "group": 2,
                            "channel": 19,
                            "code": 507
                        },
                        {
                            "group": 4,
                            "channel": 0,
                            "code": 600
                        },
                        {
                            "group": 6,
                            "channel": 4000,
                            "code": 16391
                        }
                    ]
                },
                "module": "IRRIMET"
            },
            {
                "device_name": "002099E7",
                "device_id": 7,
                "source": {
                    "type": "SOIL_MOISTURE_SENSOR_OR_PROBE",
                    "group": 25,
                    "layers": [
                        {
                            "code": 19201,
                            "channel": 12001,
                            "depth": 10,
                            "field_capacity": 23,
                            "refill_point": 14,
                            "unit": "",
                            "node": "253772",
                            "calibration_id": "SILT_LOAM"
                        },
                        {
                            "code": 19201,
                            "channel": 12002,
                            "depth": 20,
                            "field_capacity": 23,
                            "refill_point": 14,
                            "unit": "",
                            "node": "253772",
                            "calibration_id": "SILT_LOAM"
                        },
                        {
                            "code": 19201,
                            "channel": 12003,
                            "depth": 30,
                            "field_capacity": 23,
                            "refill_point": 14,
                            "unit": "",
                            "node": "253772",
                            "calibration_id": "SILT_LOAM"
                        },
                        {
                            "code": 19201,
                            "channel": 12004,
                            "depth": 40,
                            "field_capacity": 23,
                            "refill_point": 14,
                            "unit": "",
                            "node": "253772",
                            "calibration_id": "SILT_LOAM"
                        },
                        {
                            "code": 19201,
                            "channel": 12005,
                            "depth": 50,
                            "field_capacity": 23,
                            "refill_point": 14,
                            "unit": "",
                            "node": "253772",
                            "calibration_id": "SILT_LOAM"
                        },
                        {
                            "code": 19201,
                            "channel": 12006,
                            "depth": 60,
                            "field_capacity": 23,
                            "refill_point": 14,
                            "unit": "",
                            "node": "253772",
                            "calibration_id": "SILT_LOAM"
                        }
                    ]
                },
                "module": "SOIL_MOISTURE",
                "from": "2023-01-05T01:00:00+00:00",
                "to": "2023-12-23T01:00:00+00:00"
            }
        ],
        "irrigation_events": [
            {
                "title": "irrigation title",
                "from": "YYYY-MM-DDTHH:MM:SS+00:00",
                "to": "YYYY-MM-DDTHH:MM:SS+00:00",
                "duration": 60,
                "efficacy": 0.8,
                "type": "SPRINKLER",
                "amount": 10,
                "frequency": 24,
                "exceptions": []
            }
        ],
        "product_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "field": {
            "name": "field name",
            "id": "625edf1717eee784fd07feb5"
        },
        "farm": {
            "name": "farm name",
            "id": "625edf1717eee784fd07feb3"
        },
        "duplication_date": "YYYY-MM-DDTHH:MM:SS+00:00",
        "license_start_date": "YYYY-MM-DDTHH:MM:SS+00:00",
        "license_end_date": "YYYY-MM-DDTHH:MM:SS+00:00",
        "id": "626a45919dc74b586e09c2d5"
    },
    ...
]
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "GET";
$request = "/farms/{{FARM-ID}}/fields/{{FIELD-ID}}/crop-zones";

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Create Cropzone:

POST /farms/{{FARM-ID}}/fields/{{FIELD-ID}}/crop-zones

Create a cropzone for a specific field.

Specifications

Specification Value
method POST
request /farms/{{FARM-ID}}/fields/{{FIELD-ID}}/crop-zones

URL Parameters

Value Optional/Required Options Description
FARM-ID Required STRING Unique identifier of a farm
FIELD-ID Required STRING Unique identifier of a field

Body & Schema

Schema Function
schemas/CropZoneInsert.json cropzone creation schema

Response codes

HTTP CODE Description
201 Created successfully
400 Bad request
401 Unauthorized
403 Forbidden - user does not own farm or field

Response values

Values are self explanatory.

"64637ed6e870d33bbe0181f8"
{
  "title": "CropZone Insert Schema",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name",
    "from",
    "to",
    "crop_name",
    "boundary",
    "soil",
    "crop",
    "rain_efficacies",
    "data_sources",
    "irrigation_events"
  ],
  "properties": {
    "product_key": {
      "type": "string"
    },
    "name": {
      "type": "string",
      "maxLength": 50,
      "minLength": 3
    },
    "from": {
      "type": "string",
      "format": "date-time"
    },
    "to": {
      "type": "string",
      "format": "date-time"
    },
    "crop_name": {
      "type": "string",
      "maxLength": 50,
      "minLength": 3
    },
    "boundary": {
      "oneOf": [
        {
        "type": "null"
        },
        {
          "$ref": "Polygon.json"
        }
      ]
    },
    "soil": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "CropZoneSoil.json"
        }
      ]
    },
    "crop": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "CropZoneCrop.json"
        }
      ]
    },
    "rain_efficacies":  {
      "type": "array",
      "items": {
        "$ref": "CropZoneRainEfficacy.json"
      }
    },
    "data_sources": {
      "type": "array",
      "items": {
        "$ref": "CropZoneDataSource.json"
      }
    },
    "irrigation_events": {
      "type": "array",
      "items": {
        "$ref": "CropZoneIrrigationEvent.json"
      }
    },
    "yield_prediction": {
      "type": "array",
      "items": {
        "$ref": "CropZoneYieldPrediction.json"
      }
    }
  }
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "POST";
$request = "/farms/{{FARM-ID}}/fields/{{FIELD-ID}}/crop-zones";
// Body that you send needs to be JSON schema validated
$body    = [
    "name" => "farm_name",
    "from" => "2023-05-15T22:00:00.000Z",
    "to" => "2024-05-15T22:00:00.000Z",
    "boundary" => null,
    "crop" => null,
    "crop_name" => "barley",
    "data_sources" => [],
    "irrigation_events" => [],
    "product_key" => "976b7154-1950-43c3-b962-xxxxxxxxxxxx",
    "rain_efficacies" => [],
    "soil" => null
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt( $ch, CURLOPT_POST, TRUE );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $body );

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Update Cropzone:

PUT /farms/{{FARM-ID}}/fields/{{FIELD-ID}}/crop-zones/{{CROPZONE-ID}}

Update a cropzone of a user

Specifications

Specification Value
method PUT
request /farms/{{FARM-ID}}/fields/{{FIELD-ID}}/crop-zones/{{CROPZONE-ID}}

URL Parameters

Value Optional/Required Options Description
FARM-ID Required STRING Unique identifier of a farm
FIELD-ID Required STRING Unique identifier of a field
CROPZONE-ID Required STRING Unique identifier of a cropzone

Body & Schema

Schema Function
schemas/CropZoneUpdate.json Cropzone update schema

Response

Response codes

HTTP CODE Description
200 Success
204 No changes have been made
400 Validation errors
401 Unauthorized
403 Forbidden - User does not own the specified farm, field or cropzone
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method  = "PUT";
$request = "/farms/{{FARM-ID}}/fields/{{FIELD-ID}}/crop-zones/{{CROPZONE-ID}}";
// Body that you send needs to be JSON schema validated
$body    = [
  "name" => "farm_name",
  "from" => "2023-05-15T22:00:00+00:00",
  "to" => "2024-05-15T22:00:00+00:00",
  "boundary" => null,
  "crop" => null,
  "crop_name" => "barley",
  "data_sources" => [],
  "irrigation_events" => [],
  "product_key" => "976b7154-1950-43c3-b962-xxxxxxxxxxxx",
  "rain_efficacies" => [],
  "soil" => null
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;
{
  "title": "CropZone update Schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "product_key": {
      "type": "string"
    },
    "name": {
      "type": "string",
      "maxLength": 50,
      "minLength": 3
    },
    "from": {
      "type": "string",
      "format": "date-time"
    },
    "to": {
      "type": "string",
      "format": "date-time"
    },
    "crop_name": {
      "type": "string",
      "maxLength": 50,
      "minLength": 3
    },
    "boundary": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "Polygon.json"
        }
      ]
    },
    "soil": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "CropZoneSoil.json"
        }
      ]
    },
    "crop": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "CropZoneCrop.json"
        }
      ]
    },
    "rain_efficacies":  {
      "type": "array",
      "items": {
        "$ref": "CropZoneRainEfficacy.json"
      }
    },
    "data_sources": {
      "type": "array",
      "items": {
        "$ref": "CropZoneDataSource.json"
      }
    },
    "irrigation_events": {
      "type": "array",
      "items": {
        "$ref": "CropZoneIrrigationEvent.json"
      }
    },
    "yield_prediction": {
      "type": "array",
      "items": {
        "$ref": "CropZoneYieldPrediction.json"
      }
    },
    "distance": {
      "type": "number"
    }
  }
}
{
    "product_key": "976b7154-1950-43c3-b962-xxxxxxxxxxxx",
    "name": "new_cropzone_name",
    "from": "2023-05-15T22:00:00+00:00",
    "to": "2024-05-15T22:00:00+00:00",
    "crop_name": "barley",
    "boundary": null,
    "crop": null,
    "soil": null,
    "rain_efficacies": [],
    "data_sources": [],
    "irrigation_events": [],
    "yield_prediction": [],
    "distance": 30000
}

Get Sentinel Statistics:

POST /crop-zones/{{CROPZONE-ID}}/sentinel-statistics

Retrieve either the LAI (Leaf Area Index) or NDVI (Normalized Difference Vegetation Index) sentinel statistics for the specified cropzone.

Specifications

Specification Value
method POST
request /crop-zones/{{CROPZONE-ID}}/sentinel-statistics

URL Parameters

Value Optional/Required Options Description
CROPZONE-ID Required STRING Unique identifier of a device

Body & Schema

Schema Function
schemas/SentinelStatisticsBody.json Get sentinel statistics schema for either LAI or NDVI values

Response codes

HTTP CODE Description
200 Success
400 Bad Request
401 Unauthorized
403 No permissions
404 Cropzone not found

Response values

Values are self explanatory.

[
    // FOR Leaf Area Index:
    {
        "date": "2023-05-10",
        "cloud": {
            "min": 1,
            "max": 1,
            "mean": 1,
            "stDev": 0
        },
        "lai": {
            "min": 0.06071842461824417,
            "max": 0.07663551717996597,
            "mean": 0.06847049521862482,
            "stDev": 0.003535909468962207
        }
    },
    // FOR Normalized Difference Vegetation Index
    {
        "date": "2023-05-08",
        "cloud": {
            "min": 1,
            "max": 1,
            "mean": 1,
            "stDev": 0
        },
        "ndvi": {
            "min": -0.026920422911643982,
            "max": 0.06040268391370773,
            "mean": 0.019586276523740273,
            "stDev": 0.01680108997934394
        }
    },
    ...
]
{
    "title": "Sentinel statistics request Schema",
    "type": "object",
    "additionalProperties": false,
    "required": [
      "resolution",
      "type"
    ],
    "properties": {
      "resolution": {
        "type": "number",
        "minimum": 0,
        "maximum": 500
      },
      "type": {
        "oneOf": [
            {
                "type": "string",
                "enum": [ "LAI", "lai", "NDVI", "ndvi" ]
            }
        ]
        
      }
    }
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "POST";
$request = "/crop-zones/{{CROPZONE-ID}}/sentinel-statistics";
// Body that you send needs to be JSON schema validated
$body    = [
    "resolution" => 30,
    "type" => "LAI"
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt( $ch, CURLOPT_POST, TRUE );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $body );

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Get Fitting Curve:

POST /crop-zones/{{CROPZONE-ID}}/fitting-curve

Retrieve the fittinge curve from either the LAI (Leaf Area Index) or NDVI (Normalized Difference Vegetation Index) sentinel statistics of the specified cropzone.

Specifications

Specification Value
method POST
request /crop-zones/{{CROPZONE-ID}}/fitting-curve

URL Parameters

Value Optional/Required Options Description
CROPZONE-ID Required STRING Unique identifier of a device

Body & Schema

Schema Function
schemas/FittingCurveBody.json Get fitting curve of sentinel statistics schema

Response codes

HTTP CODE Description
200 Success
401 Unauthorized
403 No permissions
404 Cropzone not found

Response values

Values are self explanatory.

{
    "data": [
        {
            "x": 2.5,
            "y": 0.42330168290291814
        },
        {
            "x": 3.5,
            "y": 0.42330168290291814
        },
        {
            "x": 4.5,
            "y": 0.42330168290291814
        },
        {
            "x": 5.5,
            "y": 0.42330168290291814
        },
        {
            "x": 6.5,
            "y": 0.42330168290291814
        },
        {
            "x": 7.5,
            "y": 0.42330168290291814
        }, ...
    ],
    "redchi": 0.019717533978678977
}
{
    "title": "Fitting Curve Schema",
    "type": "object",
    "additionalProperties": false,
    "required": [
      "data",
      "type"
    ],
    "properties": {
      "data": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "cloud": {
              "type": "object",
              "properties": {
                "min": {
                  "type": "number"
                },
                "max": {
                  "type": "number"
                },
                "mean": {
                  "type": "number"
                },
                "stDev": {
                  "type": "number"
                }
              }
            },
            "date": {
              "format": "date"
            },
            "lai": {
              "type": "object",
              "properties": {
                "min": {
                  "type": "number"
                },
                "max": {
                  "type": "number"
                },
                "mean": {
                  "type": "number"
                },
                "stDev": {
                  "type": "number"
                }
              },
              "required": ["min", "max", "mean", "stDev"],
              "dependencies": {
                "ndvi": {
                  "not": {
                    "required": ["lai"]
                  }
                }
              }
            },
            "ndvi": {
              "type": "object",
              "properties": {
                "min": {
                  "type": "number"
                },
                "max": {
                  "type": "number"
                },
                "mean": {
                  "type": "number"
                },
                "stDev": {
                  "type": "number"
                }
              },
              "required": ["min", "max", "mean", "stDev"],
              "dependencies": {
                "lai": {
                  "not": {
                    "required": ["ndvi"]
                  }
                }
              }
            }
          },
          "oneOf": [
            {
              "required": ["lai"],
              "not": {
                "required": ["ndvi"]
              }
            },
            {
              "required": ["ndvi"],
              "not": {
                "required": ["lai"]
              }
            }
          ],
          "required": ["cloud", "date"]
        }
      },
      "type": {
        "type": "string",
        "enum": ["LAI", "lai", "NDVI", "ndvi"]
      }
    }
  }
  
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "POST";
$request = "/crop-zones/{{CROPZONE-ID}}/fitting-curve";
// Body that you send needs to be JSON schema validated
$body    = [
    "data" => [
        [
            "cloud" => [
                "min" => 0,
                "max" => 0,
                "mean" => 0,
                "stDev" => 0
            ],
            "date" => "2023-05-07",
            "ndvi" => [
                "min" => 0.8203737139701843,
                "max" => 4.738396644592285,
                "mean" => 1.6806123194694513,
                "stDev" => 0.5278388234312482
            ]
        ],
        [
            "cloud" => [
                "min" => 0,
                "max" => 0,
                "mean" => 0,
                "stDev" => 0
            ],
            "date" => "2023-05-05",
            "ndvi" => [
                "min" => 0.7168576121330261,
                "max" => 4.701280117034912,
                "mean" => 1.9682491116523742,
                "stDev" => 0.4608035214462633
            ]
        ],
        [
            "cloud" => [
                "min" => 0,
                "max" => 0,
                "mean" => 0,
                "stDev" => 0
            ],
            "date" => "2023-04-27",
            "ndvi" => [
                "min" => 0.6236867308616638,
                "max" => 3.54347825050354,
                "mean" => 1.356145232200622,
                "stDev" => 0.3287475461504505
            ]
        ],
        [
            "cloud" => [
                "min" => 0,
                "max" => 0,
                "mean" => 0,
                "stDev" => 0
            ],
            "date" => "2023-04-20",
            "ndvi" => [
                "min" => 0.5432727336883545,
                "max" => 4.080946445465088,
                "mean" => 1.5180718364715575,
                "stDev" => 0.48235261291138143
            ]
        ],
        [
            "cloud" => [
                "min" => 0,
                "max" => 0,
                "mean" => 0,
                "stDev" => 0
            ],
            "date" => "2023-04-07",
            "ndvi" => [
                "min" => 0.34423547983169556,
                "max" => 0.5037468671798706,
                "mean" => 0.4272834968566893,
                "stDev" => 0.029341276465697286
            ]
        ],
        [
            "cloud" => [
                "min" => 0,
                "max" => 0,
                "mean" => 0,
                "stDev" => 0
            ],
            "date" => "2023-04-05",
            "ndvi" => [
                "min" => 0.5129870176315308,
                "max" => 3.1946473121643066,
                "mean" => 1.463275423049926,
                "stDev" => 0.38614863473463307
            ]
        ],
        [
            "cloud" => [
                "min" => 0,
                "max" => 0,
                "mean" => 0,
                "stDev" => 0
            ],
            "date" => "2023-03-18",
            "ndvi" => [
                "min" => 0.35564854741096497,
                "max" => 1.8071495294570923,
                "mean" => 0.8426461148262027,
                "stDev" => 0.1980161228848823
            ]
        ],
        [
            "cloud" => [
                "min" => 0,
                "max" => 0,
                "mean" => 0,
                "stDev" => 0
            ],
            "date" => "2023-03-16",
            "ndvi" => [
                "min" => 0.43110236525535583,
                "max" => 2.160433053970337,
                "mean" => 1.0767034132480624,
                "stDev" => 0.24976066545097986
            ]
        ],
        [
            "cloud" => [
                "min" => 0,
                "max" => 0,
                "mean" => 0,
                "stDev" => 0
            ],
            "date" => "2023-03-13"",
            "ndvi" => [
                "min" => 0.3871999979019165,
                "max" => 1.418410062789917,
                "mean" => 0.6944776844978335,
                "stDev" => 0.13765869336954994
            ]
        ],
        [
            "cloud" => [
                "min" => 0,
                "max" => 0,
                "mean" => 0,
                "stDev" => 0
            ],
            "date" => "2023-03-11"",
            "ndvi" => [
                "min" => 0.241590216755867,
                "max" => 0.6233023405075073,
                "mean" => 0.4905939499139787,
                "stDev" => 0.05163162621348635
            ]
        ],
        [
            "cloud" => [
                "min" => 0,
                "max" => 0,
                "mean" => 0,
                "stDev" => 0
            ],
            "date" => "2023-03-03"",
            "ndvi" => [
                "min" => 0.16855429112911224,
                "max" => 0.46921443939208984,
                "mean" => 0.2685050587654113,
                "stDev" => 0.0550561746999114
            ]
        ],
        [
            "cloud" => [
                "min" => 0,
                "max" => 0,
                "mean" => 0,
                "stDev" => 0
            ],
            "date" => "2023-02-24"",
            "ndvi" => [
                "min" => 0.26081082224845886,
                "max" => 0.46561750769615173,
                "mean" => 0.3462496666908264,
                "stDev" => 0.02782796554263813
            ]
        ],
        [
            "cloud" => [
                "min" => 0,
                "max" => 0,
                "mean" => 0,
                "stDev" => 0
            ],
            "date" => "2023-02-21"",
            "ndvi" => [
                "min" => 0.3144981265068054,
                "max" => 0.5865257382392883,
                "mean" => 0.43720595288276676,
                "stDev" => 0.03107848066279827
            ]
        ],
        [
            "cloud" => [
                "min" => 0,
                "max" => 0,
                "mean" => 0,
                "stDev" => 0
            ],
            "date" => "2023-02-19"",
            "ndvi" => [
                "min" => 0.22007721662521362,
                "max" => 0.6000000238418579,
                "mean" => 0.4428697912693021,
                "stDev" => 0.03941568041029631
            ]
        ]
    ],
    "type" => "NDVI"
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt( $ch, CURLOPT_POST, TRUE );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $body );

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;

Get Sentinel Values:

POST /crop-zones/{{CROPZONE-ID}}/sentinel-values

Retrieve sentinel values from satellites for the specified cropzone.

Specifications

Specification Value
method POST
request /crop-zones/{{CROPZONE-ID}}/sentinel-values

URL Parameters

Value Optional/Required Options Description
CROPZONE-ID Required STRING Unique identifier of a device

Body & Schema

Schema Function
schemas/SentinelValuesBody.json Get sentinel values schema

Response codes

HTTP CODE Description
200 Success
400 Bad Request
401 Unauthorized
403 No permissions
404 Cropzone not found

Response values

Values are self explanatory.

[
    {
        "date": "2023-04-27",
        "resolution": 15,
        "result": {
            "features": [
                {
                    "geometry": {
                        "type": "MultiPolygon",
                        "coordinates": [
                            [
                                [15.648704, 47.215436],
                                [15.648704, 47.215303],
                                [15.648498, 47.215303],
                                [15.648498, 47.215169],
                                ...,
                                [15.648704, 47.215436]
                            ],
                            ...
                        ]
                    },
                    "properties" {
                        // Either property "ndvi" or "lai" !!
                        "ndvi": 0.6
                    },
                    "type": "Feature"
                },
                ...
            ],
            "type": "FeatureCollection"
        }
    },
    ...
]
{
    "title": "Sentinel statistics body Schema",
    "type": "object",
    "additionalProperties": false,
    "required": [
      "dates",
      "getBestResolution",
      "resolution",
      "type"
    ],
    "properties": {
      "dates": {
        "type": "array",
        "items": {
            "format": "date"
        }
      },
      "getBestResolution": {
        "type": "boolean"
      },
      "resolution": {
        "type": "number",
        "minimum": 0,
        "maximum": 500
      },
      "type": {
        "oneOf": [
            {
                "type": "string",
                "enum": [ "LAI", "lai", "NDVI", "ndvi" ]
            }
        ]
        
      }
    }
}
// Clients public and private key provided by service provider
$public_key = "PROVIDED BY SERVICE PROVIDER";
$private_key = "PROVIDED BY SERVICE PROVIDER";

// Define the request parameter's
$method = "POST";
$request = "/crop-zones/{{CROPZONE-ID}}/sentinel-values";
// Body that you send needs to be JSON schema validated
$body    = [
    "dates" => 
    "resolution" => 30,
    "type" => "LAI"
];
$body = json_encode( $body );

$timestamp = gmdate('D, d M Y H:i:s T'); // Date as per RFC2616 - Wed, 25 Nov 2014 12:45:26 GMT

// Creating content to sign with private key
$content_to_sign = $method.$request.$timestamp.$public_key;

// Hash content to sign into HMAC signature
$signature = hash_hmac("sha256", $content_to_sign, $private_key);

// Add required headers
// Authorization: hmac public_key:signature
// Date: Wed, 25 Nov 2014 12:45:26 GMT
$headers = [
    "Accept: application/json",
    "Authorization: hmac {$public_key}:{$signature}",
    "Date: {$timestamp}"
];

// Prepare and make https request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.fieldclimate.com/THIS-VERSION" . $request);
// SSL important
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt( $ch, CURLOPT_POST, TRUE );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $body );

$output = curl_exec($ch);
curl_close($ch);

// Parse response as json and work on it ..
echo $output. PHP_EOL;