{"error":"Error message","errno":N}. Следует знать, что запросы HTTP POST более безопасны, чем HTTP GET" /> {"error":"Error message","errno":N}. Следует знать, что запросы HTTP POST более безопасны, чем HTTP GET" />

REST API JSON для IoT приложений, виджетов, сайтов - Народный Мониторинг

+ Для отладки ваших запросов к API рекомендуем использовать Postman

Данный инструмент сильно облегчит Вам процесс разработки и отладки Вашего приложения, использующего наше API.

Сайт разработчика: postman.com
Статья о Postman на habr.com
Обучение Postman на stepik.org
Видеоуроки на YouTube.

+ Форматы, кодировки, http-заголовки, ограничения

Запросы принимаются в кодировке UTF-8 по адресу http(s)://api.narodmon.ru в формате JSON (HTTP POST) или REST (HTTP GET).
Ответ сервера будет в формате JSON и кодировке UTF-8, в случае ошибки возвращается: {"error":"Error message","errno":N}.
Следует знать, что запросы HTTP POST более безопасны, чем HTTP GET, т.к. параметры запроса не попадают в лог прокси и веб-серверов и не кешируются.

HTTP-заголовки при запросах к API:
- Accept-Encoding: gzip, deflate - необязательный заголовок для экономии трафика, если ваше приложение поддерживает gzip-сжатие.
- Content-Type: application/json - обязательный заголовок, если используется POST запрос в формате JSON.
- Narodmon-Api-Key: MyAppKey - обязательный заголовок с ключом API разработчика приложения, получаемого в разделе Мои Приложения.
- User-Agent: MyAppName (название приложения на латинице) - обязательный заголовок, без которого сервер сочтет ваш запрос нелегитимным.

Ограничения в использовании нашего REST API:
- Доступ к API бесплатен только в личных некоммерческих целях.
- Использование данных проекта на сторонних ресурсах возможно только по согласованию с Администрацией и это не бесплатно.
- Интервал опроса датчиков, приборов, веб-камер не чаще 1 раза в минуту для каждого клиента вашего приложения и для каждого IP, иначе сервер вернет ошибку HTTP 429, а при длительном её игнорировании заблокирует ваш ключ доступа к API.
- Для доступа к данным приватных датчиков и веб-камер предварительно надо выполнить запрос аутентификации userLogon, если это не было сделано ранее, но не чаще 1 раза в сутки.

+ Справочник кодов ошибок REST API (errno)

- 400 - ошибка синтаксиса в запросе к API;
- 401 - требуется аутентификация;
- 403 - в доступе к объекту отказано;
- 404 - искомый объект не найден;
- 423 - ключ API заблокирован администратором;
- 429 - более 1 запроса в минуту;
- 434 - искомый объект отключен;
- 503 - сервер временно не обрабатывает запросы по техническим причинам.

+ Обязательные параметры, которые следует передавать в КАЖДОМ запросе.

- cmd название метода API;
- lang язык интерфейса приложения ISO 639-1 ("ru","en","uk");
- uuid уникальный идентификатор пользователя приложения, представляющий собой MD5-хеш в нижнем регистре однократно сгенерированный приложением в момент его установки. Используется для определения настроек локализации, местоположения и др.

+ appInit - проверка актуальности версии приложения при первом запуске и раз в сутки, проверка аутентификации пользователя, его местонахождения, избранного и справочник типов датчиков.

Параметры запроса:
- version версия приложения пользователя для контроля, например: 1.1;
- platform версия платформы(ОС), например 6.0.1;
- model модель устройства, например Xiaomi Redmi Note 9;
- width ширина экрана клиентского устройства в пикселях для оптимизации размера загружаемых изображений;
- utc часовой пояс пользователя приложения в UTC (смещение в часах).

ОТВЕТ сервера:
- latest актуальная версия приложения указанная в Мои приложения;
- url скачивания обновления приложения указанный в Мои приложения;
- login имя авторизованного пользователя для данного uuid иначе "";
- vip = 1 признак партнера, донатора, разработчика, администрации, для остальных = 0;
- lat, lon широта и долгота текущего местонахождения пользователя в десятичном виде;
- addr ближайший адрес текущего местонахождения пользователя;
- timestamp текущее время сервера в UnixTime (для сверки);
- types[..] справочник типов датчиков;
- types[type] код типа датчика;
- types[name] название типа датчика;
- types[unit] единица измерения;
- favorites[..] массив из ID избранных датчиков у авторизованного пользователя.

Пример запроса REST(GET):
http://api.narodmon.ru/appInit?version=1.1&platform=6.0.1&uuid=UUID&lang=ru&utc=3

Пример запроса JSON(POST):
{"cmd":"appInit","version":"1.1","platform":"6.0.1","uuid":"UUID","lang":"ru","utc":3}

Ответ сервера:
{"latest":"1.2","url":"http://mysite.ru/myapp.exe","login":"..","vip":0,"lat":39.962502,"lon":-83.006104,"addr":"..",
"types":[{"type":0,"name":"..","unit":""},{..}],"favorites":[1,2,..],"timestamp":1734304831}

