Не так давно приказал долго жить и без того недокументированный API Google Weather, о котором я когда-то писал. Но жизнь на этом не останавливается, и многим из нас все так же необходимо отдавать пользователям своих сайтов прогнозы погоды.

В сегодняшней заметке речь пойдет об альтернативе Google Weather API — WorldWeatherOnline.

Итак, хоть сервис WWO и бесплатен, но он требует API-ключа. Поэтому сразу же регистрируемся. На почту прийдет confirm вместе с ключом. Теперь можно начать работу.

Сервис умеет возвращать данные в форматах XML, CSV и JSON. Приведу пример для формата XML. Для JSON и CSV необходимо всего лишь поменять один GET параметр в запросе.

Нас интересует погода в конкретном городе. Система умеет возвращать прогнозы по имени города, по имени города и страны, по широте и долготе конкретного города, по почтовому коду и по ZIP-коду. Лично мне ближе и проще видится вариант с широтой и долготой, в силу своей универсальности. Можно, конечно, запросить сразу город и страну, однако это скучно и не показывает всех плюшек системы. Так что мы пойдем длинным путем — пусть мы не знаем широту и долготу города. WWO умеет возвращать и эти данные! Для этого необходимо будет сделать дополнительный запрос.

Но перейдем от теории к практике. Поставим задачу — получить прогноз погоды в Москве (Россия) на 15 сентября 2012 года.

Начинаем строить запрос. Обращение идет к адресу http://www.worldweatheronline.com/feed/search.ashx. Далее будем передавать необходимые и известные нам параметры. Во-первых, это ключ API: ?key=XXXXXXXXXXXXXXXXXXXXX. Затем передадим запрос на город: &query=Moscow. Не секрет, что Москва в мире не одна с таким именем, поэтому ограничим результат XML-выдачи: &num_of_results=3. После этого урежем его параметром popular: &popular=yes. Но нам все равно возвращается «примесь» в виде Москвы американской. Однако, для каждого города в присылаемом XML есть параметр country, по которому худо-бедно можно фильтровать информацию. И в конце нам нужно указать формат принимаемой информации &format=xml. Вот тут при желании можно указать json или csv, если кому-то до чёртиков не нравится XML =)

Запрос будет вот таким:

http://www.worldweatheronline.com/feed/search.ashx?key=XXXXXXXXXXXXXXXXXXXXXXX&query=Moscow&num_of_results=3&format=xml&popular=yes

А вот, что он нам вернет:

<search_api>
    <result>
        <areaName>Moscow</areaName>
        <country>Russia</country>
        <region>Moscow City</region>
        <latitude>55.752</latitude>
        <longitude>37.616</longitude>
        <population>10381288</population>
        <weatherUrl>http://www.worldweatheronline.com/Moscow-weather/Moscow-City/RU.aspx</weatherUrl>
    </result>
    <result>
        <areaName>Moscow</areaName>
        <country>United States Of America</country>
        <region>Idaho</region>
        <latitude>46.733</latitude>
        <longitude>-116.999</longitude>
        <population>21865</population>
        <weatherUrl>http://www.worldweatheronline.com/Moscow-weather/Idaho/US.aspx</weatherUrl>
    </result>
</search_api>

Итак, в ответе нам должны вернуться два заветных параметра: latitude и longitude. Теперь у нас есть уникальный город, по которому точно можно получить прогноз. Это значит, что мы можем смело посылать второй запрос — уже непосредственно на погоду в городе. Адрес будет другой: http://free.worldweatheronline.com/feed/weather.ashx? , т.к. меня задушила жаба и я решил пользоваться бесплатным сервисом отдачи информации. Благо, он вполне удовлетворяет моим потребностям! Отличие платной версии в большем ассортименте возвращаемых форматов и расширенном поиске городов. Но это лирическое отступление. Продолжаем решать задачу.

Точно также передаем API-ключ в GET-параметре key, добавляем широту и долготу в странном ненативном параметре q=55.752,37.616 (это значения для Москвы), параметр cc (yes или no) возвращает или не возвращает текущие погодные условия помимо прогноза, date указывает конкретную дату, а уже знакомый нам параметр format — формат ответа (спасибо, Кэп!). В итоге наш запрос будет выглядеть следующим образом:

