K. API

Intro

This section is only for developers who would like to built-in Meteotemplate updates to their software or for people who build their own station and want to update the Meteotemplate database using the API HTTP request.

Meteotemplate API enables sending data to the template. Because Meteotemplate uses its own database, it can calculate all the statistics itslef and so values needed for the API are always just the current conditions. Some of these are saved to the database, others might only be used by some blocks and plugins.

All values should be passed to the API as an HTTP request and will be accepted by the API using as a _GET variable.

The user will always have to specify just two things, which you must take into account when sending the HTTP request - the path to the template root folder (depending on where on their server the template files are located), the password they specified in the template Main settings, which is essential for authentication.

The Entry point is located at templateRoot/api.php

If any of the parameters are not available (sensor currently not reporting, sensor not available at all, your SW does not log this etc.), then simply omit the corresponding parameter from the URL. The request always has to include the password and timestamp (essential variables, see below), others are optional, but at least one variable should be passed in addition to just date/time. The script will do some validation, so even passing an unrealistic value such as -999 will prevent the value from being worked with later. Order of parameters in the URL is irrelevant.
Decimal separator should always be a dot (.)

In case data is correctly received you will get "Success". In case there is some problem the returned output will be different from Success and say what the error was, so ideally set your SW to accept "Success" and in case this is not received, just show "Error:" and the returned message, which could be for example "Unauthorized", "No password provided" etc.

Parameters

Essential

Parameter	Name	Units	Description
U	timestamp		UTC UNIX timestamp. This corresponds to the number of seconds elapsed since Jan 1, 1970 00:00 UTC.
PASS	password		This is the password used for authentication. This password is specified in the template Main settings and referred to as the update password. It should not include any special characters such as a slash (/) or a space, which could cause problems when passed in the URL. This is not the password used to access the template control panel (the admin password), which is hashed using B-crypt and much more secure.

Parameters

When your request is authenticized, the passed input is saved into a text file. This text file is then used by the corresponding blocks and plugins. In addition, some variables are saved to the database. The database update interval is 5 minutes. This is the ideal compromise between data accuracy and database speed. For some variables, the database has several columns (temperature, wind) so that also extremes can be logged (min/max).

The interval at which the request is sent is not fixed, but must be less than or equal to 5 minutes. At this point I will explain how the script works. First thing is saving the text file with the current values. This is used by other scripts and is assumed to contain the current conditions. In the next part of the script, the script compares the current passed timestamp with the last database update. There are two possible cases - 5 minutes has not yet elapsed - in this case the current sent data set is saved to a temporary cache file. In case it is time for database update (5 minutes elapsed), the script will take the currently passed values, look if there are some cached data sets from the last 5 minutes and processes this data, inserts to database and empties the cache file.

To make sure that all extremes are logged and data accurate, it is important that the data aggregation corresponds to the interval between the requests. In other words - if the API expects average temperature, it should be the average temperature from the interval since you last sent a request. Likewise, a maximum temperature means the maximum observed value from the last time a request was sent.

Theoretically it is possible to only send data every 5 minutes (send the average, max etc. from the last 5 minutes). This will work perfectly fine, however, in such case, the scripts that display current conditions, and unlike most of the other scripts, do not use the database, but rather get data directly from the text file overwritten with each request, would also show data in 5 minute intervals. For this reason, it is better to use a shorter interval, where these current conditions showing scripts will take the latest data received and database updates will use the caching mechanism to update the database every 5 minutes.

The API also supports "package data" - you can send data from different sensors at different intervals, there always has to be a timestamp, but if for example you send wind at 10s intervals and temperature 30s, this will work fine and the API script will aggregate the data sets and always show the most recent values available for each parameter.

If the request is sent upon each new data set received from the station, then obviously, the max/min/avg values for the individual parameters would be equal and calculated by the template update script when processing the cache file. This is possible to do, however it depends on the interval. As mentioned above, there is no set minimum interval, however one should consider the associated server load if the requests are too frequent - I personally would not recommend using anything shorter than 30 seconds.