+ mapBounds - запрос списка датчиков и веб-камер в указанной прямоугольной области карты

* Для доступа к данным чужих публичных приборов требуется согласование, см. Профиль \ Мои приложения \ PubsLimit.

Параметры запроса:
- bounds массив координат углов области просмотра {широта-мин, долгота-мин, широта-макс, долгота-макс} в десятичном виде;
- metar опционально, если = 1, то включить в ответ сервера данные METAR в регионе (требуется авторизация);
- owmap опционально, если = 1, то включить в ответ сервера данные OWMap в регионе (требуется авторизация);
- types опционально массив кодов типов датчиков для фильтра отображения из справочника appInit.

ОТВЕТ сервера:
- devices массив с перечнем приборов и их датчиков в выбранной области просмотра (ограничено PubsLimit);
- devices[id] целочисленный код прибора в проекте;
- devices[name] название прибора или его ID (если нет названия);
- devices[lat], devices[lon] широта и долгота прибора в десятичном виде;
- devices[time] время последнего показания датчика в UnixTime;
- devices[value] показание датчика для балуна прибора (с макс приоритетом);
- devices[type] код типа датчика (см. appInit);
- devices[unit] единица измерения;
- webcams массив с перечнем веб-камер в выбранной области просмотра;
- webcams[id] целочисленный код веб-камеры в проекте;
- webcams[name] название веб-камеры (как назвал владелец);
- webcams[lat], webcams[lon] широта и долгота веб-камеры в десятичном виде;
- webcams[time] время последней загрузки снапшота на сервер в UnixTime;
- webcams[image] URL последнего снимка с веб-камеры.

Пример запроса REST(GET):
http://api.narodmon.ru/mapBounds?bounds=10,20,11,21&uuid=UUID&lang=ru&limit=10

Пример запроса JSON(POST):
{"cmd":"mapBounds","limit":10,"bounds":[10,20,11,21],"uuid":"UUID","lang":"ru"}

Ответ сервера:
{"devices":[{"id":0,"name":"..","lat":39.962502,"lon":-83.006104,"time":1734304831,"value":0.0,"type":0,"unit":""},{..}],
"webcams":[{"id":0,"name":"..","lat":39.962502,"lon":-83.006104,"time":1734304831,"image":"http://..."},{..}]}

+ sensorsNearby - запрос списка ближайших к пользователю датчиков + свои + избранные

* Для доступа к данным ваших приватных датчиков вне вашей локальной сети требуется однократная авторизация (userLogon).
** Для доступа к данным чужих публичных приборов требуется согласование, см. Профиль \ Мои приложения \ PubsLimit.


Параметры запроса:
- lat, lon опционально широта и долгота нового местонахождения пользователя в десятичном виде;
- my опционально, если = 1, то вывод датчиков только со своих приборов (требуется авторизация);
- pub опционально, если = 1, то вывод только публичных датчиков;
- radius опционально максимальное удаление от пользователя до датчиков в км, максимум ~111км (1°);
- metar опционально, если = 1, то включить в ответ сервера данные METAR в регионе (требуется авторизация);
- owmap опционально, если = 1, то включить в ответ сервера данные OWMap в регионе (требуется авторизация);
- types опционально массив кодов типов датчиков для фильтра отображения из справочника appInit;
- trends опционально, если = 1, то включить расчет тенденции показаний по МНК.

ОТВЕТ сервера:
- devices массив с перечнем приборов (ограничено PubsLimit);
- devices[id] целочисленный код прибора в проекте;
- devices[name] название прибора или его ID (если нет названия);
- devices[my] = 1, если этот прибор авторизованного пользователя, иначе = 0;
- devices[owner] ID владельца прибора в проекте;
- devices[mac] серийный номер прибора (только для владельца);
- devices[cmd] = 1, если включен режим управления прибором, иначе = 0;
- devices[lat], devices[lon] широта и долгота расположения прибора в десятичном виде;
- devices[location] населенный пункт местонахождения прибора;
- devices[distance] расстояние в км от текущего местонахождения пользователя;
- devices[time] время последней активности прибора в UnixTime;
- devices[sensors] массив с перечнем публичных и своих датчиков, подключенных к данному прибору;
- devices[sensors][id] целочисленный код датчика в проекте;
- devices[sensors][mac] метрика датчика (только для владельца);
- devices[sensors][fav] = 1, если датчик в Избранном у пользователя и = 0, если нет или не авторизован;
- devices[sensors][pub] = 1, если датчик публичный и = 0, если датчик приватный;
- devices[sensors][type] код типа датчика (см. appInit);
- devices[sensors][name] название датчика или его ID (если нет названия);
- devices[sensors][value] последнее показание датчика;
- devices[sensors][unit] единица измерения;
- devices[sensors][time] время последнего показания датчика в UnixTime;
- devices[sensors][changed] время последнего изменения показаний датчика в UnixTime;
- devices[sensors][trend] коэффициент линейного роста показаний датчика за последний час, рассчитанный по МНК.

