Форматы, кодировки, http-заголовки, ограничения
Запросы принимаются в кодировке UTF-8 по адресу http(s)://narodmon.ru/api в формате JSON (HTTP POST) или REST (HTTP GET).
Ответ сервера будет в формате JSON и кодировке UTF-8, в случае ошибки возвращается: {"error":"Error message","errno":N}.
Следует знать, что запросы HTTP POST более безопасны, чем HTTP GET, т.к. параметры запроса не попадают в лог прокси и веб-серверов и не кешируются.
- Accept-Encoding: gzip, deflate - необязательный заголовок для экономии трафика, если ваше приложение поддерживает gzip-сжатие.
- User-Agent: MyAppName (название приложения на латинице) - обязательный заголовок, без которого веб-сервер сочтет ваш запрос за подделку.
Для доступа к данным приватных датчиков и веб-камер предварительно надо выполнить запрос авторизации userLogon, если это не было сделано ранее или при запуске Вашего приложения (а также 1 раз в сутки) appInit вернул логин авторизованного пользователя.
Ограничения в использовании нашего REST API:
- Доступ к API бесплатен только в личных некоммерческих целях.
- Использование данных проекта на сторонних ресурсах возможно только по согласованию с Администрацией и это не бесплатно.
- Для получения доступа к чужим публичным данным надо написать в техподдержку, для запроса только своих данных этого не требуется.
- Интервал опроса датчиков, приборов, веб-камер не чаще 1 раза в минуту для каждого клиента вашего приложения и для каждого IP, иначе сервер вернет ошибку HTTP 429, а при длительном её игнорировании заблокирует ваш ключ доступа к API.
Справочник кодов ошибок REST API (errno)
- 400 - ошибка синтаксиса в запросе к API;
- 401 - требуется авторизация;
- 403 - в доступе к объекту отказано;
- 404 - искомый объект не найден;
- 423 - ключ API заблокирован администратором;
- 429 - более 1 запроса в минуту;
- 434 - искомый объект отключен;
- 503 - сервер временно не обрабатывает запросы по техническим причинам.
Обязательные параметры, которые следует передавать в КАЖДОМ запросе.
- cmd название метода API;
- ang язык интерфейса приложения ISO 639-1 ("ru","en","uk");
- uuid уникальный идентификатор пользователя приложения, представляющий собой MD5-хеш в нижнем регистре однократно сгенерированный приложением в момент его установки. Используется для определения настроек локализации, местоположения и др.;
- pi_key ключ API для разработчика, представляющий собой уникальный идентификатор приложения, получаемый в разделе Мои Приложения и используемый для определения лимитов приложения и авторства.
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://narodmon.ru/api/appInit?version=1.1&platform=6.0.1&uuid=UUID&api_key=API_KEY&lang=ru&utc=3
Пример запроса JSON(POST):
{"cmd":"appInit","version":"1.1","platform":"6.0.1","uuid":"UUID","api_key":"API_KEY","lang":"ru","utc":3}
Ответ сервера:
{"latest":"1.2","url":"http://mysite.ru/myapp.exe","login":"..","vip":0,"lat":55.747899,"lon":37.6171,"addr":"..","types":[{"type":0,"name":"..","unit":""},{..}],"favorites":[1,2,..],"timestamp":1711086535}
mapBounds - запрос списка датчиков и веб-камер в указанной прямоугольной области карты
* Для доступа к данным чужих публичных приборов требуется согласование, см. Профиль \ Мои приложения \ PubsLimit.
Параметры запроса:
- bounds массив координат углов области просмотра {широта-мин, долгота-мин, широта-макс, долгота-макс} в десятичном виде;
- metar опционально, если = 1, то включить в ответ сервера данные METAR в регионе (требуется авторизация);
- owmap опционально, если = 1, то включить в ответ сервера данные OWMap в регионе (требуется авторизация);
- types опционально массив кодов типов датчиков для фильтра отображения из справочника appInit.
ОТВЕТ сервера:
- devices массив с перечнем приборов и их датчиков в выбранной области просмотра;
- 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://narodmon.ru/api/mapBounds?bounds=10,20,11,21&uuid=UUID&api_key=API_KEY&lang=ru&limit=10
Пример запроса JSON(POST):
{"cmd":"mapBounds","limit":10,"bounds":[10,20,11,21],"uuid":"UUID","api_key":"API_KEY","lang":"ru"}
Ответ сервера:
{"devices":[{"id":0,"name":"..","lat":55.747899,"lon":37.6171,"time":1711086535,"value":0.0,"type":0,"unit":""},{..}],
"webcams":[{"id":0,"name":"..","lat":55.747899,"lon":37.6171,"time":1711086535,"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 массив с перечнем приборов, к которым подключены публичные или свои датчики;
- 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://narodmon.ru/api/sensorsNearby?lat=55.747899&lon=37.6171&radius=10&types=1,2&uuid=UUID&api_key=API_KEY&lang=ru
Пример запроса JSON(POST):
{"cmd":"sensorsNearby","lat":55.747899,"lon":37.6171,"radius":10,"types":[1,2],"uuid":"UUID","api_key":"API_KEY","lang":"ru"}
Ответ сервера:
{"devices":[{"id":0,"name":"..","my":0,"owner":"0","mac":"..","cmd":0,"lat":0.0,"lon":0.0,"location":"..","distance":0.0,"time":1711086535,"sensors":[{"id":0,"mac":"..","fav":0,"pub":0,"type":0,"name":"..","value":0.0,"unit":"","time":1711086535,"changed":1711086535,"trend":0.0},{..}]},{..}]}
sensorsOnDevice - запрос списка датчиков и их показаний по ID прибора
* Для доступа к данным ваших приватных датчиков вне вашей локальной сети требуется однократная авторизация (userLogon). ** Для доступа к данным чужих публичных приборов требуется согласование, см. Профиль \ Мои приложения \ PubsLimit.
Параметры запроса:
- devices массив ID приборов для запроса данных;
- trends = 1, необязательный параметр включающий расчет тенденций показаний;
- info = 1, необязательный параметр включает вывод полного описания прибора.
ОТВЕТ сервера:
- 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://narodmon.ru/api/sensorsOnDevice?devices=1,2&uuid=UUID&api_key=API_KEY&lang=ru
Пример запроса JSON(POST):
{"cmd":"sensorsOnDevice","devices":[1,2],"uuid":"UUID","api_key":"API_KEY","lang":"ru"}
Ответ сервера:
{"devices":[{"id":1,"name":"..","my":0,"owner":"0","mac":"","cmd":0,"lat":0.0,"lon":0.0,"location":"..","distance":0.0,"time":1711086535,
"site":"https://narodmon.ru/1","photo":"","info":"220B",
"sensors":[{"id":1,"mac":"","fav":0,"pub":1,"type":1,"name":"..","value":0.0,"unit":"",
"time":1711086535,"changed":1711086535,"trend":0},{..}]},{..}]}
sensorsValues - регулярное обновление показаний выбранных датчиков
* Для доступа к данным ваших приватных датчиков вне вашей локальной сети требуется однократная авторизация (userLogon). ** Для доступа к данным чужих публичных приборов требуется согласование, см. Профиль \ Мои приложения \ PubsLimit.
Параметры запроса:
- sensors массив кодов датчиков для запроса показаний;
- trends = 1, необязательный параметр включающий расчет тендеции показаний.
ОТВЕТ сервера:
- sensors массив показаний запрошенных датчиков;
- sensors[id] целочисленный код датчика в проекте;
- sensors[type] код типа датчика (см. appInit);
- sensors[value] последнее показание датчика;
- sensors[time] время последнего показания датчика в UnixTime;
- sensors[changed] время последнего изменения показаний датчика в UnixTime;
- sensors[trend] коэффициент линейного роста показаний датчика за последний час, рассчитанный по МНК.
Пример запроса REST(GET):
http://narodmon.ru/api/sensorsValues?sensors=1,2&uuid=UUID&api_key=API_KEY
Пример запроса JSON(POST):
{"cmd":"sensorsValues","sensors":[1,2],"uuid":"UUID","api_key":"API_KEY"}
Ответ сервера:
{"sensors":[{"id":1,"type":0,"value":0,"time":1711086535,"changed":1711086535,"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://narodmon.ru/api/sensorsHistory?id=1&period=day&offset=0&uuid=UUID&api_key=API_KEY
Пример запроса JSON(POST):
{"cmd":"sensorsHistory","id":1,"period":"day","offset":0,"uuid":"UUID","api_key":"API_KEY"}
Ответ сервера:
{"sensors":[{"id":1,"type":1,"name":"..","unit":".."}],"data":[{"id":1,"time":1711086535,"value":0.0},{..}]}
nameSensor - смена имени датчика (для владельца) или создание алиаса для остальных
Параметры запроса:
- id целочисленный код датчика в проекте;
- name новое название датчика, если пустое, то меняется на по умолчанию.
Пример запроса REST(GET):
http://narodmon.ru/api/nameSensor?id=1&name=NewName&uuid=UUID&api_key=API_KEY
Пример запроса JSON(POST):
{"cmd":"nameSensor","id":1,"name":"NewName","uuid":"UUID","api_key":"API_KEY"}
Ответ сервера:
{"result":"OK"}
pubSensor - запрос публикации приватного датчика
Параметры запроса:
- id целочисленный код датчика в проекте.
ОТВЕТ сервера:
- id целочисленный код датчика в проекте;
- code код датчика для добавления в Избранное.
Пример запроса REST(GET):
http://narodmon.ru/api/pubSensor?id=123456&uuid=UUID&api_key=API_KEY
Пример запроса JSON(POST):
{"cmd":"pubSensor","id":123456,"uuid":"UUID","api_key":"API_KEY"}
Ответ сервера:
{"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://narodmon.ru/api/webcamsNearby?radius=10&lat=55.747899&lon=37.6171&uuid=UUID&api_key=API_KEY&lang=ru
Пример запроса JSON(POST):
{"cmd":"webcamsNearby","radius":10,"lat":55.747899,"lon":37.6171,"uuid":"UUID","api_key":"API_KEY","lang":"ru"}
Ответ сервера:
{"webcams":[{"id":1,"name":"..","my":0,"owner":"1","fav":0,"distance":0.0,"lat":55.747899,"lon":37.6171,"location":"..","time":1711086535,"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://narodmon.ru/api/webcamImages?id=1&limit=10&uuid=UUID&api_key=API_KEY
Пример запроса JSON(POST):
{"cmd":"webcamImages","id":1,"limit":10,"uuid":"UUID","api_key":"API_KEY"}
Ответ сервера:
{"id":1,"name":"..","location":"..","distance":0.0,"images":[{"time":1711086535,"image":"http://.."},{..}]}
userLogon - авторизация пользователя в проекте или его регистрация
Параметры запроса:
- login логин пользователя для авторизации, если он не указан, то возвращается текущий логин для указанного uuid;
- hash хэш для авторизации, вычисляется по формуле с объединением строк MD5(uuid + MD5(введенный пароль)), если хэш не указан, то считается запросом на регистрацию в проекте по email/sms.
ОТВЕТ сервера:
- tz часовой пояс пользователя в проекте в UTC;
- vip = 1 признак партнера, донатора, разработчика, администрации, для остальных = 0;
- login имя авторизованного пользователя для текущего uuid или пустая строка;
- uid = ID участника проекта.
Пример запроса REST(GET):
http://narodmon.ru/api/userLogon?login=MyName&hash=MD5HASH&uuid=UUID&api_key=API_KEY&lang=ru
Пример запроса JSON(POST):
{"cmd":"userLogon","login":"MyName","hash":"MD5HASH","uuid":"UUID","api_key":"API_KEY","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=55.747899&lon=37.6171&uuid=UUID&api_key=API_KEY&lang=ru
Пример запроса по адресу REST(GET): http://narodmon.ru/api/userLocation?addr=..&uuid=UUID&api_key=API_KEY&lang=ru
Пример запроса по координатам JSON(POST):
{"cmd":"userLocation","lat":55.747899,"lon":37.6171,"uuid":"UUID","api_key":"API_KEY","lang":"ru"}
Пример запроса по адресу JSON(POST):
{"cmd":"userLocation","addr":"..","uuid":"UUID","api_key":"API_KEY","lang":"ru"}
Пример запроса по WiFi сетям JSON(POST):
{"cmd":"userLocation","wifi":[{"bssid":"00:00:00:00:00:00","rssi":-0},{..}],"uuid":"UUID","api_key":"API_KEY","lang":"ru"}
Пример запроса по сотовым сетям JSON(POST):
{"cmd":"userLocation","cells":[{"bssid":"000:000:0000:0000000","rssi":-0},{..}],"uuid":"UUID","api_key":"API_KEY","lang":"ru"}
Ответ сервера:
{"lat":55.747899,"lon":37.6171,"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://narodmon.ru/api/userFavorites?sensors=1,2&webcams=1,2&uuid=UUID&api_key=API_KEY&lang=ru
Пример запроса JSON(POST):
{"cmd":"userFavorites","uuid":"UUID","api_key":"API_KEY","sensors":[1,2],"webcams":[1,2],"lang":"ru"}
Ответ сервера:
{"sensors":[{"id":1,"did":1,"type":1,"name":"..","value":0.0,"time":1711086535},{..}],
"webcams":[{"id":1,"name":"..","time":1711086535,"image":"http://.."},{..}]}
userLogout - завершение сеанса текущего пользователя
Параметры запроса:
* нет параметров *
ОТВЕТ сервера:
- login имя авторизованного пользователя для текущего uuid;
- uid ID участника проекта.
Пример запроса REST(GET):
http://narodmon.ru/api/userLogout?uuid=UUID&api_key=API_KEY
Пример запроса JSON(POST):
{"cmd":"userLogout","uuid":"UUID","api_key":"API_KEY"}
Ответ сервера:
{"login":"","uid":0}
addLike - отметка "Мне нравится" на снимках с веб-камер и приборах.
Параметры запроса:
- id веб-камеры(<0) или прибора(>0). ОТВЕТ сервера: - id веб-камеры(<0) или прибора(>0); - time время отметки в UnixTime; - liked общее число отметок "Нравится" на объекте после выполнения.
Пример запроса REST(GET):
http://narodmon.ru/api/addLike?id=1&uuid=UUID&api_key=API_KEY
Пример запроса JSON(POST):
{"cmd":"addLike","id":1,"uuid":"UUID","api_key":"API_KEY"}
Ответ сервера:
{"id":1,"time":1711086535,"liked":1}
disLike - снятие отметки "Мне нравится" на снимках с веб-камер и приборах
Параметры запроса:
- id веб-камеры(<0) или прибора(>0). ОТВЕТ сервера: - id веб-камеры(<0) или прибора(>0); - time время снятия отметки в UnixTime; - liked общее число отметок "Нравится" на объекте после выполнения.
Пример запроса REST(GET):
http://narodmon.ru/api/disLike?id=1&uuid=UUID&api_key=API_KEY
Пример запроса JSON(POST):
{"cmd":"disLike","id":1,"uuid":"UUID","api_key":"API_KEY"}
Ответ сервера:
{"id":1,"time":1711086535,"liked":0}
setPushToken, setPushURI - установка параметров отправки PUSH уведомлений. Используется FireBase (Android, iOS) и WNS (Windows)
Параметры запроса:
- token токен для Android и iOS;
- uri URL для Windows Mobile и Windows Phone.
Пример запроса REST(GET):
FireBase: http://narodmon.ru/api/setPushToken?token=..&uuid=UUID&api_key=API_KEY
WNS: http://narodmon.ru/api/setPushURI?uri=..&uuid=UUID&api_key=API_KEY
Пример запроса JSON(POST):
FireBase: {"cmd":"setPushToken","token":"..","uuid":"UUID","api_key":"API_KEY"}
WNS: {"cmd":"setPushURI","uri":"https://..","uuid":"UUID","api_key":"API_KEY"}
Ответ сервера:
{"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":1711086535,"subj":"..","body":".."}
setPushStatus - отправка отчета о доставке/прочтении PUSH-уведомления
Параметры запроса:
- states массив со статусами полученных сообщений:
- states[id] идентификатор полученного сообщения (int unsigned);
- states[time] время отправки сообщения в UnixTime;
- states[status] код текущего статуса сообщения (201 - получено, 202 - прочтено).
Пример запроса REST(GET):
http://narodmon.ru/api/setPushStatus?id=1&time=1711086535&status=201&uuid=UUID&api_key=API_KEY
Пример запроса JSON(POST):
{"cmd":"setPushStatus","states":[{"id":1,"time":1711086535,"status":201},{..}],"uuid":"UUID","api_key":"API_KEY"}
Ответ сервера:
{"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":1711086535,"subj":"..","body":".."}
Во избежание ошибки 429 (слишком частые запросы), настоятельно рекомендуется аккумулировать статусы доставки PUSH-сообщений и отправлять их пакетами не чаще 1 раза в минуту!
sendCommand - отправка команды управления на прибор
Параметры запроса:
- id ID приборов в проекте (integer unsigned);
- command строка команды, шаблон PCRE [a-z0-9_\-\+\=\;\/\.]+
Пример запроса REST(GET):
http://narodmon.ru/api/sendCommand?id=1&command=reboot&uuid=UUID&api_key=API_KEY
Пример запроса JSON(POST):
{"cmd":"sendCommand","id":1,"command":"gpio12=1","uuid":"UUID","api_key":"API_KEY"}
Ответ сервера:
{"result":"OK"}
sendComplaint - отправка жалобы на ошибочное показание датчика или снимка с веб-камеры
Параметры запроса:
- id код датчика (id>0) или веб-камеры (id <0);
- time UnixTime времени возникновения проблемы;
- name имя заявителя для обратной связи;
- email почта заявителя для обратной связи;
- problem краткое описание сути проблемы;
- value каким должно быть показание датчика (для id>0).
Пример запроса REST(GET):
http://narodmon.ru/api/sendComplaint?id=1&time=1711086535&value=0&name=..&email=..&problem=..&uuid=UUID&api_key=API_KEY
Пример запроса JSON(POST):
{"cmd":"sendComplaint","id":1,"time":1711086535,"value":0,"name":"..","email":"..","problem":"..","uuid":"UUID","api_key":"API_KEY"}
Ответ сервера:
{"result":"OK"}
sendMessage - отправка сообщения в беседу или вопроса к Администрации
Параметры запроса:
- uid опционально ID получателя, по умолчанию Администрация;
- name опционально имя заявителя для обращения;
- email опционально почта заявителя для дублирования;
- chat опционально ID беседы из getDialog;
- subj обязательно тема обращения;
- mess обязательно текст сообщения;
- images[..] опционально массив вложенных изображений (до 1МБ) в виде base64 строк.
Пример запроса REST(GET):
http://narodmon.ru/api/sendMessage?uid=1&name=..&email=..&subj=..&mess=..&uuid=UUID&api_key=API_KEY
Пример запроса JSON(POST):
{"cmd":"sendMessage","uid":1,"name":"..","email":"..","subj":"..","mess":"..","uuid":"UUID","api_key":"API_KEY"}
Ответ сервера:
{"result":"OK"}
weatherReport - отправка метеоданных пользователем с автономных метеоприборов
Параметры запроса:
- lat, lon широта и долгота прибора на момент отправки (предварительно обновить геолокацию!);
- temp показания уличного термометра (если он есть) °C;
- humid показания уличного гигрометра (если он есть) %;
- pss показания бытового барометра (если он есть) мм рт.ст.;
- wind азимут направления ветра (если есть анемометр) 0-360°.
Пример запроса REST(GET):
http://narodmon.ru/api/weatherReport?lat=55.747899&lon=37.6171&temp=00&humid=00&pss=000&wind=000&lang=ru&uuid=UUID&api_key=API_KEY
Пример запроса JSON(POST):
{"cmd":"weatherReport","lat":55.747899,"lon":37.6171,"temp":00,"humid":00,"pss":000,"wind":000,"lang":"ru","uuid":"UUID","api_key":"API_KEY"}
Ответ сервера:
{"result":"Вы сообщили следующие данные:..."}
Если отчет о погоде будет отправлен менее чем через час после предыдущего, то он посчитается исправлением и заменит его.
bugReport - отправка отзыва на приложение и багрепортов с техданными для отладки
Параметры запроса:
- time опционально UnixTime момента возникновения сбоя;
- name опционально имя заявителя для обращения;
- email опционально почта заявителя для дублирования;
- mess опционально текст сообщения пользователя;
- logs опционально технические данные для отладки;
- images[..] опционально массив вложенных изображений (до 1МБ) в виде base64 строк.
Пример запроса REST(GET):
http://narodmon.ru/api/bugReport?time=1711086535&name=..&email=..&mess=..&logs=..&uuid=UUID&api_key=API_KEY
Пример запроса JSON(POST):
{"cmd":"bugReport","time":1711086535,"name":"..","email":"..","mess":"..","logs":"..","uuid":"UUID","api_key":"API_KEY"}
Ответ сервера:
{"result":"OK"}
Уведомление о багрепорте в краткой форме будет отправлено автору приложения используя PUSH, а на e-mail автора будет отправлена полная версия вместе с техданными для отладки.
getHelp - запрос справочной информации о проекте
Параметры запроса:
- topic опционально идентификатор статьи, если он не указан, то возвращается оглавление.
ОТВЕТ сервера:
- topics массив со список статей;
- topics[topic] идентификатор статьи;
- topics[group] название раздела Справки;
- topics[title] название статьи из Справки;
- topics[body] html-текст статьи (если был указан topic) или хеш статьи в оглавлении.
Пример запроса в оглавлении REST(GET):
http://narodmon.ru/api/getHelp?lang=ru&uuid=UUID&api_key=API_KEY
Пример запроса оглавления JSON(POST):
{"cmd":"getHelp","lang":"ru","uuid":"UUID","api_key":"API_KEY"}
Ответ сервера с оглавлением:
{"topics":[{"topic":"topic1","group":"Раздел1","title":"Заголовок1","body":"c8542aec71a1a1e371f39553ae3b7ec7"},{..}]}
Пример запроса текста статьи REST(GET):
http://narodmon.ru/api/getHelp?topic=topic1&lang=ru&uuid=UUID&api_key=API_KEY
Пример запроса текста статьи JSON(POST):
{"cmd":"getHelp","topic":"topic1","lang":"ru","uuid":"UUID","api_key":"API_KEY"}
Ответ сервера с текстом статьи:
{"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://narodmon.ru/api');
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 ' = '.rounОтвет сервера:d($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://narodmon.ru/api', 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://narodmon.ru/api', 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://narodmon.ru/api', 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)=}")