Version 2

Neverin station protocol

How a weather station, a gateway or a program sends its measurements to ws.neverin.hr: the key that identifies a station, the names and units we read, the time rule and the answers. For station makers, software authors and owners who write their own sender.

1. The key

A station on Neverin is identified by its key alone: 10 lower-case hexadecimal characters. The owner gets it in their Neverin profile, under My stations, the moment they add the station, together with the exact settings for their device; the data flow from the first minute.

The key is the one thing a sender must send; nothing else identifies the station, and there is no account, token or password besides it. Where a firmware or a program asks for two fields, Station ID and Key (the Weather Underground shape), the owner enters the Station ID the profile shows beside the key: it is accepted and ignored. A built-in "Neverin" entry needs the key; it may offer a Station ID field for the owners used to one.

2. Endpoint

ws.neverin.hr, plain HTTP on port 80 (HTTPS on 443 for software that has it). A sample is written once per 2.5 seconds at most per station. Send every 2.5 seconds to 5 minutes; longer intervals, 10, 15, 30 or 60 minutes, work too, but the station's live values and its 5-minute archive are only as fresh as you send. Match the interval to the device: send no more often than its sensors refresh. A console that updates its readings once a minute has nothing new to report every 2.5 seconds; one sample per refresh is the right pace.

Everything goes to /v2/: a GET or a POST (a form, or a JSON object of one level), with the key in the path, /v2/<key>, or as the parameter key (in the body of a POST it stays out of access logs). Required: the key and at least one measurement. Everything else is optional; the first known name present wins. A name we do not know is kept beside the sample and shown to the owner, so a new sensor needs no change on your side.

GET  http://ws.neverin.hr/v2/<key>?temp=14.2&rh=81&baro_rel=1016.4&wspeed=2.5&wdir=230&precip_day=3.4
POST http://ws.neverin.hr/v2/              key=<key>&temp=14.2&rh=81&baro_abs=985.1&soil_temp_1=9.8&soil_vwc_1=31
POST http://ws.neverin.hr/v2/<key>         {"temp": 14.2, "rh": 81, "time": "2026-11-08T12:00:00Z"}

3. Parameters

Every name of the table is read and kept with the station: you map everything once. Metric units, no conversions. N is a channel number.

GroupParameterUnitMeaning
Time and sendertimeUTC, ISO 8601 or Unix secondsthe sample's time; without it, the arrival
software, modeltextwhat sends, for our reports; not stored with the sample
Weathertemp°Cair temperature
rh%relative humidity
baro_relhPasea-level (relative) pressure
baro_abshPastation (absolute) pressure
wspeedm/sinstant wind speed
wavgm/smean wind speed
wgustm/swind gust
wdir°wind direction, 0 to 360
uvindexUV index
solarW/m²solar radiation
visibilitymvisibility
Rainprecipmmrain since the previous sample
precip_total, precip_year, precip_month, precip_daymmor one rain counter instead: the total if the device has it, else the year's, the month's, the day's, in this order; resets are handled
Indoortemp_in°Cindoor temperature
rh_in%indoor humidity
Soil, N 1 to 8soil_temp_N°Csoil temperature of probe N
soil_vwc_N%volumetric water content of probe N
soil_moist_Ncbsoil water tension of probe N (Davis)
soil_ec_NµS/cmsoil electrical conductivity of probe N
Leaf, N 1 to 8leaf_wet_N%leaf wetness of sensor N
Channels, N 1 to 8temp_chN°Ca temperature sensor whose place the device does not know; its role is given at approval (section 4)
rh_chN%a humidity sensor likewise
Sea and snowsea_temp°Csea temperature
snow_depthcmsnow depth
Air qualitypm1, pm2p5, pm10µg/m³particulate matter
no2, o3, so2, c6h6, h2s, nh3µg/m³gases
comg/m³carbon monoxide
pm2p5_chNµg/m³a PM2.5 sensor by channel, N 1 to 4; its role is given at approval
CO2co2ppmcarbon dioxide
Lightninglightning_countcountthe day's strikes
lightning_distkmthe last strike's distance
Batteriesbatt_<sensor>as the device sends ita battery level or voltage, named by its sensor

Derived values may be sent and are not read, since we compute them from the samples: the dew point, the wind chill, the heat index, the feels-like temperature, the rain rate, the hour's, the event's, the week's and the last 24 hours' rain, the day's highest gust, the 10-minute means, the vapour pressure deficit, the radiation in lux.

4. Channels and roles