Пример запроса REST(GET):
http://api.narodmon.ru/sensorsNearby?lat=39.962502&lon=-83.006104&radius=10&types=1,2&uuid=UUID&lang=ru

Пример запроса JSON(POST):
{"cmd":"sensorsNearby","lat":39.962502,"lon":-83.006104,"radius":10,"types":[1,2],
"uuid":"UUID","lang":"ru"}

Ответ сервера:
{"devices":[{"id":0,"name":"..","my":0,"owner":"0","mac":"..","cmd":0,"lat":0.0,"lon":0.0,"location":"..",
"distance":0.0,"time":1734304831,"sensors":[{"id":0,"mac":"..","fav":0,"pub":0,"type":0,"name":"..","value":0.0,"unit":"","time":1734304831,
"changed":1734304831,"trend":0.0},{..}]},{..}]}

+ sensorsOnDevice - запрос списка датчиков и их показаний по ID прибора

* Для доступа к данным ваших приватных датчиков вне вашей локальной сети требуется однократная авторизация (userLogon).
** Для доступа к данным чужих публичных приборов требуется согласование, см. Профиль \ Мои приложения \ PubsLimit.


Параметры запроса:
- devices массив ID приборов для запроса данных;
- trends = 1, необязательный параметр включающий расчет тенденций показаний;
- info = 1, необязательный параметр включает вывод полного описания прибора.

ОТВЕТ сервера:
- devices массив с перечнем приборов (≤ 10, ограничено PubsLimit);
- devices[id] ID прибора в проекте;
- devices[name] название прибора или его ID (если нет названия);
- devices[my] = 1, если этот прибор авторизованного пользователя, иначе = 0;
- devices[owner] ID владельца прибора в проекте;
- devices[mac] серийный номер прибора (только для владельца);
- devices[cmd] = 1, если включен режим управления прибором, иначе = 0;
- devices[lat], devices[lon] широта и долгота расположения прибора в десятичном виде;
- devices[location] населенный пункт местонахождения прибора;
- devices[distance] расстояние в км от текущего местонахождения пользователя;
- devices[time] время последней активности прибора в UnixTime;
- devices[site] ссылка на сайт владельца прибора, иначе https://narodmon.ru/id;
- devices[photo] ссылка на фото прибора (если владелец его загрузил), иначе пустая строка;
- devices[info] описание прибора (если info = 1), иначе длина описания в байтах или пустая строка;
- devices[sensors] массив датчиков подключенных к указанному прибору;
- devices[sensors][id] целочисленный код датчика в проекте;
- devices[sensors][pub] = 1, если датчик публичный и = 0, если датчик приватный;
- devices[sensors][type] код типа датчика (см. appInit);
- devices[sensors][name] название датчика или его ID (если нет названия);
- devices[sensors][value] последнее показание датчика;
- devices[sensors][unit] единица измерения;
- devices[sensors][time] время последнего показания датчика в UnixTime;
- devices[sensors][changed] время последнего изменения показаний датчика в UnixTime;
- devices[sensors][trend] коэффициент линейного роста показаний датчика за последний час, рассчитанный по МНК.

Пример запроса REST(GET):
http://api.narodmon.ru/sensorsOnDevice?devices=1,2&uuid=UUID&lang=ru

Пример запроса JSON(POST):
{"cmd":"sensorsOnDevice","devices":[1,2],"uuid":"UUID","lang":"ru"}

Ответ сервера:
{"devices":[{"id":1,"name":"..","my":0,"owner":"0","mac":"","cmd":0,"lat":0.0,"lon":0.0,"location":"..","distance":0.0,"time":1734304831,
"site":"https://narodmon.ru/1","photo":"","info":"220B",
"sensors":[{"id":1,"mac":"","fav":0,"pub":1,"type":1,"name":"..","value":0.0,"unit":"",
"time":1734304831,"changed":1734304831,"trend":0},{..}]},{..}]}

+ sensorsValues - регулярное обновление показаний выбранных датчиков

* Для доступа к данным ваших приватных датчиков вне вашей локальной сети требуется однократная авторизация (userLogon).
** Для доступа к данным чужих публичных приборов требуется согласование, см. Профиль \ Мои приложения \ PubsLimit.


Параметры запроса:
- sensors массив кодов датчиков для запроса показаний;
- trends = 1, необязательный параметр включающий расчет тендеции показаний.

ОТВЕТ сервера:
- sensors массив показаний запрошенных датчиков (≤ 30, ограничено PubsLimit);
- sensors[id] целочисленный код датчика в проекте;
- sensors[type] код типа датчика (см. appInit);
- sensors[value] последнее показание датчика;
- sensors[time] время последнего показания датчика в UnixTime;
- sensors[changed] время последнего изменения показаний датчика в UnixTime;
- sensors[trend] коэффициент линейного роста показаний датчика за последний час, рассчитанный по МНК.

Пример запроса REST(GET):
http://api.narodmon.ru/sensorsValues?sensors=1,2&uuid=UUID