http://free.worldweatheronline.com/feed/weather.ashx?key=XXXXXXXXXXXXXXXXXXXX&q=Moscow&cc=no&date=2012-09-13&format=xml

Результат будет выглядеть примерно вот так:

<data>
    <request>
        <type>City</type>
        <query>Moscow, Russia</query>
    </request>
    <weather>
        <date>2012-09-13</date>
        <tempMaxC>23</tempMaxC>
        <tempMaxF>73</tempMaxF>
        <tempMinC>10</tempMinC>
        <tempMinF>49</tempMinF>
        <windspeedMiles>9</windspeedMiles>
        <windspeedKmph>15</windspeedKmph>
        <winddirection>WSW</winddirection>
        <winddir16Point>WSW</winddir16Point>
        <winddirDegree>241</winddirDegree>
        <weatherCode>113</weatherCode>
        <weatherIconUrl>http://www.worldweatheronline.com/images/wsymbols01_png_64/wsymbol_0001_sunny.png</weatherIconUrl>
        <weatherDesc>Sunny</weatherDesc>
        <precipMM>0.0</precipMM>
    </weather>
</data>

Как видите, все довольно нативно и просто: нам возвращается имя города, дата, температура в градусах имени товарищей Цельсия и Фаренгейта, скорость ветра в милях и километрах в час, направление ветра, иконка погоды и описание погоды. Дальше все можно разбирать парсером и выгружать на сайт. Наша задача решена!

Опишу все параметры, которые можно передать в запросе на погоду (http://free.worldweatheronline.com/feed/weather.ashx):

q — непосредственно запрос на точку. Может выглядеть как:

Имя города:
Имя Города
Имя Города, Штат (только для США)
Имя Города, Штат, Страна
Имя Города, Страна
К примеру: q=New+York или q=New+york,ny или q=London,united+kingdom

IP адрес
К примеру: q=101.25.32.325

Британский или канадский почтовый код или Zipcode США
К примеру: q=SW1 или q=90201

Широта и Долгота (в десятичных величинах, а не в градусах)
К примеру: q=48.834,2.394

Обязательно проверяйте запрашиваемую информацию на возможность подстановки её в URL! Иначе просто не получите нужного ответа.

extra (опционально) — позволяет запрашивать дополнительную информацию от сервера
localObsTime — возвращает текущее время в UTC, а также местное время в точке наблюдения.
isDayTime — возвращает «yes», если время дневное, и «no», если ночное. (Доступно только для Premium API с 3-х, 6-ти и 12-ти часовым интервалом запросов)
utcDateTime — если пользователь хочет увидеть время в формате UTC, а не местное время (Доступно только для Premium API)

num_of_days — продолжительность прогноза в днях

date (опционально) — прогноз и данные на точную дату. Можно указать значения today(сегодня), tomorrow(завтра) или же дату в формате yyyy-MM-dd.

fx (опционально) — триггер нормированного вывода погоды (yes или no).

cc (опционально) — выводит текущие погодные условия в точке (yes или no).

includeLocation (опционально) — возвращает ближайшую точку для заданного запроса q (yes или no). По дефолту — no.

format — формат вывода. xml, csv или json.

show_comments (опционально) — отключает CSV/TAB-комментарии из вывода (yes или no). По дефолту — yes.

callback (опционально) — используется только для функции json-callback

key — Ваш уникальный API-ключ.

Также система умеет генерировать прогноз по температурам воды и прогноз для серферов. Запрос для него можно автоматически сгенерировать здесь.

А теперь о бюрократии — об условиях использования бесплатной версии:
1. Ограничение в 500 запросов в час (но с поддержкой кэширования данных). Таким образом, свежая информация будет поступать каждые 15 минут. Как говорят разработчики, они используют гибкую политику ограничений, так что можно им написать письмо с просьбой увеличения лимита запросов в час за n-цать долларов в день.

2. Можно использовать сервис на мобильных и невёб платформах. Но линкбэк обязателен.

3. Использование на сайте и в блоге также требует использования линкбэка, который можно найти тут.

За сим всё! Безошибочного Вам кода!