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

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
  • 50 = uMetos
  • 51 = uMetos NBIoT
  • 52 = uMetos LoRa
  • 70 = CropVIEW
  • 71 = CropVIEW Zoom
  • 72 = iSCOUT
  • 73 = CropVIEW Panorama

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;
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();
        }
    }
}

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_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 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);
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 - 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"]}

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']}

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.

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.

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.

[
    {
        "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": "PATH-TO-THE-PNG-IMAGE",
        "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.

[
    {
        "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": "PATH-TO-THE-PNG-IMAGE",
        "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;
  • More coming soon...
  • ROUTES - DEV

    If you are using OAuth 2.0 you are able to define multiple applications and register users to them. This enables you to overview/manage
    your applications, users and stations.

    If user belong to your application you are able to access their station information/data so you can offer support or consulting ... But remember that you are not able to modify the user itself or any other information that is considered private.

    NOTE: This routes are only available if you are using OAuth 2.0 as authentication method

    Schemas

    Schema Function
    schemas/UserInsert.json Register new account
    schemas/UserStationInsert.json Adding station to account
    schemas/UserPasswordReset.json New password reset request
    schemas/UserPasswordUpdate.json Password reset

    Routes

    HTTP Method Endpoint URL Params Function
    GET /dev/applications N/A List of applications
    GET /dev/users/{{APP-ID}} APP-ID List of users of a application
    GET /dev/stations/{{APP-ID}} APP-ID Stations of a application
    GET /dev/user/{{USERNAME}}/stations USERNAME List of user stations
    POST /dev/user/{{USERNAME}}/{{STATION-ID}}/{{STATION-KEY}} USERNAME, STATION-ID, STATION-KEY Adding new station to user
    DELETE /dev/user/{{USERNAME}}/{{STATION-ID}} USERNAME, STATION-ID Remove station from user
    POST /dev/user/{{APP-ID}} APP-ID Register new user to application
    GET /dev/user/activate/{{ACTIVATION-KEY}} ACTIVATION-KEY Activate registered user account
    POST /dev/user/{{APP-ID}}/password-reset APP-ID Request password reset
    POST /dev/user/{{APP-ID}}/password-update/{{PASSWORD-KEY}} APP-ID, PASSWORD-KEY Change password

    URL Parameters

    Value Optional/Required Options Description
    APP-ID Required STRING Unique identifier of a application
    USERNAME Required STRING Account username
    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
    ACTIVATION-KEY Required STRING Temporary activation key to activate account
    PASSWORD-KEY Required STRING Temporary password key to change password

    List of applications:

    GET /dev/applications

    Reading the list of applications.

    Specifications

    Specification Value
    method GET
    request /dev/applications

    URL Parameters

    N/A

    Body & Schema

    N/A

    Response

    Response codes

    HTTP CODE Description
    200 Success
    204 No Applications
    401 Unauthorized
    403 Forbidden

    Response values

    Values are self explanatory.

    [
        "App name 1",
        "App name 2",...
    ]
    // 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 = "/dev/applications";
    
    $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;

    Application users:

    GET /dev/users/{{APP-ID}}

    Reading list users in the specified application.

    Specifications

    Specification Value
    method GET
    request /dev/users/{{APP-ID}}

    URL Parameters

    Value Optional/Required Options Description
    APP-ID Required STRING Unique identifier of a application

    Body & Schema

    N/A

    Response

    Response codes

    HTTP CODE Description
    200 Success
    204 You have no users for specified application
    401 Unauthorized
    403 Forbidden

    Response values

    Values are self explanatory.

    [
        {
            "username": "USERNAME",
            "usercode": NUMBER,
            "salt": "",
            "info": {
                "name": "",
                "lastname": "",
                "title": null,
                "email": "EMAIL",
                "phone": null,
                "cellphone": null,
                "fax": null
            },
            "company": {
                "name": "",
                "profession": "",
                "department": "",
                "customer_id": null,
                "vat_id": null
            },
            "address": {
                "street": "",
                "city": "",
                "district": "",
                "zip": NUMBER,
                "country": ""
            },
            "settings": {
                "language": "en"
            },
            "stations": [],
            "activate_token": "",
            "create_time": "",
            "last_access": ""
        },
        {
            "username": "USERNAME",
            "usercode": NUMBER,
            "salt": "",
            "info": {
                "name": "",
                "lastname": "",
                "title": null,
                "email": "EMAIL",
                "phone": null,
                "cellphone": null,
                "fax": null
            },
            "company": {
                "name": "",
                "profession": "",
                "department": "",
                "customer_id": null,
                "vat_id": null
            },
            "address": {
                "street": "",
                "city": "",
                "district": "",
                "zip": NUMBER,
                "country": ""
            },
            "settings": {
                "language": "en"
            },
            "stations": [],
            "activate_token": "",
            "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 = "/dev/users/{{APP-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;

    Application stations:

    GET /dev/stations/{{APP-ID}}

    Reading list of station in the Application.

    Specifications

    Specification Value
    method GET
    request /dev/stations/{{APP-ID}}

    URL Parameters

    Value Optional/Required Options Description
    APP-ID Required STRING Unique identifier of a application

    Body & Schema

    N/A

    Response

    Response codes

    HTTP CODE Description
    200 Success
    204 You have no stations for specified application
    401 Unauthorized
    403 Forbidden

    Response values

    Values are self explanatory.

    [
        {
            "name": {
                "original": STRING
            },
            "rights": STRING,
            "info": {
                "device_id": "",
                "device_name": "",
                "uid": "",
                "firmware": "",
                "hardware": "",
                "description": "",
                "max_time": ""
            },
            "dates": {
                "min_date": "",
                "max_date": "",
                "created_at": "",
                "last_communication": ""
            },
            "position": {
                "geo": {
                    "coordinates": [
                        NUMBER,
                        NUMBER
                    ]
                },
                "altitude": NUMBER
            },
            "config": {
                "timezone_offset": NUMBER,
                "dst": false,
                "precision_reduction": NUMBER,
                "scheduler": NUMBER,
                "fixed_transfer_interval": NUMBER,
                "rain_monitor": NUMBER,
                "water_level_monitor": NUMBER,
                "data_interval": NUMBER,
                "activity_mode": NUMBER,
                "measuring_interval": NUMBER,
                "logging_interval": NUMBER
            },
            "networking": {
                "mnc": "",
                "mcc": "",
                "apn": null,
                "username": null,
                "password": null,
                "country": "",
                "provider": "",
                "type": "",
                "imei": null,
                "simid": null
            },
            "warnings": {
                "sms_numbers": [],
                "sensors": [
                    "",
                    "",
                    "",
                    "",
                    ""
                ]
            },
            "flags": {
                "imeteopro": false
            },
            "users": [
                ...
            ]
        },..
    ]
    // 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 = "/dev/stations/{{APP-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;

    User stations:

    GET /dev/user/{{USER-ID}}/stations

    Reading list of station in the Application.

    Specifications

    Specification Value
    method GET
    request /dev/user/{{USER-ID}}/stations

    URL Parameters

    Value Optional/Required Options Description
    USER-ID Required STRING Unique identifier of a user

    Body & Schema

    N/A

    Response

    Response codes

    HTTP CODE Description
    200 Success
    204 You have no stations for specified user
    401 Unauthorized
    403 Forbidden

    Response values

    Values are self explanatory.

    [
        {
            "name": {
                "original": STRING
            },
            "rights": STRING,
            "info": {
                "device_id": "",
                "device_name": "",
                "uid": "",
                "firmware": "",
                "hardware": "",
                "description": "",
                "max_time": ""
            },
            "dates": {
                "min_date": "",
                "max_date": "",
                "created_at": "",
                "last_communication": ""
            },
            "position": {
                "geo": {
                    "coordinates": [
                        NUMBER,
                        NUMBER
                    ]
                },
                "altitude": NUMBER
            },
            "config": {
                "timezone_offset": NUMBER,
                "dst": false,
                "precision_reduction": NUMBER,
                "scheduler": NUMBER,
                "fixed_transfer_interval": NUMBER,
                "rain_monitor": NUMBER,
                "water_level_monitor": NUMBER,
                "data_interval": NUMBER,
                "activity_mode": NUMBER,
                "measuring_interval": NUMBER,
                "logging_interval": NUMBER
            },
            "networking": {
                "mnc": "",
                "mcc": "",
                "apn": null,
                "username": null,
                "password": null,
                "country": "",
                "provider": "",
                "type": "",
                "imei": null,
                "simid": null
            },
            "warnings": {
                "sms_numbers": [],
                "sensors": [
                    "",
                    "",
                    "",
                    "",
                    ""
                ]
            },
            "flags": {
                "imeteopro": false
            },
            "users": [
                ...
            ]
        },..
    ]
    // 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 = "/dev/user/{{USER-ID}}/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;

    Add station to user:

    POST /dev/user/{{USERNAME}}/{{STATION-ID}}/{{STATION-KEY}}

    Adding station to user account that belongs to your application. 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 /dev/user/{{USERNAME}}/{{STATION-ID}}/{{STATION-KEY}}

    URL Parameters

    Value Optional/Required Options Description
    USERNAME Required STRING User name of a user that belongs to your application
    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 Forbidden - Station id or key is incorrect

    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 = "/dev/user/{{USERNAME}}/{{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 user:

    DELETE /dev/user/{{USERNAME}}/{{STATION-ID}}

    Removing station from account that belongs to your application.

    Specifications

    Specification Value
    method DELETE
    request /dev/user/{{USERNAME}}/{{STATION-ID}}

    URL Parameters

    Value Optional/Required Options Description
    USERNAME Required STRING Username of account that belongs to your application
    STATION-ID Required STRING Unique identifier 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

    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 = "/dev/user/{{USERNAME}}/{{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);
    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;

    Register a user to a application:

    POST /dev/user/{{APP-ID}}

    Register a new user to your application. Activation key is returned after successful registration.
    By default account is blocked and activation key has to be used to activate it. To do so
    you need to design a process of account activation (send email to a client with link to activate his account).
    To finish the process of activation on your side all you need to do is call /dev/user/activate/{{ACTIVATION-KEY}}.

    Activation key is being used for identity validation.

    Specifications

    Specification Value
    method POST
    request /dev/user/{{APP-ID}}

    URL Parameters

    Value Optional/Required Options Description
    APP-ID Required STRING Unique identifier of a application

    Body & Schema

    Schema Function
    schemas/UserInsert.json Register new account

    Response

    Response codes

    HTTP CODE Description
    200 Success
    400 Validation errors
    401 Unauthorized
    403 Forbidden
    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  = "POST";
    $request = "{{api}}/dev/user/{{APP-ID}}";
    // Body that you send needs to be JSON schema validated
    $body    = [
        "username" => "USERNAME",
        "password" => "PASSWORD",
        "info" => [
            "name" => "",
            "lastname" => "",
            "title" => "",
            "email"=>  "",
            "phone" => "",
            "cellphone" => "",
            "fax" => ""
        ],
        "company"  => [
            "name" => "",
            "profession" =>  "",
            "department" =>  "",
            "customer_id" => "",
            "vat_id" =>  ""
        ],
        "address" => [
            "street" => "",
            "city" => "",
            "district" => "",
            "zip" => "",
            "country" =>  ""
        ],
        "settings" =>  [
            "language"  =>  "en",
            "newsletter" =>  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;
    {
      "title": "User Insert Schema",
      "type": "object",
      "properties": {
        "username": {
          "type": "string",
          "pattern": "(*UTF8)^[[:alnum:]]+(?:[-_ ]?[[:alnum:]]+)*$",
          "description": "Chars, Numbers, space, _, - but no other special chars"
        },
        "password": {
          "type": "string",
          "minLength": 4,
          "description": "Password"
        },
        "old_password": {
          "type": "string",
          "description": "For old Fieldclimate send password without encoding. Temporary solution."
        },
        "info": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "lastname": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "email": {
              "type": "string",
              "format": "email"
            },
            "phone": {
              "type": "string"
            },
            "cellphone": {
              "type": "string"
            },
            "fax": {
              "type": "string"
            }
          },
          "required": [
            "name",
            "lastname",
            "email"
          ],
          "additionalProperties": false,
          "description": "Data updated as whole object will overwrite whole set in database"
        },
        "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": {
          "type": "object",
          "properties": {
            "street": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "district": {
              "type": "string"
            },
            "zip": {
              "type": "string"
            },
            "country": {
              "type": "string"
            }
          },
          "required": [
            "country"
          ],
          "additionalProperties": false,
          "description": "Data updated as whole object will overwrite whole set in database"
        },
        "settings": {
          "type": "object",
          "properties": {
            "language": {
              "type": "string",
              "pattern": "^[a-z]{2,2}$"
            },
            "newsletter": {
              "type": "boolean"
            }
          },
          "required": [
            "language"
          ],
          "additionalProperties": false,
          "description": "Language has to be in ISO 639-1 format. Data updated as whole object will overwrite whole set in database"
        }
      },
      "required": [
        "username",
        "password",
        "info",
        "settings"
      ],
      "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"
    }
    {
        "username" : "Username",
        "password" : "Password",
        "info" : {
            "name" : "Name",
            "lastname" : "Last name",
            "email":  "Email"
        },
        "settings" :  {
            "language" : "en",
            "newsletter": true
        }
    }

    Activate registered user account:

    GET /dev/user/activate/{{ACTIVATION-KEY}}

    Activate registered user account after the call /dev/user/{{APP-ID}} from which you will
    receive activation key upon successful registration.

    Specifications

    Specification Value
    method GET
    request /dev/user/activate/{{ACTIVATION-KEY}}

    URL Parameters

    Value Optional/Required Options Description
    ACTIVATION-KEY Required STRING Temporary activation key to activate account

    Body & Schema

    N/A

    Response

    Response codes

    HTTP CODE Description
    200 Success
    401 Unauthorized
    403 Forbidden

    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 = "GET";
    $request = "/user/activate/{{ACTIVATION-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);
    
    $output = curl_exec($ch);
    curl_close($ch);
    
    // Parse response as json and work on it ..
    echo $output. PHP_EOL;

    New password request:

    POST /dev/user/{{APP-ID}}/password-reset

    Requesting application to change password of a user that belongs to your application.
    Password key is returned which is used to change old password with new one. Intended process is that password key is send to users email in combination with URL and then user is able to change his password by following the URL.
    When user follows the URL back to your site all you need to do is proceed with call /dev/user/{{APP-ID}}/password-update/{{PASSWORD-KEY}} which enables password change.

    Password key is used for validation of identity.

    Specifications

    Specification Value
    method POST
    request /dev/user/{{APP-ID}}/password-reset

    URL Parameters

    Value Optional/Required Options Description
    APP-ID Required STRING Unique identifier of a application

    Body & Schema

    Schema Function
    schemas/UserPasswordReset.json New password reset request

    Response

    Response codes

    HTTP CODE Description
    200 Success
    400 Validation errors
    401 Unauthorized
    403 Forbidden - Station id or key is incorrect
    404 User does not exist

    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 = "/dev/user/{{APP-ID}}/password-reset";
    // Body that you send needs to be JSON schema validated
    $body    = [
        "username" => "Username of account you wish to reset"
    ];
    $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 password reset",
      "description": "Reset a password for specific user",
      "type": "object",
      "properties": {
        "username": {
          "type": "string",
          "pattern": "(*UTF8)^[[:alnum:]]+(?:[-_ ]?[[:alnum:]]+)*$",
          "description": "Chars, Numbers, space, _, - but no other special chars"
        }
      },
      "additionalProperties": false
    }
    {
    	"username":"Username"
    }

    Setting new password:

    POST /dev/user/{{APP-ID}}/password-update/{{PASSWORD-KEY}}

    Changing password of user account. You need to acquire password key from call /dev/user/{{APP-ID}}/password-reset.

    Specifications

    Specification Value
    method POST
    request /dev/user/{{APP-ID}}/password-update/{{PASSWORD-KEY}}

    URL Parameters

    Value Optional/Required Options Description
    APP-ID Required STRING Unique identifier of a application
    PASSWORD-KEY Required STRING Temporary password key to change password

    Body & Schema

    Schema Function
    schemas/UserPasswordUpdate.json Password reset

    Response

    Response codes

    HTTP CODE Description
    200 Success
    400 Validation errors
    401 Unauthorized
    403 Forbidden

    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 = "/user/{{APP-ID}}/password-update/{{PASSWORD-KEY}}";
    // Body that you send needs to be JSON schema validated
    $body    = [
        "password" => "Password",
        "password_repeat" => "Password repeat"
    ];
    $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 password update",
      "description": "Update user password",
      "type": "object",
      "properties": {
        "password": {
          "type": "string",
          "minLength": 4,
          "description": "Password"
        },
        "password_repeat": {
          "type": "string",
          "minLength": 4,
          "description": "Repeat Password"
        }
      },
      "additionalProperties": false
    }
    {
    	"password":"Password",
    	"password_repeat": "Password repeat"
    }