One name has one meaning: temp is the station's air temperature, sea_temp the water's, snow_depth the snow's; a sea probe never lands in temp. A measurement reaches its place in two ways: by its name, from software that knows what it measures; or as a channel plus a role, from a device that does not (an Ecowitt WN34 is "temperature channel 3", an LDS01 "distance channel 1"). The role is given once, when we approve the station, from what the device sends and what the owner tells us; the receiver never guesses it. A role is an explicit decision and wins over the device's own name: a WH31 in the right screen mapped to temp replaces the array's tempf.

ChannelThe roles it may take
temp_chN; tf_chN, tempNf, tempNc (Ecowitt WN34, WH31, WN30)temp, sea_temp, soil_temp_N
rh_chN; humidityN (WH31)rh
depth_chN (Ecowitt LDS01)snow_depth
soilmoistureN, soil_ec_humN (WH51, WH52)soil_vwc_N
soil_ec_tempN (WH52)soil_temp_N
leafwetness_chN (WN35)leaf_wet_N
pm2p5_chN; pm25_chN (WH41, WH43)pm2p5
pm1_co2, pm25_co2, pm10_co2 (WH45, WH46)pm1, pm2p5, pm10

5. Time

A sample is timed at its arrival unless it carries time (UTC, ISO 8601 such as 2026-11-08T12:00:00Z, or Unix seconds), which is honoured within 5 minutes ahead of the arrival and 3 hours behind it. The Weather Underground protocol's dateutc is read only for stations whose software clock we have checked. Software that sends at least once a minute needs no time field: the arrival is as good.

6. Answers

JSON. 200 with "stored": true, the station's number, the sample's time and the fields read; 200 with "stored": false and "reason": "TOO_SOON" within 2.5 seconds of the last sample; 400 NO_VALUES when nothing is a known measurement; 400 INVALID_PARAMETER, with the field named, when a time cannot be read; 401 STATION_KEY_MISSING or STATION_KEY_INVALID; 403 STATION_DISABLED or STATION_REJECTED; 503 SERVICE_UNAVAILABLE when the sample could not be stored, retry later. Devices need only the status.

7. Also accepted: the Weather Underground protocol

The GET your firmware already sends to Wunderground, with ID and PASSWORD=<key>, to /v2/?: the question mark at the end, because the firmware runs its query straight into the path (an Ecowitt's Customized screen: protocol Wunderground, Server IP ws.neverin.hr, Path /v2/?). Only where the firmware does not let you change the path, its own /weatherstation/updateweatherstation.php works as well. Its imperial fields are converted: tempf, humidity, baromin, absbaromin, windspeedmph, windgustmph, winddir, dailyrainin, monthlyrainin, yearlyrainin, totalrainin, UV, solarradiation, soiltempf to soiltemp4f, soilmoisture, leafwetness, AqPM2.5, AqPM10, indoortempf, indoorhumidity; the derived fields (dewptf, windchillf, rainin, rainratein) are not read.

GET http://ws.neverin.hr/v2/?ID=<station id>&PASSWORD=<key>&tempf=57.6&humidity=81&baromin=30.01&dailyrainin=0.13

8. Also accepted: the Ecowitt protocol

The POST form your firmware sends to ecowitt.net, with every sensor (both pressures, the piezo rain gauge, the extra probes, the batteries), with Path /v2/<key>: this body has no field for the key, so the key is the path. Imperial fields are converted; the rebranded models' metric spellings (tempc, baromrelhpa, windspeedkmh, dailyrainmm) are read too. The channel sensors (tf_chN, tempNf, humidityN, soilmoistureN, leafwetness_chN, pm25_chN, depth_chN) get their roles at approval (section 4); the console's indoor values, the CO2 sensor, the lightning sensor and the batteries are kept with the sample.

POST http://ws.neverin.hr/v2/<key>         PASSKEY=...&tempf=57.6&humidity=81&baromrelin=30.01&baromabsin=29.63&yrain_piezo=12.3&tf_ch1=61.2 ...

9. Testing, the logo and contact

Test it as an owner would: register, add a station in your profile under My stations, and you have a key and the settings for a device; the data appear on the station's card as they arrive. We also send test credentials on request, answer every question about an integration and help with the implementation: [email protected].

The logo for the "Neverin" entry in your app, firmware or program, as SVG and as a transparent PNG of 512 pixels:

Neverin logo, SVG
SVG
https://www.neverin.hr/img/brand/neverin-logo.svg
Neverin logo, PNG, 512 px
PNG, 512 px
https://www.neverin.hr/img/brand/neverin-logo-512.png

Changes

  • Version 2. This document. Every form of version 1 stays accepted.