Formats, encodings, http-headers, restrictions

To debug your API requests, we recommend using Postman

This tool will greatly facilitate the process of developing and debugging your application that uses our API.

Developer's website: postman.com.
Article about Postman at habr.com.
Postman training at stepik.org.
Video tutorials on YouTube.

Formats, encodings, http-headers, restrictions

Requests are received in UTF-8 at http://api.narodmon.com in format JSON (HTTP POST) or REST (HTTP GET).

The Server response will be in JSON format and encoding is UTF-8. If an error occurs, returns {"error":"Error message","errno":N}.
Please be aware that requests in HTTP POST are safer than HTTP GET, because query parameters are not saved in the log of proxy and web servers and not cached.

HTTP headers for API requests:
- Accept-Encoding: gzip, deflate - optional header to save traffic if your application supports gzip compression.
- Content-Type: application/json - required header if a POST request in JSON format is used.
- Narodmon-Api-Key: MyAppKey - required header with the API key of the application developer, obtained in the My Applications section.
- User-Agent: MyAppName (application name in Latin) - required header, without which the server will consider your request illegitimate.

Limitations in using our REST API:
- Access to the API is free only for personal non-commercial purposes.
- The use of project data on third-party resources is possible only by agreement with the Administration and it is not free.
- The interval for polling sensors, devices, webcams is no more than 1 time per minute for each client of your application and for each IP, otherwise the server will return an HTTP 429 error, and if it is ignored for a long time, it will block your access key to API.
- To access data from private sensors and web cameras, you must first complete the userLogon authorization request, if this has not been done previously, but not more than once a day.

REST API error code reference (errno)

- 400 - syntax error in API request;
- 401 - requires authorization;
- 403 - access denied to the object;
- 404 - requested object not found;
- 423 - API key is locked by admin;
- 429 - more than 1 request per minute;
- 434 - requested object is offline;
- 503 - service is temporarily unavailable.

Required parameters to be passed in each request.

- cmd name of the API method;
- lang interface language ISO 639-1 ("en","ru","uk");
- uuid app's unique user ID, which is a lowercase MD5 hash generated once by the application at the time of installation. Used to define localization settings, location, etc.

appInit - check latest app version on first start + 1 times a day, user's authorization status, its location and favorites, sensor types list.

Request parameters:
- version version of the application, eg 1.1;
- platform platform(OS) version, eg 6.0.1;
- model device model, eg Xiaomi Redmi Note 4;
- width the width of the client device screen in pixels to optimize the size of the downloaded images;
- utc users's time zone in UTC (offset in hours).

Server response:
- latest latest version of app specified by developer in My Apps;
- url for update download specified by developer in My Apps;
- login authorized username for this uuid otherwise "";
- vip = 1 sign of the partner, donator, developer, administration, for the rest = 0;
- lat, lon latitude and longitude of user's current location in decimal degrees;
- addr nearest address to current user's location;
- timestamp current server time in UnixTime (for verification);
- types[..] array of sensor types(temp, humid, pressure, wind, energy, etc);
- types[type] sensor type ID;
- types[name] sensor type name;
- types[unit] measure unit;
- favorites[..] array of favorite sensors IDs of authorized user.

Request example REST(GET):
http://api.narodmon.com/appInit?version=1.1&platform=6.0.1&uuid=UUID&lang=en&utc=3

Request example JSON(POST):
{"cmd":"appInit","version":"1.1","platform":"6.0.1","uuid":"UUID","lang":"en","utc":3}

Server response:
{"latest":"1.2","url":"http://mysite.com/myapp.exe","login":"...","vip":0,"lat":39.962502,"lon":-83.006104,"addr":"...",
"types":[{"type":0,"name":"...","unit":""},{..}],"favorites":[1,2,..],"timestamp":1734285204}

mapBounds - query list of sensors and webcams in the specified rectangular area of the map

* The number of devices in the response (without agreement) is limited to 10. Your limit in Profile \ My Applications.

