Для налагодження ваших запитів до 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 4;
- 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=uk&utc=3
Приклад запиту JSON(POST):
{"cmd":"appInit","version":"1.1","platform":"6.0.1","uuid":"UUID","lang":"uk","utc":3}
Відповідь сервера:
{"latest":"1.2","url":"http://mysite.ua/myapp.exe","login":"...","vip":0,"lat":39.962502,"lon":-83.006104,"addr":"...",
"types":[{"type":0,"name":"...","unit":""},{..}],"favorites":[1,2,..],"timestamp":1732245414}
mapBounds - запит списку датчиків і веб-камер в зазначеній прямокутної області карти
* Кількість приладів у вибірці (без узгодження) обмежена до 10. Ваш ліміт в Профілі \ Мої програми.
Параметри запиту:
- 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=uk&limit=10
Приклад запиту JSON(POST):
{"cmd":"mapBounds","limit":10,"bounds":[10,20,11,21],"uuid":"UUID","lang":"uk"}
Відповідь сервера:
{"devices":[{"id":0,"name":"..","lat":39.962502,"lon":-83.006104,"time":1732245414,"value":0.0,"type":0,"unit":""},{..}],
"webcams":[{"id":0,"name":"..","lat":39.962502,"lon":-83.006104,"time":1732245414,"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=uk
Приклад запиту SON(POST):
{"cmd":"sensorsNearby","lat":39.962502,"lon":-83.006104,"radius":10,"types":[1,2],
"uuid":"UUID","lang":"uk"}
Відповідь сервера:
{"devices":[{"id":0,"name":"..","my":0,"owner":"0","mac":"..","cmd":0,"lat":0.0,"lon":0.0,"location":"..",
"distance":0.0,"time":1732245414,"sensors":[{"id":0,"mac":"..","fav":0,"pub":0,"type":0,"name":"..","value":0.0,"unit":"","time":1732245414,
"changed":1732245414,"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=uk
Приклад запиту JSON(POST):
{"cmd":"sensorsOnDevice","devices":[1,2],"uuid":"UUID","lang":"uk"}
Відповідь сервера:
{"devices":[{"id":1,"name":"..","my":0,"owner":"0","mac":"","cmd":0,"lat":0.0,"lon":0.0,"location":"..","distance":0.0,"time":1732245414,
"site":"https://narodmon.ru/1","photo":"","info":"220B",
"sensors":[{"id":1,"mac":"","fav":0,"pub":1,"type":1,"name":"..","value":0.0,"unit":"",
"time":1732245414,"changed":1732245414,"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":1732245414,"changed":1732245414,"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":1732245414,"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] назва веб-камери або http-посилання (як назвав власник);
- 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=uk
Приклад запиту JSON(POST):
{"cmd":"webcamsNearby","radius":10,"lat":39.962502,"lon":-83.006104,"uuid":"UUID","lang":"uk"}
Відповідь сервера:
{"webcams":[{"id":1,"name":"..","my":0,"owner":"1","fav":0,"distance":0.0,"lat":39.962502,"lon":-83.006104,"location":"..",
"time":1732245414,"image":"http://.."},{..}]}
webcamImages - запит списку знімків з веб-камери за її ID
Параметри запиту:
- id ID веб-камери з посилання на кшталт http://narodmon.ru/-ID у балуні на карті;
- since опціонально час першого знімка у вибірці в UnixTime, за замовчуванням дорівнює 0;
- limit опціонально кількість знімків у відповіді сервера, за замовчуванням 20, максимум 50;
- latest опціонально час останнього знімка у вибірці в UnixTime, за замовчуванням дорівнює поточним;
- width опціонально ширина екрану клієнтського пристрою в пікселях для оптимізації розміру завантажуваних знімків.
ВІДПОВІДЬ сервера:
- id цілочисельний код веб-камери в проекті;
- name назва веб-камери (як назвав власник);
- location населений пункт місцезнаходження веб-камери;
- distance відстань у км від поточного місця знаходження користувача;
- images масив знімків з веб-камери знаходяться на сервері;
- images[time] час актуальності знімка в UnixTime;
- images[image] URL для скачування знімка.
Приклад запиту REST(GET):
http://api.narodmon.ru/webcamImages?id=1&uuid=UUID
Приклад запиту JSON(POST):
{"cmd":"webcamImages","id":1,"limit":10,"uuid":"UUID"}
Відповідь сервера:
{"id":1,"name":"..","location":"..","distance":0.0,
"images":[{"time":1732245414,"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=uk
Приклад запиту JSON(POST):
{"cmd":"userLogon","login":"MyName","hash":"MD5HASH","uuid":"UUID","lang":"uk"}
Відповідь сервера:
{"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=uk
Приклад запиту за адресою REST(GET):
http://api.narodmon.ru/userLocation?addr=..&uuid=UUID&lang=uk
Приклад запиту за координатами JSON(POST):
{"cmd":"userLocation","lat":39.962502,"lon":-83.006104,"uuid":"UUID","lang":"uk"}
Приклад запиту за адресою JSON(POST):
{"cmd":"userLocation","addr":"..","uuid":"UUID","lang":"uk"}
Приклад запиту по WiFi мережам JSON(POST):
{"cmd":"userLocation",
"wifi":[{"bssid":"00:00:00:00:00:00","rssi":-0},{..}],"uuid":"UUID","lang":"uk"}
Приклад запиту по стільникових мережах JSON(POST):
{"cmd":"userLocation",
"cells":[{"bssid":"000:000:0000:0000000","rssi":-0},{..}],"uuid":"UUID","lang":"uk"}
Відповідь сервера:
{"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=uk
Приклад запиту JSON(POST):
{"cmd":"userFavorites","uuid":"UUID",
"sensors":[1,2],"webcams":[1,2],"lang":"uk"}
Відповідь сервера:
{"sensors":[{"id":1,"did":1,"type":1,"name":"..","value":0.0,"time":1732245414},{..}],
"webcams":[{"id":1,"name":"..","time":1732245414,"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":1732245414,"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":1732245414,"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=TOKEN&uuid=UUID
WNS: http://api.narodmon.ru/setPushURI?uri=URL&uuid=UUID
Приклад запиту JSON(POST):
FireBase: {"cmd":"setPushToken","token":"TOKEN","uuid":"UUID"}
WNS: {"cmd":"setPushURI","uri":"URL","uuid":"UUID"}
Відповідь сервера:
{"result":"OK"}
PUSH повідомлення від FireBase приходять в колекції java.util.Map з полями:
- id ідентифікатор повідомлення (int unsigned);
- uid ідентифікатор користувача (signed int);
- time час відправки повідомлення UnixTime (int unsigned);
- subj заголовок повідомлення;
- body повний текст повідомлення.
PUSH повідомлення від WNS приходять у вигляді структури JSON:
{"id":ID,"uid":UserID,"time":1732245414,"subj":"..","body":".."}
setPushStatus - відправка звіту про доставку/прочитання PUSH-сповіщення
Параметри запиту:
- states масив зі статусами отриманих повідомлень:
- states[id] ідентифікатор отриманого повідомлення (unsigned int);
- states[time] час відправки повідомлення у UnixTime;
- states[status] код поточного статусу повідомлення (201 - отримано, 202 - прочитано).
Приклад запиту REST(GET):
http://api.narodmon.ru/setPushStatus?id=1&time=1732245414&status=201&uuid=UUID
Приклад запиту JSON(POST):
{"cmd":"setPushStatus","states":[{"id":1,"time":1732245414,"status":201},{..}],"uuid":"UUID"}
Відповідь сервера:
{"result":"OK"}
PUSH повідомлення від FireBase приходять в колекції java.util.Map з полями:
- id ідентифікатор повідомлення (int unsigned);
- uid ідентифікатор користувача (signed int);
- time час відправки повідомлення UnixTime (int unsigned);
- subj заголовок повідомлення;
- body повний текст повідомлення.
PUSH повідомлення від WNS приходять у вигляді структури JSON:
{"id":ID,"uid":UserID,"time":1732245414,"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=1732245414&value=0
&name=MyName&email=my@email&problem=test_problem&uuid=UUID
Приклад запиту JSON(POST):
{"cmd":"sendComplaint","id":1,"time":1732245414,"value":0,
"name":"MyName","email":"my@email","problem":"test_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=1732245414&name=..&email=..&mess=..&logs=..&uuid=UUID
Приклад запиту JSON(POST):
{"cmd":"bugReport","time":1732245414,"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://narodmon.ru/api/getHelp?lang=uk&uuid=UUID
Приклад запиту змісту JSON(POST):
{"cmd":"getHelp","lang":"uk","uuid":"UUID"}
Відповідь сервера з змістом:
{"topics":[{"topic":"topic1","group":"Розділ1","title":"Заголовок1","body":"c8542aec71a1a1e371f39553ae3b7ec7"},{..}]}
Приклад запиту тексту статті REST(GET):
http://api.narodmon.ru/getHelp?topic=topic1&lang=uk&uuid=UUID
Приклад запиту тексту статті JSON(POST):
{"cmd":"getHelp","topic":"topic1","lang":"uk","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'=>50.45, 'lon'=>30.52, 'radius'=>11, 'uuid'=>md5('mysite.ua'), 'api_key'=>'MY_API_KEY', 'lang'=>'uk');
// виконання запиту
$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.ua');
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'=>50.45, 'lon'=>30.52, 'radius'=>11, 'uuid'=>md5('mysite.ua'), 'api_key'=>'MY_API_KEY', 'lang'=>'uk');
// виконання запиту
$header = "User-Agent: mysite.ua\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.com', 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)=}")