Русский · English
Готовые примеры работы с погодным API на шести языках: Python, TypeScript (Node.js), Go, Java, C#, PHP. Получить температуру по широте и долготе, скорость ветра, порывы, влажность, облачность, видимость и осадки — одним HTTP-запросом. Ответ в формате погода JSON API, пригоден как источник данных о погоде для приложения.
Каждый пример запускается сразу — без регистрации, без ключа, без карты. В коде зашит публичный демо-ключ.
git clone https://github.com/atlorium-api/weather-api-client
cd weather-api-client/python && pip install -r requirements.txt && python main.pyПогода по координатам 55.7558, 37.6173
Точка: Махачкала (RU), coord из ответа: 55.7558, 37.6173
Замер: 13.07.2026 18:02 (местное время, UTC+3)
Небо: небольшой дождь (Rain)
Температура: -14.0 °C, ощущается как -16.2 °C
Ветер: 3.3 м/с, порывы до 16.6 м/с, направление 62° (СВ)
Влажность: 80 %
Облачность: 77 %
Видимость: 5475 м
Давление: 995 гПа
ВЕРДИКТ: РАБОТАТЬ С ОСТОРОЖНОСТЬЮ
[~] Заморозки: -14.0 °C (main.temp <= 0)
[~] Порывы ветра до 16.6 м/с (wind.gust >= 15)
Это настоящий вывод примера на демо-ключе, не подогнанный. Да, он внутренне противоречив — см. раздел «Что не так с данными в песочнице». Так и задумано: интеграцию можно написать и протестировать до оплаты, а с боевым ключом тот же код вернёт реальные данные.
Погода нужна не сама по себе, а чтобы что-то решить: выпускать ли машину на маршрут, поднимать ли людей на высоту, начинать ли наружные работы, не сорвётся ли монтаж, надо ли подсыпать реагент. Плюс обычные продуктовые задачи — виджет погоды, подсказка «возьмите зонт», геймификация, аналитика продаж от погоды.
Поэтому примеры не просто печатают JSON, а применяют его: в каждом есть функция assessConditions(), которая по ответу выносит вердикт из трёх состояний — МОЖНО РАБОТАТЬ / РАБОТАТЬ С ОСТОРОЖНОСТЬЮ / РАБОТЫ ОТМЕНИТЬ — и перечисляет причины, каждую со ссылкой на поле, из которого она выведена.
Что она проверяет:
| Проверка | Условие по полям ответа | Вес |
|---|---|---|
| Гололёд | main.temp в диапазоне −5…+3 °C И осадки (weather[].main = Rain/Drizzle либо rain ≠ null) |
стоп-фактор |
| Сильный ветер | wind.speed >= 10 м/с |
стоп-фактор |
| Плохая видимость | visibility < 1000 м — туман |
стоп-фактор |
| Заморозки | main.temp <= 0 °C |
предупреждение |
| Порывы ветра | wind.gust >= 15 м/с |
предупреждение |
| Экстремальный холод | main.feels_like <= -20 °C |
предупреждение |
Самое ценное здесь — гололёд, и его не видно ни из одного поля по отдельности. Ни «−1 °C», ни «идёт дождь» сами по себе ничего не означают. А вот их комбинация — вода на покрытии при температуре около нуля — это ровно та ситуация, которая губит логистику: машины в кюветах, сорванные сроки, битый груз. Одно if по двум полям ответа, и вы знаете об этом за час до выезда.
Пороги вынесены в константы: у логистики, кровельщиков и монтажников высотных конструкций они разные. Правьте под свою задачу.
Проверить API вообще без клонирования:
curl -H "Authorization: Bearer ak_sandbox_demo_mockdata_v1" \
"https://atlorium.com/api/Weather?latitude=55.7558&longitude=37.6173"| Язык | Запуск | Требуется |
|---|---|---|
| Python | pip install -r requirements.txt && python main.py |
Python 3.10+ |
| TypeScript / Node.js | npm install && npm start |
Node.js 20+ |
| Go | go run . |
Go 1.22+ |
| Java | java Main.java |
JDK 11+ (без зависимостей) |
| C# | dotnet run |
.NET 8+ |
| PHP | php main.php |
PHP 8.1+ |
Передать свои координаты двумя аргументами (по умолчанию — Москва):
python main.py 59.9343 30.3351 # Санкт-Петербург
go run . 51.5074 -0.1278 # Лондон
npm start -- -33.8688 151.2093 # СиднейКлюч передаётся в заголовке Authorization:
Authorization: Bearer ВАШ_КЛЮЧ
| Ключ | Что делает |
|---|---|
ak_sandbox_demo_mockdata_v1 |
Демо-ключ. Публичный, один на всех. Возвращает моки, денег не списывает, регистрации не требует. Ответы привязаны к округлённым координатам: одна и та же точка всегда даёт одну и ту же «погоду» — на этом можно писать стабильные тесты. |
| Боевой ключ | Реальные метеоданные. Получить в личном кабинете: atlorium.com |
Переход на боевой ключ не требует правок в коде — все примеры читают переменную окружения:
export ATLORIUM_API_KEY="ak_ваш_боевой_ключ"Каждый ответ песочницы помечен заголовком X-Atlorium-Sandbox: true — перепутать мок с реальными данными невозможно.
Честно, потому что вы это всё равно увидите в первую же минуту.
Демо-ключ отдаёт сгенерированные значения. Они правдоподобны по отдельности и стабильны для одной точки, но не согласованы между собой и с координатами. В выводе выше это видно дважды:
nameне связан с координатами. На координаты Москвы (55.7558, 37.6173) в полеnameпришло «Махачкала». При этомcoordчестно отражает то, что вы прислали, — эхом.- Погода физически абсурдна. «Небольшой дождь» (
Rain) приtemp = −13.99 °Cв природе не встречается.
Практический вывод: проверять на песочнице логику своего приложения можно и нужно — поля, типы, null-ы, ветки кода, вердикты. Делать по ней выводы о погоде — нельзя. С боевым ключом приходят реальные измерения метеостанций, и противоречия исчезают.
Ещё одна деталь для тех, кто пишет тесты: стабильны в песочнице не все поля. Погода привязана к округлённым координатам и повторяется, а вот dt, sys.sunrise и sys.sunset считаются от текущего момента и меняются от запроса к запросу. Snapshot-тест по всему телу ответа из-за них будет «мигать» — сравнивайте поля выборочно.
Отдельно: поля rain и snow в песочнице всегда null. В боевом режиме они приходят объектом {"1h": 0.5}, когда осадки есть. Код в примерах это учитывает — обращение к rain["1h"] без проверки на null даёт TypeError / NullReferenceException / панику, и именно поэтому проверка вынесена в отдельную функцию hasPrecipitation().
Базовый адрес: https://atlorium.com
| Метод | Путь | Назначение |
|---|---|---|
GET |
/api/Weather |
Текущая погода в точке по географическим координатам |
Это единственный эндпоинт сервиса. Прогноза на несколько дней вперёд он не отдаёт — только текущее состояние на момент запроса.
| Параметр | Где | Тип | Описание |
|---|---|---|---|
latitude |
query | number | Широта в градусах, от −90.0 до +90.0. Положительные — Северное полушарие (55.7558 — Москва), отрицательные — Южное (−33.8688 — Сидней) |
longitude |
query | number | Долгота в градусах, от −180.0 до +180.0. Положительные — Восточное полушарие (37.6173 — Москва), отрицательные — Западное (−74.0060 — Нью-Йорк) |
Регистр в пути значения не имеет: /api/weather и /api/Weather — одно и то же.
Имена полей — в snake_case, единицы измерения метрические.
| Поле | Тип | Что содержит |
|---|---|---|
coord |
object | { lat, lon } — координаты. Эхо запроса, а не «найденная ближайшая станция» |
weather |
array | Состояния неба. Обычно один элемент: { id, main, description, icon } |
weather[].main |
string | Машинный код: Clear, Clouds, Rain, Drizzle, Snow, Fog. По нему и надо ветвить логику, а не по description |
weather[].description |
string | Человекочитаемое описание на языке ответа: «небольшой дождь» |
weather[].icon |
string | Код иконки погодного состояния: 10d, 01n |
base |
string | Источник данных, обычно stations |
main.temp |
number | Температура в градусах Цельсия (не в кельвинах) |
main.feels_like |
number | Ощущаемая температура, °C — с учётом ветра и влажности |
main.temp_min / main.temp_max |
number | Минимум и максимум по территории населённого пункта, °C |
main.pressure |
number | Атмосферное давление, гПа (гектопаскали) |
main.humidity |
number | Влажность, % |
main.sea_level / main.grnd_level |
number|null | Давление на уровне моря и на уровне земли, гПа |
visibility |
number|null | Видимость в метрах, максимум 10000 |
wind.speed |
number | Скорость ветра в м/с (не в км/ч) |
wind.deg |
number | Направление ветра, градусы (0 — север, 90 — восток) |
wind.gust |
number|null | Порывы ветра, м/с. Может отсутствовать — при штиле порывов нет |
clouds.all |
number | Облачность, % |
rain / snow |
object|null | Осадки, мм: { "1h": …, "3h": … }. null, если осадков нет |
dt |
number | Время замера — Unix timestamp в UTC |
timezone |
number | Смещение точки от UTC в СЕКУНДАХ: 10800 = UTC+3 |
sys.country |
string | Код страны, ISO 3166 |
sys.sunrise / sys.sunset |
number | Восход и закат, Unix timestamp в UTC |
id |
number | Внутренний идентификатор населённого пункта |
name |
string | Название населённого пункта |
cod |
number | Код ответа внутри тела, 200 при успехе |
Три места, где чаще всего спотыкаются:
dt— это UTC, аtimezone— смещение в СЕКУНДАХ, а не в часах. Готового локального времени сервер не присылает:dt + timezoneнадо сложить руками. Во всех шести примерах это делает функцияlocalTime().wind.gust,visibility,rain,snow— nullable. Обращение к ним без проверки роняет приложение.- Температура — в °C, ветер — в м/с. Для км/ч умножьте на 3.6.
| Код | Причина | Что делать |
|---|---|---|
400 |
Координаты вне диапазона | Широта −90…90, долгота −180…180 |
401 |
Ключ отсутствует, просрочен или недействителен | Проверьте заголовок Authorization |
402 |
Недостаточно кредитов на балансе | Пополнить на atlorium.com |
429 |
Превышен rate-limit | Повторить с задержкой — см. ниже |
500 |
Непредвиденная внутренняя ошибка сервера | Повторить позже |
503 |
Внешний источник погодных данных недоступен. Именно этим кодом отвечает сервис на сбой получения погоды — не 500 |
Повторить позже. За сбой на нашей стороне деньги не списываются |
Во всех шести примерах коды разложены в человекочитаемые причины — смотрите класс AtloriumError.
Про 429 и Retry-After. Сервер честно сообщает, сколько ждать. Но если исчерпан часовой лимит, он может попросить подождать десятки минут — и клиент, слепо доверяющий заголовку, зависнет на всё это время (а в CI просто съест бюджет джоба). Поэтому в примерах есть потолок ожидания MAX_RETRY_DELAY = 120 секунд: дольше не ждём, честно сообщаем «квота исчерпана» и выходим. Копируйте этот подход к себе.
Оплата pay-as-you-go, без подписки: платите только за выполненные запросы.
Лимиты у погоды умеренные, но не безграничные: их хватает, чтобы отладить интеграцию и держать виджет, но не чтобы превратить сервис в личный погодный прокси. Демо-ключ лимитируется по IP ровно теми же цифрами, что получит платящий клиент, — песочница честно показывает будущие условия. Актуальные лимиты и цены — на atlorium.com/pricing. Не запускайте примеры в цикле.
Актуальные цены и лимиты: atlorium.com/pricing
Откуда данные? Реальные измерения метеостанций на момент запроса, без потерь и переупаковки.
Можно ли получить прогноз на неделю? Нет. Эндпоинт один и возвращает текущую погоду в точке. Если вам нужен именно многодневный прогноз — этот сервис не подойдёт, и лучше узнать об этом сейчас, чем после интеграции.
В каких единицах температура? В градусах Цельсия — конвертация уже сделана на нашей стороне. temp можно печатать как есть.
Как перевести dt в местное время точки? Сложить dt (Unix, UTC) со смещением timezone (в секундах). Смещение — именно точки, а не вашего сервера. Готовая функция localTime() есть во всех шести примерах.
Что делать, если wind.gust отсутствует? Считать, что порывов нет. Поле не приходит при слабом ветре — это не ошибка. То же с rain и snow.
Можно ли искать погоду по названию города? Нет, только по координатам. Название города вы получаете в ответе (name), а не подаёте на вход. Чтобы превратить адрес в координаты, возьмите Стандартизацию адреса или Адреса ГАР/ФИАС, а IP-адрес в координаты — Профиль IP.
Обязательна ли регистрация, чтобы попробовать? Нет. Демо-ключ публичный и работает без аккаунта — но возвращает моки, а не реальные данные.
Погода редко бывает единственной задачей. Из того же аккаунта и тем же ключом доступны:
- Адреса ГАР/ФИАС — поиск и подсказки по официальному справочнику
- Разбор cron-выражений — валидация расписания и ближайшие запуски с учётом таймзоны
- Стандартизация адреса — разбор строки на компоненты и оценка качества
- Проверка SSL-сертификата — срок действия, SAN, цепочка доверия
- Валидация телефона — формат, тип номера, оператор диапазона
- DNS Lookup — записи домена, MX, SPF, DMARC
Полный каталог — atlorium.com
- Документация API (Swagger): atlorium.com/weatherAPI
- Описание сервиса: atlorium.com/weatherDescription
- Веб-интерфейс: atlorium.com/weatherGUI
- OpenAPI-спецификация: weather_ru.json
- Поддержка: support@atlorium.com
MIT — берите код и используйте как хотите, в том числе в коммерческих проектах.