Пример запроса JSON(POST):
{"cmd":"sensorsValues","sensors":[1,2],"uuid":"UUID"}

Ответ сервера:
{"sensors":[{"id":1,"type":0,"value":0,"time":1734304831,"changed":1734304831,"trend":0},{..}]}

+ sensorsHistory - история показаний датчика за период (для графиков и тенденций)

* Для доступа к данным ваших приватных датчиков вне вашей локальной сети требуется однократная авторизация (userLogon).
Параметры запроса:
- id код датчика для запроса истории показаний (или sensors);
- sensors массив кодов датчиков для запроса показаний (или id);
- period название периода показаний: 'hour','day','week','month','year';
- offset смещение по выбранному периоду в прошлое, т.е. 1(day) = вчера, 1(month) = прошл.месяц.

ОТВЕТ сервера:
- sensors массив запрошенных датчиков;
- sensors[id] целочисленный код датчика в проекте;
- sensors[type] код типа датчика (см. appInit);
- sensors[name] название датчика или его ID (если нет названия);
- sensors[unit] единица измерения;
- data массив показаний запрошенного датчика;
- data[id] целочисленный код датчика в проекте;
- data[time] время показания датчика в UnixTime;
- data[value] показание датчика в указанный момент времени.

Пример запроса REST(GET):
http://api.narodmon.ru/sensorsHistory?id=1&period=day&offset=0&uuid=UUID

Пример запроса JSON(POST):
{"cmd":"sensorsHistory","id":1,"period":"day","offset":0,"uuid":"UUID"}

Ответ сервера:
{"sensors":[{"id":1,"type":1,"name":"..","unit":".."}],"data":[{"id":1,"time":1734304831,"value":0.0},{..}]}

+ nameSensor - смена имени датчика (для владельца) или создание алиаса для остальных

Параметры запроса:
- id целочисленный код датчика в проекте;
- name новое название датчика, если пустое, то меняется на по умолчанию.

Пример запроса REST(GET):
http://api.narodmon.ru/nameSensor?id=1&name=NewName&uuid=UUID

Пример запроса JSON(POST):
{"cmd":"nameSensor","id":1,"name":"NewName","uuid":"UUID"}

Ответ сервера:
{"result":"OK"}

+ pubSensor - запрос публикации приватного датчика

Параметры запроса:
- id целочисленный код датчика в проекте.

ОТВЕТ сервера:
- id целочисленный код датчика в проекте;
- code код датчика для добавления в Избранное.

Пример запроса REST(GET):
http://api.narodmon.ru/pubSensor?id=123456&uuid=UUID

Пример запроса JSON(POST):
{"cmd":"pubSensor","id":123456,"uuid":"UUID"}

Ответ сервера:
{"id":123456,"code":123456}

+ webcamsNearby - запрос списка ближайших к пользователю веб-камер + свои + избранные

Параметры запроса:
- lat, lon опционально широта и долгота местонахождения пользователя в десятичном виде;
- radius опционально максимальное удаление от пользователя до веб-камеры в км, максимум ~111км (1°);
- my опционально, если = 1, то вывод только своих вебкамер (требуется авторизация);
- width опционально ширина экрана клиентского устройства в пикселях для оптимизации размера загружаемых снимков.

ОТВЕТ сервера:
- webcams массив с перечнем веб-камер;
- webcams[id] целочисленный код веб-камеры в проекте;
- webcams[name] название веб-камеры (как назвал владелец);
- webcams[my] = 1, если веб-камера авторизованного пользователя, иначе = 0;
- webcams[owner] имя владельца веб-камеры в проекте;
- webcams[fav] = 1, если веб-камера в Избранном у пользователя и = 0, если нет или не авторизован;
- webcams[distance] расстояние в км от текущего местонахождения пользователя;
- webcams[location] населенный пункт местонахождения веб-камеры;
- webcams[time] время последней загрузки снапшота на сервер в UnixTime;
- webcams[lat], webcams[lon] широта и долгота расположения веб-камеры в градусах в десятичном виде;
- webcams[image] URL последнего снимка с веб-камеры;

Пример запроса REST(GET):
http://api.narodmon.ru/webcamsNearby?radius=10&lat=39.962502&lon=-83.006104&uuid=UUID&lang=ru

Пример запроса JSON(POST):
{"cmd":"webcamsNearby","radius":10,"lat":39.962502,"lon":-83.006104,"uuid":"UUID","lang":"ru"}

Ответ сервера:
{"webcams":[{"id":1,"name":"..","my":0,"owner":"1","fav":0,"distance":0.0,"lat":39.962502,"lon":-83.006104,"location":"..",
"time":1734304831,"image":"http://.."},{..}]}

+ webcamImages - запрос списка снимков с веб-камеры по ее ID

Параметры запроса:
- id ID веб-камеры из ссылки вида http://narodmon.ru/-ID в балуне на карте;
- limit опционально кол-во снимков в ответе сервера, по умолчанию 20, максимум 50;
- since опционально время первого снимка в выборке в UnixTime, по умолчанию равно 0;
- latest опционально время последнего снимка в выборке в UnixTime, по умолчанию равно текущему;
- width опционально ширина экрана клиентского устройства в пикселях для оптимизации размера загружаемых снимков.