Request parameters:
- bounds array of coordinates of the corners of the viewport {min latitude, min longitude, max latitude, max longitude} in decimal form;
- metar optional, if = 1, then include METAR data in the region in the server response (authorization required);
- owmap optional, if = 1, then include OWMap data in the region in the server response (authorization required);
- types optional array of sensor type ids for display filter from directory appInit.

Server Response:
- devices an array with the list of devices and their sensors in a selected field of view (limited by PubsLimit);
- devices[id] integer code of the device in the project;
- devices[name] the device name or its ID (if no name);
- devices[lat], devices[lon] the latitude and longitude of the device in decimal form;
- devices[time] time of the last sensor value in UnixTime;
- devices[value] the value of the sensor to the balun devices (with max priority);
- devices[type] the type code of sensor (see appInit);
- devices[unit] unit of measurement;
- webcams an array with a list of web cameras in the selected view area
- webcams[id] integer code of a web camera in the project;
- webcams[name] the name of the webcam (as called by the owner);
- webcams[lat], webcams[lon] the latitude and longitude of Webcams in decimal form;
- webcams[time] time of last download the snapshot to the server in UnixTime;
- webcams[image] the URL of the latest snapshot with the webcam.

Request example REST(GET):
http://api.narodmon.com/mapBounds?bounds=10,20,11,21&uuid=UUID&lang=en&limit=10

Request example JSON(POST):
{"cmd":"mapBounds","limit":10,"bounds":[10,20,11,21],"uuid":"UUID","lang":"en"}

Server response:
{"devices":[{"id":0,"name":"..","lat":39.962502,"lon":-83.006104,"time":1734285204,"value":0.0,"type":0,"unit":""},{..}],
"webcams":[{"id":0,"name":"..","lat":39.962502,"lon":-83.006104,"time":1734285204,"image":"http://..."},{..}]}

sensorsNearby - request a list of sensors closest to the user's location + its own + Favorites

* To access the data of your private sensors outside your local network, a single authorization is required (userLogon).
** To access the data of other people's public devices, approval is required, see Profile \ My Apps List \ PubsLimit.

Request parameters:
- lat, lon optional latitude and longitude of user's location in decimal degrees;
- my optional, if = 1, then output only sensors from my devices (requires auth);
- pub optional, if = 1, then output only public sensors;
- radius maximum distance from the user to the sensor in km, max ~111km (1°);
- limit optional maximum number of public monitoring devices nearby in server response, default 20, max 50;
- metar optional, if = 1, then include METAR data in the region in the server response (authorization required);
- owmap optional, if = 1, then include OWMap data in the region in the server response (authorization required);
- types optional array of sensor type ids for display filter from directory appInit;
- trends optional, if = 1, then activate trends calculation by OLS.

Server response:
- devices array with a list of devices (limited by PubsLimit);
- devices[id] integer ID of the device in the project;
- devices[name] device name or its ID (if no name);
- devices[my] = 1, if this user's own device, otherwise = 0;
- devices[owner] ID of the device owner in the project;
- devices[mac] device serial number (for owner only);
- devices[cmd] = 1, if device control mode enabled, otherwise = 0;
- devices[lat], devices[lon] latitude and longitude of device location in decimal degrees;
- devices[location] locality of the device location;
- devices[distance] distance in kilometers from your current location of the user;
- devices[time] last time active of the device in UnixTime;
- devices[sensors] array of public or user's own sensors, connected to the device;
- devices[sensors][id] integer ID of the sensor in the Project;
- devices[sensors][mac] sensor metric (for owner only);
- devices[sensors][fav] = 1 if the sensor is in user's Favorites and = 0 if NO or not authorized;
- devices[sensors][pub] = 1 for public sensor and = 0 for private sensor;
- devices[sensors][type] sensor type code (see appInit);
- devices[sensors][name] sensor name or its ID (if no name);
- devices[sensors][value] last sensor reading;
- devices[sensors][unit] measure unit;
- devices[sensors][time] sensor's last time reading in UnixTime;
- devices[sensors][changed] last time the sensor was changed in UnixTime;
- devices[sensors][trend] coefficient of linear growth of sensor's readings for last hour, calculated by OLS.

