API Погоды в деталях

API Погоды основан на HTTP-запросах, отправляемых на серверы Foreca. Локации идентифицируются по координатам (широта/долгота). Ответы на запросы приходят в виде исходных данных в независимых от языка форматах JSON, XML или разделенного ASCII.

Клиент должен ретранслировать запросы конечных потребителей/устройств через центральный прокси-сервер(ы). Foreca открывает доступ к интерфейсу запроса только указанным IP-адресам прокси-сервера. Также сервис предполагает случайное распределение запросов, то есть использование API Погоды для пакетного режима запросов не должно уходить в замкнутый цикл. Любое обращение к пакетному режиму должно включать секундную задержку между запросами (1 QPS). Более 10 QPS с одной пакетной учетной записи могут быть заблокированы без предупреждения.

 

Предоставляемые метеорологические данные

Текущие условия: данные от ближайшей метеостанции, недавно отправившей данные

  • Если в пределах 100 км от данных координат нет метеостанции, текущие условия не будут сообщены
  • Foreca предоставляет бесплатные изображения в формате gif/png для визуализации погодных условий
  • Параметры текущего состояния, сообщаемые станцией:
    • название метеостанции, например, “Лондон Хитроу”
    • расстояние — расстояние от выбранной локации до метеостанции, например, “8 км СВ”
    • Время наблюдения — местное время, в которое было совершено наблюдение
    • температура по Цельсию или Фаренгейту
    • температура по ощущениям по Цельсию или Фаренгейту
    • код графического символа, например, “d420”
    • скорость ветра, м/с, узлы, км/ч или мили/ч
    • направление ветра (С, СВ, В...)
    • давление, гПа, например, “1012”
    • относительная влажность, в %, например, “87”
    • видимость, в метрах, например, “10000” (10 км)

Краткий детальный прогноз: Краткий детальный прогноз:

  • Доступен с интервалами в час, 3 часа или 6 часов
  • Foreca бесплатно предоставляет изображения формата gif/png для визуализации погодных условий
  • Рекомендованный срок прогнозирования — до двух дней

Ежедневная сводка прогнозов: содержит сводные данные одного дня

  • Рекомендованный срок прогнозирования — до семи дней
  • Foreca бесплатно предоставляет изображения формата gif/png для визуализации погодных условий
  • Метеорологические параметры ограничены:
    • код графических символов
    • мин/макс температура по Цельсию или Фаренгейту

 

Опции

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

 

Как отобразить атрибуты?

Все продукты с использованием API Погоды, API Карт Погоды и других пакетов исходных данных должны обладать атрибутикой Foreca возле погодной информации в виде одной из следующих фраз или в соответствующем переводе: “При поддержке Foreca”, “Метеорологические данные предоставлены Foreca”, “Источник метеорологических данных: Foreca”. Если это возможно, текст “Foreca” должен быть расположен на одном из графических изображений, доступных здесь. See document Логотип Foreca и требования к атрибутике для детальных инструкций.

  

Примеры запросов

ПРИМЕЧАНИЕ: анализатор ответов должен быть способен справляться с новыми метеорологическими параметрами, которые могут появиться в будущем, например, новые ключи к JSON, теги XML или новые колонки в разделенном ASCII.

Ежедневные обзорные запросы

Прогноз на два дня вперед

http://HOST/data?lon=24.97&lat=60.22&ftimes=48/24h&format=json/standardfeed&tempunit=C&windunit=MS&tz=

 

Краткие запросы прогнозов

Прогноз на два часа вперед

http://HOST/data?lon=24.97&lat=60.32&ftimes=2/1h&format=json/standardfeed&tempunit=C&windunit=MS&tz=
 

 

Поиск прогноза погоды по названию локации

Найдите локацию через базу данных Foreca, например, через поисковый запрос “lond”

http://HOST/search?q=lond


Выберите локацию из списка результатов и используйте еt ID, чтобы запросить метеорологические данные для данной локации:

http://HOST/data?l=102643743&ftimes=48/24h&format=json/standardfeed&tempunit=C&windunit=MS&tz=


Интерпретация ответа

Будьте готовы обрабатывать недостающую информацию о текущих условиях (наблюдениях), поскольку отсутствие аппаратуры или сбои приборов могут влиять на данные. Любые значения параметров могут оказаться пустыми, в том числе и входной obs-ключ (в JSON), тег (в XML) или строки OBSH/OBS (в тексте). Для примера попробуйте lon=0&lat=0. В случае отсутствия данных рекомендуется адаптировать содержание так, чтобы создать пустое пространство. Надписи вроде “Нет данных” часто воспринимаются конечными потребителями как неисправность сервиса.

Параметры/строки прогнозов всегда будут на месте, и обработка отсутствующих значений не должна быть сложнее, чем при текущих условиях. Прогнозы могут быть пропущены лишь при реальных технических неполадках.

Необходимые параметры запроса:

  • lon — долгота местоположения, градусы
  • lon — долгота местоположения, градусы

или

  • id — ID локации Foreca
  • format — формат ответа. Каждому клиенту предоставляют выделенное имя формата, “json/standardfeed” и “xml/standardfeed” используются в качестве примеров выше. Могут быть созданы пользовательские форматы.