ОТВЕТ сервера:
- id целочисленный код веб-камеры в проекте;
- name название веб-камеры (как назвал владелец);
- location населенный пункт местонахождения веб-камеры;
- distance расстояние в км от текущего местонахождения пользователя;
- images массив снимков с веб-камеры находящихся на сервере;
- images[time] время актуальности снимка в UnixTime;
- images[image] URL для скачивания снимка.

Пример запроса REST(GET):
http://api.narodmon.ru/webcamImages?id=1&limit=10&uuid=UUID

Пример запроса JSON(POST):
{"cmd":"webcamImages","id":1,"limit":10,"uuid":"UUID"}

Ответ сервера:
{"id":1,"name":"..","location":"..","distance":0.0,
"images":[{"time":1734304831,"image":"http://.."},{..}]}

+ userLogon - аутентификация пользователя в проекте или его регистрация

Параметры запроса:
- login логин пользователя для авторизации, если он не указан, то возвращается текущий логин для указанного uuid;
- hash хэш для авторизации, вычисляется по формуле с объединением строк MD5(uuid + MD5(введенный пароль)), если хэш не указан, то считается запросом на регистрацию в проекте по email/sms.

ОТВЕТ сервера:
- tz часовой пояс пользователя в проекте в UTC;
- vip = 1 признак партнера, донатора, разработчика, администрации, для остальных = 0;
- login имя авторизованного пользователя для текущего uuid или пустая строка;
- uid = ID участника проекта.

Пример запроса REST(GET):
http://api.narodmon.ru/userLogon?login=MyName&hash=MD5HASH&uuid=UUID&lang=ru

Пример запроса JSON(POST):
{"cmd":"userLogon","login":"MyName","hash":"MD5HASH","uuid":"UUID","lang":"ru"}

Ответ сервера:
{"uid":1,"tz":3,"login":"MyName","vip":0}

+ userLocation - запрос текущего и установка нового местонахождение пользователя (точки отсчета)

Параметры запроса:
- lat, lon опционально широта и долгота местонахождения пользователя;
- addr опционально ближайший адрес к местонахождению пользователя;
- wifi опциональный массив точек доступа WiFi поблизости;
- wifi[bssid] MAC адрес точки доступа;
- wifi[rssi] уровень сигнала точки доступа в dBm (<0);
- cells опциональный массив сотовых станций поблизости;
- cells[bssid] = MCC[3]:MNC[3]:LAC[4]:CID[7] в hex виде;
- cells[rssi] уровень сигнала сотовой станции в dBm (<0);
- gui флаг указывающий на необходимость получения полного адреса.

ОТВЕТ сервера:
- lat, lon широта и долгота нового местонахождения пользователя в десятичном виде;
- addr ближайший адрес к найденным координатам (при gui = 1).

Пример запроса по координатам REST(GET):
http://narodmon.ru/api/userLocation?lat=39.962502&lon=-83.006104&uuid=UUID&lang=ru

Пример запроса по адресу REST(GET):
http://api.narodmon.ru/userLocation?addr=..&uuid=UUID&lang=ru

Пример запроса по координатам JSON(POST):
{"cmd":"userLocation","lat":39.962502,"lon":-83.006104,"uuid":"UUID","lang":"ru"}

Пример запроса по адресу JSON(POST):
{"cmd":"userLocation","addr":"..","uuid":"UUID","lang":"ru"}

Пример запроса по WiFi сетям JSON(POST):
{"cmd":"userLocation",
"wifi":[{"bssid":"00:00:00:00:00:00","rssi":-0},{..}],"uuid":"UUID","lang":"ru"}

Пример запроса по сотовым сетям JSON(POST):
{"cmd":"userLocation",
"cells":[{"bssid":"000:000:0000:0000000","rssi":-0},{..}],"uuid":"UUID","lang":"ru"}

Ответ сервера:
{"lat":39.962502,"lon":-83.006104,"addr":".."}

+ userFavorites - управление списком избранных датчиков и веб-камер

Параметры запроса:
- sensors опционально новый массив id избранных датчиков (список будет заменен, для его очистки передать "sensors":[0]);
- webcams опционально новый массив id избранных веб-камер (список будет заменен, для его очистки передать "webcams":[0]).

ОТВЕТ сервера:
- sensors массив избранных датчиков авторизованного пользователя;
- sensors[id] целочисленный код датчика в проекте;
- sensors[did] целочисленный код прибора в проекте;
- sensors[type] код типа датчика (см. appInit);
- sensors[name] название датчика или его ID (если нет названия);
- sensors[value] последнее показание датчика;
- sensors[unit] единица измерения;
- sensors[time] время последнего показания датчика в UnixTime;
- webcams массив избранных веб-камер авторизованного пользователя;
- webcams[id] целочисленный код веб-камеры в проекте, если <0 то удалить из списка;
- webcams[name] название веб-камеры или http-ссылка (как назвал владелец);
- webcams[time] время последней загрузки снапшота на сервер в UnixTime;
- webcams[image] URL последнего снимка с веб-камеры.