Request example REST(GET):
http://api.narodmon.com/sensorsNearby?lat=39.962502&lon=-83.006104&radius=10&types=1,2&uuid=UUID&lang=en

Request example JSON(POST):
{"cmd":"sensorsNearby","lat":39.962502,"lon":-83.006104,"radius":10,"types":[1,2],
"uuid":"UUID","lang":"en"}

Server response:
{"devices":[{"id":0,"name":"..","my":0,"owner":"0","mac":"..","cmd":0,
"lat":0.0,"lon":0.0,"location":"..",
"distance":0.0,"time":1734285204,"sensors":[{"id":0,"mac":"..","fav":0,"pub":0,"type":0,"name":"..","value":0.0,"unit":"","time":1734285204,
"changed":1734285204,"trend":0.0},{..}]},{..}]}

sensorsOnDevice - request for list of sensors by monitoring device's ID

* To access the data of your private sensors outside your local network, a single authorization is required (userLogon).
** To access the data of other people's public devices, approval is required, see Profile \ My Apps List \ PubsLimit.

Request parameters:
- devices array of device IDs for data request;
- trends = 1, optional parameter which activates trends calculation by OLS;
- info = 1, optional option includes a full description of the device.

Server response:
- devices array with a list of devices (≤ 10, limited by PubsLimit);
- devices[id] ID of the device in the Project;
- devices[name] device name or its ID (if no name);
- devices[my] = 1 if this user's own device, otherwise = 0;
- devices[owner] ID of the device owner in the Project;
- devices[mac] device serial number (for owner only);
- devices[cmd] = 1, if device control mode enabled, otherwise = 0;
- devices[lat], devices[lon] latitude and longitude of device location in decimal degrees;
- devices[location] locality of the device location;
- devices[distance] distance in kilometers from your current location of the user;
- devices[time] last time active of the device in UnixTime;
- devices[site] link to the device owner's website, otherwise https://narodmon.com/id;
- devices[photo] link to the device photo (if the owner uploaded it), otherwise an empty string;
- devices[info] device description (if info = 1), otherwise the description length in bytes or an empty string;
- devices[sensors] array of sensors, connected to this device;
- devices[sensors][id] integer ID of the sensor in the Project;
- devices[sensors][pub] = 1 for public sensor and = 0 for private sensor;
- devices[sensors][type] sensor type code (see appInit);
- devices[sensors][name] sensor name or its ID (if no name);
- devices[sensors][value] last sensor reading;
- devices[sensors][unit] measure unit;
- devices[sensors][time] sensor's last time reading in UnixTime;
- devices[sensors][changed] last time the sensor was changed in UnixTime;
- devices[sensors][trend] coefficient of linear growth of sensor's readings for last hour, calculated by OLS.

Request example REST(GET):
http://api.narodmon.com/sensorsOnDevice?devices=1,2&uuid=UUID&lang=en

Request example JSON(POST):
{"cmd":"sensorsOnDevice","devices":[1,2],"uuid":"UUID","lang":"en"}

Server response:
{"devices":[{"id":1,"name":"..","my":0,"owner":"0","mac":"","cmd":0,"lat":0.0,"lon":0.0,"location":"..","distance":0.0,"time":1734285204,
"site":"https://narodmon.com/1","photo":"","info":"220B",
"sensors":[{"id":1,"mac":"","fav":0,"pub":1,"type":1,"name":"..","value":0.0,"unit":"",
"time":1734285204,"changed":1734285204,"trend":0},{..}]},{..}]}

sensorsValues - request for last readings of the selected sensors

sensorsHistory - history of the sensor readings for the period (eg for charts and trends)

* To access the data of your private sensors outside your local network, a single authorization is required (userLogon).

Request parameters:
- id sensor id to query the history of readings (or sensors);
- sensors array of sensor ids to request readings (or id);
- period name of the period: 'hour','day','week','month','year';
- offset offset of the selected period to the past, ie 1(day) = yesterday, 1(month) = last month.