Parameter	Name	Units	Description
T	temperature	°C	average temperature from the primary thermometer
TMX	maximum temperature	°C	maximum temperature measured using the primary thermometer (i.e. the maximum value since last request was sent)
TMN	minimum temperature	°C	minimum temperature measured using the primary thermometer (i.e. the minimum value since last request was sent)
H	relative humidity	%	average relative humidity from the primary humidity sensor
P	barometric pressure	hPa (mbar)	average barometric pressure (normalized to sea level)
W	wind speed	km/h	average wind speed
G	wind gust	km/h	maximum wind speed
B	wind direction	°	average wind direction (bearing), a value between 0 and 359
R	rainfall	mm	daily cumulative rainfall (since midnight)
RR	rain rate	mm/h	average current rain rate
S	solar radiation	W/m2	average solar radiation
UV	UV index
SS	sunshine	h	total sunshine hours today (since midnight)
CC	cloud cover	%
TIN	indoor temperature	°C	average indoor temperature
HIN	indoor relative humidity	%	average indoor humidity
T1,T2,T3, ...	extra thermometer 1, 2, 3,...	°C	average temperature from extra thermometer 1, 2, 3, ... Number of sensors is not limited
H1,H2,H3, ...	extra humidity sensor 1, 2, 3,...	%	average relative humidity from extra humidity sensor 1, 2, 3, ... Number of sensors is not limited
TS1,TS2,TS3, ...	soil temperature, sensor 1, 2, 3,...	°C	average soil temperature from soil temperature sensor 1, 2, 3, ... Number of sensors is not limited
TSD1,TSD2,TSD3, ...	depth of soil temperature sensor 1, 2, 3,...	cm	the depth of the corresponding soil temperature sensor below the ground.
LW1,LW2,LW3, ...	leaf wetness, sensor 1, 2, 3,...		leaf wetness from leaf wetness sensor 1, 2, 3, ... Number of sensors is not limited
LT1,LT2,LT3, ...	leaf temperature, sensor 1, 2, 3,...	°C	leaf temperature from leaf temperature sensor 1, 2, 3, ... Number of sensors is not limited
SM1,SM2,SM3 ...	soil moisture, sensor 1, 2, 3,...	%	soil moisture from soil moisture sensor 1, 2, 3, ... Number of sensors is not limited
SN	snowfall	mm	cumulative daily new snow (since midnight)
SD	snow depth	mm	current snow depth (snow on ground)
L	lightning		number of lightning strikes today (since midnight)
NL	noise level	dB	current noise level
CO2_1,CO2_2,CO2_3,...	CO2 level	ppm	current carbon dioxide (CO2) level, sensor 1, 2, 3, ...
NO2_1,NO2_2,NO2_3,...	NO2 level	ppm	current nitrogen dioxide (NO2) level, sensor 1, 2, 3, ...
CO_1,CO_2,CO_3,...	CO level	ppm	current carbon monoxide (CO) level, sensor 1, 2, 3, ...
SO2_1,SO2_2,SO2_3,...	SO2 level	ppb	current sulfur dioxide (SO2) level, sensor 1, 2, 3, ...
O3_1,O3_2,O3_3	ozone level	ppb	current ozone (O3) level, sensor 1, 2, 3, ...
PP1,PP2,PP3,...	particulate pollution	μg/m3	aggregate PM10 and PM2.5 measure, sensor 1, 2, 3, ...
...BAT	sensor battery level		for each sensor you can pass the battery level by appending the word BAT (eg. TBAT, TS1BAT, WBAT etc.). For battery level of the console use just BAT, with no sensor specification. Battery level can be passed as either number (%) or if battery level in percentage is not available as either OK or LOW
SW	software		software type - do not use spaces or special characters, which might cause problems in the URL

Examples

Here is an example of a request URL, sent to meteotemplate.com, where the template is in a subfolder "template" of server root:

http://www.meteotemplate.com/template/api.php?U=1486255070&T=25.3&H=79.9&P=1010.1&W=5.6&G=7.8&R=0&RR=0&B=272&S=788&PASS=password123

Contents