Пример запроса REST(GET):
http://api.narodmon.ru/userFavorites?sensors=1,2&webcams=1,2&uuid=UUID&lang=ru

Пример запроса JSON(POST):
{"cmd":"userFavorites","uuid":"UUID",
"sensors":[1,2],"webcams":[1,2],"lang":"ru"}

Ответ сервера:
{"sensors":[{"id":1,"did":1,"type":1,"name":"..","value":0.0,"time":1734304831},{..}],
"webcams":[{"id":1,"name":"..","time":1734304831,"image":"http://.."},{..}]}

+ userLogout - завершение сеанса текущего пользователя

Параметры запроса:
* нет параметров *

ОТВЕТ сервера:
- login имя авторизованного пользователя для текущего uuid;
- uid ID участника проекта.

Пример запроса REST(GET):
http://api.narodmon.ru/userLogout?uuid=UUID

Пример запроса JSON(POST):
{"cmd":"userLogout","uuid":"UUID"}

Ответ сервера:
{"login":"","uid":0}

+ addLike - отметка "Мне нравится" на снимках с веб-камер и приборах.

Параметры запроса:
- id веб-камеры(<0) или прибора(>0).

ОТВЕТ сервера:
- id веб-камеры(<0) или прибора(>0);
- time время отметки в UnixTime;
- liked общее число отметок "Нравится" на объекте после выполнения.

Пример запроса REST(GET):
http://api.narodmon.ru/addLike?id=1&uuid=UUID

Пример запроса JSON(POST):
{"cmd":"addLike","id":1,"uuid":"UUID"}

Ответ сервера:
{"id":1,"time":1734304831,"liked":1}

+ disLike - снятие отметки "Мне нравится" на снимках с веб-камер и приборах

Параметры запроса:
- id веб-камеры(<0) или прибора(>0).

ОТВЕТ сервера:
- id веб-камеры(<0) или прибора(>0);
- time время снятия отметки в UnixTime;
- liked общее число отметок "Нравится" на объекте после выполнения.

Пример запроса REST(GET):
http://api.narodmon.ru/disLike?id=1&uuid=UUID

Пример запроса JSON(POST):
{"cmd":"disLike","id":1,"uuid":"UUID"}

Ответ сервера:
{"id":1,"time":1734304831,"liked":0}

+ setPushToken, setPushURI - установка параметров отправки PUSH уведомлений. Используется FireBase (Android, iOS) и WNS (Windows)

Параметры запроса:
- token токен для Android и iOS;
- uri URL для Windows Mobile и Windows Phone.

Пример запроса REST(GET):
FireBase: http://api.narodmon.ru/setPushToken?token=..&uuid=UUID
WNS: http://api.narodmon.ru/setPushURI?uri=..&uuid=UUID

Пример запроса JSON(POST):
FireBase: {"cmd":"setPushToken","token":"..","uuid":"UUID"}
WNS: {"cmd":"setPushURI","uri":"https://..","uuid":"UUID"}

Ответ сервера:
{"result":"OK"}


PUSH сообщения от FireBase приходят в коллекции java.util.Map с полями:
- id идентификатор сообщения (int unsigned);
- uid идентификатор пользователя (int signed);
- time время отправки сообщения UnixTime (int unsigned);
- subj заголовок сообщения;
- body полный текст сообщения.

PUSH сообщения от WNS приходят в виде структуры JSON:
{"id":ID,"uid":UserID,"time":1734304831,"subj":"..","body":".."}

+ setPushStatus - отправка отчета о доставке/прочтении PUSH-уведомления

Параметры запроса:
- states массив со статусами полученных сообщений:
- states[id] идентификатор полученного сообщения (int unsigned);
- states[time] время отправки сообщения в UnixTime;
- states[status] код текущего статуса сообщения (201 - получено, 202 - прочтено).

Пример запроса REST(GET):
http://api.narodmon.ru/setPushStatus?id=1&time=1734304831&status=201&uuid=UUID

Пример запроса JSON(POST):
{"cmd":"setPushStatus","states":[{"id":1,"time":1734304831,"status":201},{..}],"uuid":"UUID"}

Ответ сервера:
{"result":"OK"}


PUSH сообщения от FireBase приходят в коллекции java.util.Map с полями:
- id идентификатор сообщения (int unsigned);
- uid идентификатор пользователя (int signed);
- time время отправки сообщения UnixTime (int unsigned);
- subj заголовок сообщения;
- body полный текст сообщения.

PUSH сообщения от WNS приходят в виде структуры JSON:
{"id":ID,"uid":UserID,"time":1734304831,"subj":"..","body":".."}

Во избежание ошибки 429 (слишком частые запросы), настоятельно рекомендуется аккумулировать статусы доставки PUSH-сообщений и отправлять их пакетами не чаще 1 раза в минуту!

+ sendCommand - отправка команды управления на прибор