Server response:
- sensors array of the requested sensors;
- sensors[id] integer code of the sensor in the Project;
- sensors[type] sensor type code (see appInit);
- sensors[name] sensor name or ID (if there is no name);
- sensors[unit] unit of measurement;
- data array of the sensor readings;
- data[id] integer ID of the sensor in the Project;
- data[time] time of sensor reading in UnixTime;
- data[value] sensor reading in this time.

Request example REST(GET):
http://api.narodmon.com/sensorsHistory?id=1&period=day&offset=0&uuid=UUID

Request example JSON(POST):
{"cmd":"sensorsHistory","id":1,"period":"day","offset":0,"uuid":"UUID"}

Server response:
{"sensors":[{"id":1,"type":1,"name":"..","unit":".."}],"data":[{"id":1,"time":1734285204,"value":0.0},{..}]}

nameSensor - change the name of the sensor (for the owner) or create an alias for the rest

Request parameters:
- id integer sensor code in the project;
- name the new name of the sensor, if empty, it changes to the default.

Request example REST(GET):
http://api.narodmon.com/nameSensor?id=1&name=NewName&uuid=UUID

Request example JSON(POST):
{"cmd":"nameSensor","id":1,"name":"NewName","uuid":"UUID"}

Server response:
{"result":"OK"}

pubSensor - private sensor publish request

Request parameters:
- id is an integer sensor code in the Project.

Server RESPONSE:
- id integer sensor code in the Project;
- code sensor code to add to Favorites.

Request example REST(GET):
http://api.narodmon.com/pubSensor?id=123456&uuid=UUID

Request example JSON(POST):
{"cmd":"pubSensor","id":123456,"uuid":"UUID"}

Server response:
{"id":123456,"code":123456}

webcamsNearby - request a list of webcams closest to the user's location + its own + Favorites

Request parameters:
- lat, lon optional latitude and longitude of user's current location in decimal degrees;
- radius maximum distance from the user to the webcam in km, max ~111km (1°);
- my optional, if = 1, then output only my webcams (requires auth);
- width optionally the width of the client device screen in pixels to optimize the size of the downloaded images.

Server response:
- webcams array of the webcams in the Project;
- webcams[id] ID of the webcam in the Project;
- webcams[name] webcam name or http-link (as named by the owner);
- webcams[my] = 1, if this user's own webcam, otherwise = 0;
- webcams[owner] username of the webcam owner in the Project;
- webcams[fav] = 1, if the webcam is in user's Favorites and = 0 if NO or not authorized;
- webcams[distance] distance in kilometers from user's current location;
- webcams[location] locality of the webcam location;
- webcams[time] time of the last snapshot from the webcam in UnixTime;
- webcams[lat], webcams[lon] latitude and longitude of the webcam location in decimal degrees;
- webcams[image] URL of the latest snapshot from webcam.

Request example REST(GET):
http://api.narodmon.com/webcamsNearby?radius=10&lat=39.962502&lon=-83.006104&uuid=UUID&lang=en

Request example JSON(POST):
{"cmd":"webcamsNearby","lat":39.962502,"lon":-83.006104,"radius":10,"uuid":"UUID","lang":"en"}

Server response:
{"webcams":[{"id":1,"name":"..","my":0,"owner":"1","fav":0,"distance":0.0,"lat":39.962502,"lon":-83.006104,"location":"..",
"time":1734285204,"image":"http://.."},{..}]}

webcamImages - request a list of images from the webcam on its ID

Request parameters:
- id ID of the webcam from URL http://narodmon.com/-ID;
- limit optional number of images in the server response, default 20, max 50;
- since optionally the time of the first snapshot in UnixTime, default is 0;
- latest optionally the time of the last snapshot in UnixTime, default is current;
- width optionally the width of the client device screen in pixels to optimize the size of the downloaded images.