Опциональные параметры запросов:

  • alt — высота над уровнем моря, в метрах. например, “2148” для 2148 метров. По умолчанию высота оценивается по величине модели численного прогноза погоды (NWP) для данных координат, что может вызвать ошибки в горных регионах. Предоставление фактической высоты позволит API Погоды лучше прогнозировать температуру в местах с большим изменением высоты. На уровне земли преимущество будет незначительным.
  • tempunit — “C” или “F”, Цельсий (по умолчанию) или Фаренгейт
  • windunit — "MS", "KTS", "KMH", или "MPH", м/с (по умолчанию), узлы, км/ч и миля/ч
  • tz — форматированный часовой пояс POSIX для штампов времени отклика, например, “UTC” или “Европа/Хельсинки”. Если он не указан, часовой пояс приближается к координатам, что может привести к ошибкам возле границ часовых поясов
  • ftimes — (только пакеты Стандарт/Премиум) длина интервала запрошенного прогноза погоды в часах, интервал в 24 часа включает режим ежедневного обзора. Например, “72/24 ч” переключает ежедневный обзор в течение следующих трех дней, “48/3 ч” переключает трехчасовой прогноз погоды на следующие два дня, а “12/1 ч” переключает на ежечасный прогноз в течение 12 часов. Время первого прогноза может быть задано в данном параметре, подробности см. ниже (*).

(*) использование параметра запроса ftimes для указания временного интервала

Существует два формата:

  1. ftimes=length/timestep
  2. ftimes=length/timestep/firststep

Формат 1 использует стандартные значения для принятия решения о времени первого прогноза. В формате 2 firststep изменяет время первого прогноза. Для ежедневной сводки прогнозов (типа x/24 ч) это интерпретируется как количество часов до полуночи, по умолчанию — 11. Для почасовых прогнозов это интерпретируется как минимальное количество часов с этого момента до первого прогноза timestep, по умолчанию — 0. Примеры:

  • ftimes=72/24h — стандартный, 1 pm, то есть смена даты на 13.00
  • ftimes=72/24h/11— то же, что и по умолчанию, смена даты на 13.00, 11 часов до полуночи
  • ftimes=72/24h/3 — смена даты на 21.00 (3 часа до полуночи)
  • ftimes=72/24h/0 — смена даты на полночь
  • ftimes=72/24h/-6 — показать вчерашний прогноз до 6 am
  • ftimes=12/1h — стандартный, почасовой прогноз на 12 часов
  • ftimes=12/1h/0 — то же, что и по умолчанию, почасовые прогнозы, начало — прямо сейчас
  • ftimes=12/1h/6 — почасовой прогноз на 12 часов, начало через шесть часов, то есть окончание через 18 часов

Пожалуйста, обратите внимание на то, что расчет часового пояса по местному времени является приблизительным.

Параметры ответа:

  • dt — временной штамп наблюдения/прогноза, для ежедневного обзора содержит только часть даты. Прогнозы API Погоды используют приблизительный часовой пояс, если он не указан в параметрах запроса, что может привести к неточностях вблизи границ часовых поясов. Использование Foreca ID часовой пояс становится точным. Для наблюдений (тег obs) время всегда совпадает с местным временем метеостанции.
  • station — название метеостанции, например, “Берлин Тегельхоф”
  • dist — расстояние до станции наблюдений от заданных координат, прилагаемых к направлению ветра на английском языке, например, “8 км СВ”
  • p — давление, в гПа, например, “1012”
  • v — видимость, в метрах, например, “10000” или 10 км
  • t — температура воздуха (стандартная единица: Цельсий)
  • tx — макс температура за 24 часа (стандартная единица: Цельсий) (ежедневные сводные данные)
  • tn — мин температура за 24 часа (стандартная единица: Цельсий) (ежедневные сводные данные)
  • tf — температура по ощущениям (стандартная единица: Цельсий), которая представляет собой объединенный индекс NOAA / NWS «только для ветра» и индекс тепла Rothfusz, которые учитывают влияние ветра и влажности на охлаждение и нагрев.
  • rh — относительная влажность, % от 0 до 100
  • pp — вероятность осадков, % от 0 до 100
  • tp — вероятность грозы, % от 0 до 100
  • pr — количество осадков (стандартная единица: миллиметр)
  • ws — средняя скорость ветра за 10 минут (стандартная единица: м/с)
  • wsx — дневной максимум средней скорости ветра за 10 минут (стандартная единица: м/с)
  • wsa — среднесуточная средняя скорость ветра за 10 минут (стандартная единица: м/с)
  • wn — строка направления ветра: С, СВ, В, ЮВ, Ю, ЮЗ, З, СЗ (Foreca предоставляет соответствующий набор символов)
  • s - код символа (see explanations in https://corporate.foreca.com/en/resources/foreca-symbols)
  • c - облачность, % от 0 до 100
  • ca - средняя облачность в течение дня, % от 0 до 100
  • sT - код символа в виде текста, используйте этот параметр для управления языком вывода
  • rise - восход солнца по местному времени в 24-часовой системе
  • set - заход солнца по местному времени в 24-часовой системе
  • uv - УФ индекс, основывающийся на модели прогнозирования уровня озонового слоя (1-2=низкий, 3-5=средний, 6-7=высокий, 8-10=очень высокий, 11+=опасный) ОБРАТИТЕ ВНИМАНИЕ: максимальный доступный прогноз — на 5 дней
  • dl - продолжительность дня, минуты

 

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

 

 

Свяжитесь с нами