Параметры запроса:
- id ID приборов в проекте (integer unsigned);
- command строка команды, шаблон PCRE [a-z0-9_\-\+\=\;\/\.]+

Пример запроса REST(GET):
http://api.narodmon.ru/sendCommand?id=1&command=reboot&uuid=UUID

Пример запроса JSON(POST):
{"cmd":"sendCommand","id":1,"command":"gpio12=1","uuid":"UUID"}

Ответ сервера:
{"result":"OK"}

+ sendComplaint - отправка жалобы на ошибочное показание датчика или снимка с веб-камеры

Параметры запроса:
- id код датчика (id>0) или веб-камеры (id<0);
- time UnixTime времени возникновения проблемы;
- name имя заявителя для обратной связи;
- email почта заявителя для обратной связи;
- problem краткое описание сути проблемы;
- value каким должно быть показание датчика (для id>0).

Пример запроса REST(GET):
http://api.narodmon.ru/sendComplaint?id=1&time=1734304831&value=0
&name=..&email=..&problem=..&uuid=UUID

Пример запроса JSON(POST):
{"cmd":"sendComplaint","id":1,"time":1734304831,"value":0,
"name":"..","email":"..","problem":"..","uuid":"UUID"}

Ответ сервера:
{"result":"OK"}

+ sendMessage - отправка сообщения в беседу или вопроса к Администрации

Параметры запроса:
- uid опционально ID получателя, по умолчанию Администрация;
- name опционально имя заявителя для обращения;
- email опционально почта заявителя для дублирования;
- chat опционально ID беседы из getDialog;
- subj обязательно тема обращения;
- mess обязательно текст сообщения;
- images[..] опционально массив вложенных изображений (до 1МБ) в виде base64 строк.

Пример запроса REST(GET):
http://api.narodmon.ru/sendMessage?uid=1&name=..&email=..&subj=..&mess=..&uuid=UUID

Пример запроса JSON(POST):
{"cmd":"sendMessage","uid":1,"name":"..","email":"..","subj":"..","mess":"..","uuid":"UUID"}

Ответ сервера:
{"result":"OK"}

+ weatherReport - отправка метеоданных пользователем с автономных метеоприборов

Параметры запроса:
- lat, lon широта и долгота прибора на момент отправки (предварительно обновить геолокацию!);
- temp показания уличного термометра (если он есть) °C;
- humid показания уличного гигрометра (если он есть) %;
- press показания бытового барометра (если он есть) мм рт.ст.;
- wind азимут направления ветра (если есть анемометр) 0-360°.

Пример запроса REST(GET):
http://api.narodmon.ru/weatherReport?lat=39.962502&lon=-83.006104&temp=00&humid=00&press=000&wind=000
&lang=ru&uuid=UUID

Пример запроса JSON(POST):
{"cmd":"weatherReport","lat":39.962502,"lon":-83.006104,"temp":00,"humid":00,"press":000,"wind":000,
"lang":"ru","uuid":"UUID"}

Ответ сервера:
{"result":"Вы сообщили следующие данные:..."}


Если отчет о погоде будет отправлен менее чем через час после предыдущего, то он посчитается исправлением и заменит его.

+ bugReport - отправка отзыва на приложение и багрепортов с техданными для отладки

Параметры запроса:
- time опционально UnixTime момента возникновения сбоя;
- name опционально имя заявителя для обращения;
- email опционально почта заявителя для дублирования;
- mess опционально текст сообщения пользователя;
- logs опционально технические данные для отладки;
- images[..] опционально массив вложенных изображений (до 1МБ) в виде base64 строк.

Пример запроса REST(GET):
http://api.narodmon.ru/bugReport?time=1734304831&name=..&email=..&mess=..&logs=..&uuid=UUID

Пример запроса JSON(POST):
{"cmd":"bugReport","time":1734304831,"name":"..","email":"..","mess":"..","logs":"..","uuid":"UUID"}

Ответ сервера:
{"result":"OK"}


Уведомление о багрепорте в краткой форме будет отправлено автору приложения используя PUSH, а на e-mail автора будет отправлена полная версия вместе с техданными для отладки.

+ getHelp - запрос справочной информации о проекте

Параметры запроса:
- topic опционально идентификатор статьи, если он не указан, то возвращается оглавление.

ОТВЕТ сервера:
- topics массив со список статей;
- topics[topic] идентификатор статьи;
- topics[group] название раздела Справки;
- topics[title] название статьи из Справки;
- topics[body] html-текст статьи (если был указан topic) или хеш статьи в оглавлении.

Пример запроса оглавления REST(GET):
http://api.narodmon.ru/getHelp?lang=ru&uuid=UUID

Пример запроса оглавления JSON(POST):
{"cmd":"getHelp","lang":"ru","uuid":"UUID"}

Ответ сервера с оглавлением:
{"topics":[{"topic":"topic1","group":"Раздел1","title":"Заголовок1","body":"c8542aec71a1a1e371f39553ae3b7ec7"},{..}]}