Server response:
- id ID of the webcam in the Project;
- name webcam name (as named by the owner);
- location locality of the webcam location;
- distance distance in kilometers from user's location;
- images array of snapshots from the webcam on the server;
- images[time] time of the snapshot in UnixTime;
- images[image] URL to download the snapshot.

Request example REST(GET):
http://api.narodmon.com/webcamImages?id=1&limit=10&uuid=UUID

Request example JSON(POST):
{"cmd":"webcamImages","id":1,"limit":10,"uuid":"UUID"}

Server response:
{"id":1,"name":"..","location":"..","distance":0.0,
"images":[{"time":1734285204,"image":"http://.."},{..}]}

userLogon - user authorization in the Project or his registration

Request parameters:
- login user login for authorization, if it is not specified, returns the current login for the specified uuid;
- hash hash for authorization, calculated by the formula with string concatenation MD5(uuid + MD5(entered password)), if hash is not specified, it is considered a request for registration in the Project by email/sms.

Server response:
- tz user's time zone in the Project in UTC;
- vip = 1 sign of the partner, donator, developer, administration, for the rest = 0;
- login authorized username for this uuid otherwise "";
- uid = Project member ID.

Request example REST(GET):
http://api.narodmon.com/userLogon?login=MyName&hash=MD5HASH&uuid=UUID&lang=en

Request example JSON(POST):
{"cmd":"userLogon","login":"MyName","hash":"MD5HASH","uuid":"UUID","lang":"en"}

Server response:
{"uid":1,"tz":3,"login":"MyName","vip":0}

userLocation - GET and SET user's location (reference point)

Request parameters:
- lat, lon optional latitude and longitude of the user's location;
- addr optionally the nearest address to the user's location;
- wifi optional array of WiFi access points nearby;
- wifi[bssid] MAC address of the access point;
- wifi[rssi] signal strength of the AP signal in dBm (<0);
- cells optional array of cellular stations nearby;
- cells[bssid] = MCC[3]:MNC[3]:LAC[4]:CID[7] in hex form;
- cells[rssi] signal strength of the cell-site in dBm (<0);
- gui flag indicating the need for a complete address.

Server response:
- lat, lon latitude and longitude of user's location in decimal degrees;
- addr nearest address to user's location (if gui = 1).

Request example by coordinates REST(GET):
http://api.narodmon.com/userLocation?lat=39.962502&lon=-83.006104&uuid=UUID&lang=en

Request example by address REST(GET):
http://narodmon.com/api/userLocation?addr=..&uuid=UUID&lang=en

Request example by coordinates JSON(POST):
{"cmd":"userLocation","lat":39.962502,"lon":-83.006104,"uuid":"UUID","lang":"en"}

Request example by address JSON(POST):
{"cmd":"userLocation","addr":"..","uuid":"UUID","lang":"en"}

Request example by WiFi networks JSON(POST):
{"cmd":"userLocation",
"wifi":[{"bssid":"00:00:00:00:00:00","rssi":-0},{..}],"uuid":"UUID","lang":"en"}

Request example by cellular networks JSON(POST):
{"cmd":"userLocation",
"cells":[{"bssid":"000:000:0000:0000000","rssi":-0},{..}],"uuid":"UUID","lang":"en"}

Server response:
{"lat":39.962502,"lon":-83.006104,"addr":".."}

userFavorites - management list of selected sensors and webcams

Request parameters:
- sensors optional array of IDs of favorite sensors (list will be replaced, for its cleaning pass "sensors":[0]);
- webcams optional array of IDs of favorite webcams (list will be replaced, for its cleaning pass "webcams":[0]).

Server response:
- sensors array of favorite sensors for authorized user;
- sensors[id] integer ID of the sensor in the Project;
- sensors[did] integer ID of the device in the Project;
- sensors[type] sensor type code (see appInit);
- sensors[name] sensor name or its ID (if no name);
- sensors[value] last sensor reading;
- sensors[unit] measure unit;
- sensors[time] sensor's last time reading in UnixTime;
- webcams array of favorite webcams from an authorized user;
- webcams[id] integer webcam code in the project, if <0 then remove from list;
- webcams[name] name of the webcam or http-link (as the owner called it);
- webcams[time] time of the last download of the snapshot to the server in UnixTime;
- webcams[image] URL of the last snapshot from the webcam.