Пример запроса текста статьи REST(GET):
http://narodmon.ru/api/getHelp?topic=topic1&lang=ru&uuid=UUID

Пример запроса текста статьи JSON(POST):
{"cmd":"getHelp","topic":"topic1","lang":"ru","uuid":"UUID"}

Ответ сервера с текстом статьи:
{"topics":[{"topic":"topic1","group":"Раздел1","title":"Заголовок1","body":"html-текст"}]}


Настоятельно рекомендуется кешировать тексты уже скачанных ранее статей в виду их существенного объёма, но при этом периодически обновлять оглавление и в случае изменения хеша статьи её следует перезакачать с сервера указав её topic и обновить title и body в локальном кеше приложения.

+ Пример на PHP + cURL для вывода показаний на свой сайт

// кодировка ответа сервера
header('Content-Type: text/html; charset=utf-8');

// подготовка параметров запроса
$request = array('cmd'=>'sensorsNearby', 'lat'=>55.75, 'lon'=>37.62, 'radius'=>11, 'uuid'=>md5('mysite.ru'), 'api_key'=>'MY_API_KEY', 'lang'=>'ru');

// исполнение запроса
$ch = curl_init('http://api.narodmon.ru');
if(!$ch) exit('Ошибка инициализации cURL');
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.ru');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($request));
$reply = curl_exec($ch);
curl_close($ch);
if(empty($reply)) exit('Ошибка сети');

// декодирование ответа из JSON в массив
$data = json_decode($reply, true);
if(empty($data) or !is_array($data)) {
  exit('Ошибочные данные'); }

// если была ошибка API
if(isset($data['error'])) exit($data['error']);

// выводим в цикле показания датчиков
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 без cURL для вывода показаний на свой сайт

// кодировка ответа сервера
header('Content-Type: text/html; charset=utf-8');

// подготовка параметров запроса
$request = array('cmd'=>'sensorsNearby', 'lat'=>55.75, 'lon'=>37.62, 'radius'=>11, 'uuid'=>md5('mysite.ru'), 'api_key'=>'MY_API_KEY', 'lang'=>'ru');

// исполнение запроса
$header = "User-Agent: mysite.ru\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.ru', false, stream_context_create($context));
if(empty($reply)) exit('Ошибка сети');

// декодирование ответа из JSON в массив
$data = json_decode($reply, true);
if(empty($data) or !is_array($data)) {
  exit('Ошибочные данные'); }

// если была ошибка API
if(isset($data['error'])) exit($data['error']);

// выводим в цикле показания датчиков
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"; }}

+ Пример на Python2 для вывода показаний на свой сайт

#!/usr/bin/env python2
# -*- coding: utf-8 -*-
# by Roman Vishnevsky aka.x0x01 @ gmail.com

import urllib2
import json
import hashlib
import uuid

# ключ API для разработчика, получаемый в Мои данные \ Мои приложения после регистрации в проекте.
# заменить на свой!
api_key = 'abcdefABCDEF'

# генерация уникального ID приложения
app_id = str(uuid.getnode())
md5_app_id = hashlib.md5(app_id).hexdigest()

# формирование тела JSON
data = {
'cmd': 'sensorsNearby',
'uuid': md5_app_id,
'api_key': api_key,
'radius': 11,
'lat': 55.75,
'lon': 37.62,
'lang': 'ru'
}

# обработчик исключений
try:
# запрос
request = urllib2.Request('http://api.narodmon.ru', json.dumps(data))
response = urllib2.urlopen(request)
# работа с JSON
result = json.loads(response.read())

# вывод всего массива
print json.dumps(result, indent=4, sort_keys=True)
# или по ключу
# print result['devices']
# или по ключу в цикле
# for dev in result['devices']:
# print dev['name'], dev['distance']

except urllib2.URLError, e:
print 'HTTP error:', e

except (ValueError, TypeError), e:
print 'JSON error:', e

+ Пример на Python3 для вывода показаний на свой сайт

# Гладышев Дмитрий aka nightflash

import requests
import hmac, hashlib
import json
import uuid

# ключ API для разработчика, получаемый в Мои данные \ Мои приложения после регистрации в проекте.
# заменить на свой!
api_key = 'abcdef123456'

# генерация уникального ID приложения
app_id = str(uuid.getnode())
md5_app_id = hashlib.md5(app_id.encode()).hexdigest()

# формирование тела JSON
data = {
'cmd': 'sensorsNearby',
'uuid': md5_app_id,
'api_key': api_key,
'radius': 11,
'lat': 55.75,
'lon': 37.62,
'lang': 'ru'
}

# обработчик исключений
try:
# запрос
request = requests.post('http://api.narodmon.ru', data=json.dumps(data))

# работа с JSON
result = json.loads(request.text)

# вывод всего массива
print(json.dumps(result, indent=4, sort_keys=True))
# или по ключу
# print(result['devices'])
# или по ключу в цикле
# for dev in result['devices']:
# print(dev['name'], dev['distance'])

except Exception as err:
print(f"Unexpected {err=}, {type(err)=}")