Request example REST(GET):
http://api.narodmon.com/userFavorites?sensors=1,2&webcams=1,2&uuid=UUID&lang=en

Request example JSON(POST):
{"cmd":"userFavorites","uuid":"UUID",
"sensors":[1,2],"webcams":[1,2],"lang":"en"}

Server response:
{"sensors":[{"id":1,"did":1,"type":1,"name":"..","value":0.0,"time":1734285204},{..}],
"webcams":[{"id":1,"name":"..","time":1734285204,"image":"http://.."},{..}]}

userLogout - log off the current user

Request parameters:
* no parameters *

Server response:
- login authorized user name for this uuid;
- uid Project member ID.

Request example REST(GET):
http://api.narodmon.com/userLogout?uuid=UUID

Request example JSON(POST):
{"cmd":"userLogout","uuid":"UUID"}

Server response:
{"login":"","uid":0}

addLike - mark "Like" on the images from webcams and monitoring devices.

Request parameters:
- id of the webcam(<0) or of the monitoring device(>0).

Server response:
- id of the webcam(<0) or of the monitoring device(>0);
- time mark time in UnixTime;
- liked total number of "Likes" on the object after execution.

Request example REST(GET):
http://api.narodmon.com/addLike?id=1&uuid=UUID

Request example JSON(POST):
{"cmd":"addLike","id":1,"uuid":"UUID"}

Server response:
{"id":1,"time":1734285204,"liked":1}

disLike - unmark "Like" on the images from webcams and monitoring devices

Request parameters:
- id of the webcam(<0) or of the monitoring device(>0).

Server response:
- id of the webcam(<0) or of the monitoring device(>0);
- time time of unmark in UnixTime;
- liked total number of "Likes" on the object after execution.

Request example REST(GET):
http://api.narodmon.com/disLike?id=1&uuid=UUID

Request example JSON(POST):
{"cmd":"disLike","id":1,"uuid":"UUID"}

Server response:
{"id":1,"time":1734285204,"liked":0}

setPushToken, setPushURI - settings for sending PUSH notifications. Use FireBase (Android, iOS) and WNS (Windows)

Request parameters:
- token for Android и iOS;
- uri URL for Windows Mobile and Windows Phone.

Request example REST(GET):
FireBase: http://api.narodmon.com/setPushToken?token=TOKEN&uuid=UUID
WNS: http://api.narodmon.com/setPushURI?uri=URL&uuid=UUID

Request example JSON(POST):
FireBase: {"cmd":"setPushToken","token":"TOKEN","uuid":"UUID"}
WNS: {"cmd":"setPushURI","uri":"URL","uuid":"UUID"}

Server response:
{"result":"OK"}

PUSH messages from FireBase come in the java.util.Map collection with fields:
- id message id (int unsigned);
- uid user ID (int signed);
- time message sending time in UnixTime (int unsigned);
- subj headline of the message;
- body full text of the message.

Push messages from WNS come as a structure JSON:
{"id":ID,"uid":UserID,"time":1734285204,"subj":"..","body":".."}

setPushStatus - sending PUSH-notification delivery report

Request parameters:
- states array with received message statuses:
- states[id] ID of the message received (int unsigned);
- states[time] time of sending a message in UnixTime;
- states[status] status code of the message (201 - received, 202 - read).

Request example REST(GET):
http://api.narodmon.com/setPushStatus?id=1&time=1734285204&status=201&uuid=UUID

Request example JSON(POST):
{"cmd":"setPushStatus","states":[{"id":1,"time":1734285204,"status":201},{..}],"uuid":"UUID"}

Server response:
{"result":"OK"}

PUSH messages from FireBase come in the java.util.Map collection with fields:
- id message id (int unsigned);
- uid user ID (int signed);
- time message sending time in UnixTime (int unsigned);
- subj headline of the message;
- body full text of the message.

Push messages from WNS come as a structure JSON:
{"id":ID,"uid":UserID,"time":1734285204,"subj":"..","body":".."}

In order to avoid receiving error 429 (too frequent requests), it is strongly recommended to accumulate the delivery status of PUSH messages and send them in batches no more than 1 time per minute!

sendCommand - sends a control command to the device

Request parameters:
- id ID of the monitoring device in the project (integer unsigned);
- command command string, PCRE template [a-z0-9_\-\+\=\;\/\.]+

Request example REST(GET):
http://api.narodmon.com/sendCommand?id=1&command=reboot&uuid=UUID

Request example JSON(POST):
{"cmd":"sendCommand","id":1,"command":"gpio12=1","uuid":"UUID"}

Server response:
{"result":"OK"}

sendComplaint - send complaint to the wrong sensor reading or webcam snapshot

Request parameters:
- id sensor ID (id>0) or webcam ID (id<0);
- time of occurrence of the problem in UnixTime;
- name of the applicant for feedback;
- email of the applicant for feedback;
- problem brief description of the problem;
- value what should be the value of the sensor (if id>0).

Request example REST(GET):
http://api.narodmon.com/sendComplaint?id=1&time=1734285204&value=0
&name=..&email=..&problem=..&uuid=UUID

Request example JSON(POST):
{"cmd":"sendComplaint","id":1,"time":1734285204,"value":0,
"name":"..","email":"..","problem":"..","uuid":"UUID"}

Server response:
{"result":"OK"}

sendMessage - sending a message to a conversation or a question to the Administration

Request parameters:
- uid optional recipient ID, by default Administration;
- name optionally the name of the applicant for the request;
- email optionally the applicant's mail for duplication;
- chat optional conversation ID from getDialog;
- subj be sure the topic of the request;
- mess the message text is required;
- images[..] optional array of embedded images (up to 1MB) in the form of base64 strings.

Request example REST(GET):
http://api.narodmon.com/sendMessage?uid=1&name=..&email=..&subj=..&mess=..&uuid=UUID

Request example JSON(POST):
{"cmd":"sendMessage","uid":1,"name":"..","email":"..","subj":"..","mess":"..","uuid":"UUID"}

Server Response:
{"result":"OK"}

weatherReport - sending meteorological data by the user from autonomous meteorological devices

Request parameters:
- lat, lon the latitude and longitude of the device at the time of sending (pre-update geolocation!);
- temp reading of the outdoor thermometer (if any) °C;
- humid street hygrometer readings (if any) %;
- press readings of a household barometer (if any) mmHg;
- wind azimuth of the wind direction (from anemometer) 0-360°.

Request example REST(GET):
http://api.narodmon.com/weatherReport?lat=39.962502&lon=-83.006104&temp=00&humid=00&press=000&wind=000
&lang=ru&uuid=UUID

Request example JSON(POST):
{"cmd":"weatherReport","lat":39.962502,"lon":-83.006104,"temp":00,"humid":00,"press":000,"wind":000,
"lang":"ru","uuid":"UUID"}

Server response:
{"result":"You have reported the following data:..."}

If the weather report is sent less than an hour after the previous one, it will be considered a correction and replace it.

bugReport - sending feedback and bug reports with technical data for debugging

Request parameters:
- time optional UnixTime when the failure occurred;
- name optionally the name of the applicant for the request;
- email optionally the user's e-mail for a copy;
- mess optional text of the user's message;
- logs optional technical data for debugging;
- images[..] optional array of embedded images (upto 1MB) in the form of base64 strings.

Request example REST(GET) query:
http://api.narodmon.com/bugReport?time=1734285204&name=..&email=..&mess=..&logs=..&uuid=UUID

Request example JSON(POST):
{"cmd":"bugReport","time":1734285204,"name":"..","email":"..","mess":"..","logs":"..","uuid":"UUID"}

Server response:
{"result":"OK"}

The bug report will be briefly sent to the author of the app using PUSH, and the full version will be sent to the author's e-mail along with the technical data for debugging.

getHelp - request for Project reference information

Request parameters:
- topic optional article identifier, if it is not specified, then the table of contents is returned.

Server response:
- topics an array of articles;
- topics[topic] article id;
- topics[group] name of the section;
- topics[title] article title from HowTo;
- topics[body] The html text of the article (if topic was specified) or the hash of the article in the table of contents.

Request example table of contents REST(GET):
http://api.narodmon.com/getHelp?lang=en&uuid=UUID

Request example table of contents JSON(POST):
{"cmd":"getHelp","lang":"en","uuid":"UUID"}

Server response with a table of contents:
{"topics":[{"topic":"topic1","group":"Group1","title":"Title1","body":"c8542aec71a1a1e371f39553ae3b7ec7"},{..}]}

Request example the text of the article REST(GET):
http://narodmon.com/api/getHelp?topic=topic1&lang=en&uuid=UUID

Request example the text of the article JSON(POST):
{"cmd":"getHelp","topic":"topic1","lang":"en","uuid":"UUID"}

Server response with the text of the article:
{"topics":[{"topic":"topic1","group":"Group1","title":"Title1","body":"html-текст"}]}

It is strongly recommended to cache texts of previously downloaded articles in view of their substantial size, but periodically update the table of contents and in case of changing the article hash, it should be downloaded from the server specifying its topic and updating the title and body in the local application cache.

PHP + cURL example to display readings on your website

// server response encoding
header('Content-Type: text/html; charset=utf-8');

// preparation of request parameters
$request = array('cmd'=>'sensorsNearby', 'lat'=>55.75, 'lon'=>37.62, 'radius'=>11, 'uuid'=>md5('mysite.com'), 'api_key'=>'MY_API_KEY', 'lang'=>'en');

// request execution
$ch = curl_init('http://api.narodmon.com');
if(!$ch) exit('cURL initialization error');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 2);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERAGENT, 'mysite.com');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($request));
$reply = curl_exec($ch);
curl_close($ch);
if(empty($reply)) exit('Network error');

// decode response from json to array
$data = json_decode($reply, true);
if(empty($data) or !is_array($data)) {
  exit('Erroneous data'); }

// if there was an API error
if(isset($data['error'])) exit($data['error']);

// output in a cycle sensors readings
foreach($data['devices'] as $D) {
  echo "\n".$D['name'].":\n";
  foreach($D['sensors'] as $S) {
    echo date('H:i', $S['time']).' '.$S['name'];
    echo ' = '.round($S['value']).$S['unit']."\n"; }}

PHP without cURL example to output readings to your website

// server response encoding
header('Content-Type: text/html; charset=utf-8');

// preparation of request parameters
$request = array('cmd'=>'sensorsNearby', 'lat'=>55.75, 'lon'=>37.62, 'radius'=>11, 'uuid'=>md5('mysite.com'), 'api_key'=>'MY_API_KEY', 'lang'=>'en');

// request execution
$header = "User-Agent: mysite.com\r\nContent-Type: application/x-www-form-urlencoded\n";
$context = array('http' => array('method'=>'POST', 'header'=>$header, 'content'=>json_encode($request)));
$reply = file_get_contents('http://api.narodmon.com', false, stream_context_create($context));
if(empty($reply)) exit('Network error');

// decode response from json to array
$data = json_decode($reply, true);
if(empty($data) or !is_array($data)) {
  exit('Erroneous data'); }

// if there was an API error
if(isset($data['error'])) exit($data['error']);

// output in a cycle sensors readings
foreach($data['devices'] as $D) {
  echo "\n".$D['name'].":\n";
  foreach($D['sensors'] as $S) {
    echo date('H:i', $S['time']).' '.$S['name'];
    echo ' = '.round($S['value']).$S['unit']."\n"; }}

REST API JSON for IoT apps, widgets, websites - Public Monitoring Project

To debug your API requests, we recommend using Postman