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

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

Посмотреть погоду

Инструмент lookup_weather позволяет LLM получать данные об условиях окружающей среды в определенном месте: погоде, качестве воздуха и пыльце. В одном запросе можно запросить одну, две или все три экологические возможности для идентификатора места, адреса или координат широты/долготы.

Запросы, которые запрашивают только погоду или текущее и прогнозируемое качество воздуха, оплачиваются по коду Maps Grounding Essentials SKU. Pro добавляет ежедневные прогнозы уровня пыльцы и статистику качества воздуха за последние 30 дней.

Вы можете вызвать lookup_weather через сервер MCP или как метод REST lookupWeather. На этой странице описаны возможности, связанные с окружающей средой, параметры запросов, параметры Pro, структура ответов и правила оплаты. Полные схемы приведены в справочнике по MCP lookup_weather и справочнике по REST lookupWeather.

Возможности и временные горизонты

Используйте массив capabilities, чтобы выбрать, какие домены окружающей среды нужно вернуть (WEATHER, AIR_QUALITY, POLLEN). Массив capabilities обязателен, если вы задаете weather_options, air_quality_options или language_code. Если вы не укажете capabilities, weather_options, air_quality_options и language_code, lookup_weather будет работать в устаревшем режиме и возвращать простые поля погоды верхнего уровня.

Все значения date и hour оцениваются в местном часовом поясе запрошенного местоположения. В таблице ниже приведены поддерживаемые диапазоны дат и SKU для каждой функции.

Возможности	Текущая погода (`date` и `hour` не указаны)	Перенесенные заболевания	Прогноз погоды	Код товара
`WEATHER`	Текущая погода	До 24 часов в прошлом (требуются оба параметра: `date` и `hour`; параметр `date` без `hour` не поддерживается).	Почасовой прогноз на срок до 240 часов (10 дней), если задан параметр `hour`, или ежедневный прогноз на срок до 10 дней, если задан только параметр `date`.	Essentials
`AIR_QUALITY`	Текущее качество воздуха по часам	До 720 часов (30 дней) в прошлом для одного часа, если заданы параметры `date` и `hour`, или до 29 дней до сегодняшнего дня (до 24 записей за час), если задан только параметр `date`.	До 96 часов (4 дней) в будущем для одного часа, если заданы `date` и `hour`, или от сегодняшнего дня до трех дней после сегодняшнего дня (до 24 записей по часам), если задано только `date`.	Основные сведения о текущей погоде, погоде на сегодня и прогнозе. Pro для `date` до сегодняшнего дня или прошедшего `hour`, если возвращается в ответе.
`POLLEN`	Прогноз содержания пыльцы на текущий день	Не поддерживается (возвращает ошибку `INVALID_ARGUMENT`)	Ежедневный прогноз уровня пыльцы на срок до четырех дней после сегодняшнего, то есть на пять дней, включая сегодняшний (параметр `hour` игнорируется).	Pro, если возвращается в ответе.

Для AIR_QUALITY окно прогноза от 720 часов в прошлом до 96 часов в будущем привязано к текущему часу. Запросы за полный день (date без hour) охватывают период с 00:00 до 23:00 по местному времени и должны укладываться в этот интервал – на практике от 29 дней до сегодняшнего дня и до трех дней после сегодняшнего дня.

Если запрос включает несколько возможностей, временной горизонт каждой из них оценивается независимо. Если запрашиваемые значения date и hour находятся в пределах диапазона хотя бы для одной запрашиваемой возможности, в ответе возвращаются контейнеры поддерживаемых возможностей, а все возможности, интервал времени которых не поддерживается, опускаются. Например, если запросить AIR_QUALITY и POLLEN за прошедшую дату в пределах 30 дней, будет возвращено значение airQuality, а pollen будет опущено. Если значение date или hour выходит за пределы поддерживаемого диапазона для всех запрошенных возможностей, запрос возвращает ошибку INVALID_ARGUMENT.

Параметры запроса

LLM задает эти параметры при вызове инструмента на основе запроса пользователя и описания инструмента. Вы можете повлиять на то, какие варианты использует модель, с помощью собственных инструкций. Подробнее о том, как управлять использованием Pro…

В таблице ниже описаны параметры запроса для lookup_weather.

Option	Описание
`location`	Обязательно. Местоположение, которое нужно запросить, указанное как `address` (человекочитаемый адрес, город или название ориентира), `place_id` или `lat_lng` (`latitude` и `longitude`).
`capabilities`	Необязательное поле. Одно или несколько значений из `WEATHER`, `AIR_QUALITY` и `POLLEN`. Повторяющиеся значения удаляются. Обязательно при настройке `weather_options`, `air_quality_options` или `language_code`. Если параметр `capabilities` и все эти параметры опущены, возвращается устаревший ответ с плоскими полями.
`date`	Необязательное поле. Местная гражданская дата (`year`, `month`, `day`) в запрошенном местоположении. Пропустите `date` и `hour` для текущих условий.
`hour`	Необязательное поле. Местное время (от `0` до `23`) в запрошенном местоположении. Требуется задать `date`. Если задать `hour` без `date`, возвращается ошибка `INVALID_ARGUMENT`.
`language_code`	Необязательное поле. Код языка по стандарту BCP-47 для локализованного текста в ответе, например `en`, `ja` или `fr-CA`. Значение по умолчанию – `en`.
`weather_options.units_system`	Необязательное поле. Система единиц измерения для погодных значений: `METRIC` (по умолчанию; градусы Цельсия, километры в час, миллиметры) или `IMPERIAL` (градусы Фаренгейта, мили в час, дюймы). Игнорируется, если `WEATHER` не запрашивается.
`air_quality_options.include_pollutant_concentration`	Необязательное поле. Если `true`, `airQuality.hourlyResults[].pollutants[]` включает измеренные концентрации загрязняющих веществ, источники выбросов и влияние на здоровье. Значение по умолчанию – `false`. Игнорируется, если `AIR_QUALITY` не запрашивается.
`air_quality_options.index_region_code`	Необязательное поле. Двухбуквенный код страны или региона по стандарту ISO 3166-1 alpha-2, например `US`, `FR` или `CN`, который используется для выбора местной шкалы индекса качества воздуха (AQI) наряду с универсальным индексом качества воздуха (UAQI). По умолчанию используется регион запрошенного местоположения. Игнорируется, если `AIR_QUALITY` не запрашивается.

Возможности Pro

Два варианта выбора Maps Grounding Pro SKU. Если в ответе возвращается любой из этих вариантов, запрос оплачивается по коду Pro. Правила оплаты за использование нескольких функций описаны в разделе Оплата и квоты. В таблице ниже описаны варианты Pro.

Версия Pro	Для чего его можно использовать
`POLLEN` (`capabilities`)	Пользователь спрашивает об уровне пыльцы, сезонной аллергии, пыльце деревьев, трав или сорняков или конкретных видах аллергенных растений.
`AIR_QUALITY` в `capabilities` с `date` до сегодняшнего дня или за прошлый `hour`	Пользователь спрашивает о качестве воздуха, задымлении или загрязнении за последние 30 дней в часовом поясе местоположения.

Все остальные запросы lookup_weather оплачиваются по тарифу Essentials, в том числе:

Все запросы WEATHER (текущие, история за 24 часа, а также почасовые или ежедневные прогнозы на 10 дней).
Текущие запросы, запросы за полный сегодняшний день (параметр date установлен на сегодня без параметра hour) и прогнозные запросы AIR_QUALITY, включая запросы, в которых параметр include_pollutant_concentration установлен на true или указан параметр index_region_code.

Пример

В следующем запросе MCP запрашивается текущая погода, качество воздуха (с концентрацией загрязняющих веществ) и сегодняшний прогноз пыльцы в Токио. Поскольку capabilities включает POLLEN, запрос оплачивается по коду Pro:

{
  "method": "tools/call",
  "params": {
    "name": "lookup_weather",
    "arguments": {
      "location": {"address": "Tokyo, Japan"},
      "capabilities": ["WEATHER", "AIR_QUALITY", "POLLEN"],
      "weather_options": {
        "units_system": "METRIC"
      },
      "air_quality_options": {
        "include_pollutant_concentration": true
      },
      "language_code": "en"
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

В примере ниже показано, как отправить такой же запрос в метод REST lookupWeather.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "location": {"address": "Tokyo, Japan"},
  "capabilities": ["WEATHER", "AIR_QUALITY", "POLLEN"],
  "weatherOptions": {"unitsSystem": "METRIC"},
  "airQualityOptions": {"includePollutantConcentration": true},
  "languageCode": "en"
}' \
"https://mapstools.googleapis.com/v1:lookupWeather"

Укажите вместо API_KEY свой ключ API.

Ответ

Если в запросе указан параметр capabilities, в ответе будут заполнены контейнеры для каждой запрошенной функции, а также географические метаданные:

returnedLocation – определенное местоположение (address, placeId или latLng, соответствующее типу входных данных location) для данных об окружающей среде.
timeZone – распознанный идентификатор часового пояса IANA для местоположения, например "America/Los_Angeles" или "Asia/Tokyo".
weather: заполняется, когда запрашивается WEATHER:
- dateTime (для текущих и почасовых запросов) в виде временной метки UTC или date (для запросов прогноза на день). Чтобы показывать местное время, преобразуйте dateTime с помощью поля timeZone.
- Температура (temperature, feelsLikeTemperature, heatIndex или ежедневная maxTemperature, minTemperature, feelsLikeMaxTemperature, feelsLikeMinTemperature, maxHeatIndex).
- weatherCondition, precipitation, wind, airPressure, relativeHumidity, uvIndex, thunderstormProbability, cloudCover, а также ежедневные sunEvents и moonEvents. Время восхода и захода солнца и луны указывается в формате UTC.
- attribution – указание авторства, которое должно отображаться вместе с данными о погоде.
airQuality: заполняется, когда запрашивается AIR_QUALITY:
- hourlyResults[] – содержит одну запись для текущих или одночасовых запросов или до 24 записей, охватывающих полный местный день (с 00:00 до 23:00), если задано только значение date. Если в качестве значения date указана сегодняшняя дата, а значение hour не задано, то в записях будут объединены данные за прошедшие часы сегодняшнего дня, текущий час и оставшиеся часы, для которых доступен прогноз. Каждая запись содержит:
  - dateTime – местная гражданская дата и время (year, month, day, hours, minutes, seconds и utcOffset) в часовом поясе местоположения.
  - indexes[] – универсальный ИКВ и, если доступен, местный ИКВ (displayName, value, valueDisplay, category и dominantPollutant).
  - pollutants[]: заполняется, если include_pollutant_concentration – это true (displayName, fullName, concentration в ppb или µg/m³, а также additionalInfo с выбросами sources и здоровьем effects).
  - healthRecommendations: рекомендации для generalPopulation, elderly, lungDiseasePopulation, heartDiseasePopulation, athletes, pregnantWomen и children.
- attribution – указание авторства, которое должно отображаться вместе с данными о качестве воздуха.
pollen: заполняется, когда запрашивается POLLEN:
- dailyForecast – прогноз уровня пыльцы для запрошенного date:
  - date – дата прогноза по гражданскому календарю.
  - categories[] – широкие категории аллергенов (Tree, Grass и Weed), каждая из которых содержит displayName, inSeason, универсальный индекс пыльцы index (шкала от 0 до 5, category и description) и healthRecommendations[].
  - plantSpecies[] – конкретные виды растений-аллергенов (например, береза, амброзия или криптомерия японская). Для каждого из них указываются code, displayName, ботаническое family, inSeason, универсальный индекс пыльцы index, типичный период цветения season и crossReactions.
- attribution – указание авторства, которое должно отображаться вместе с данными о пыльце.

Частичная доступность функций

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

Подробные сведения о полях приведены в справочнике по lookup_weather.

Оплата и квоты

Каждый запрос lookup_weather – это одно оплачиваемое событие, даже если capabilities запрашивает два или три домена среды в одном вызове:

Запрос оплачивается по самому высокому уровню SKU среди функций, которые успешно выполняются и возвращаются в ответе:
- Если ответ содержит pollen или исторические данные airQuality (date до сегодняшнего дня или hour в прошлом в часовом поясе местоположения), запрос оплачивается по SKU Maps Grounding Pro. Запрос POLLEN и AIR_QUALITY за прошлые периоды в рамках одного вызова по-прежнему считается одним платным событием Pro.
- В противном случае запрос оплачивается по коду Maps Grounding Essentials SKU.
Если в запросе с несколькими возможностями не указана возможность Pro (поскольку она недоступна для местоположения, находится за пределами поддерживаемого диапазона времени или временно не работает) и в ответе возвращаются только возможности Essentials, запрос оплачивается по тарифу Essentials.

Квота lookup_weather составляет 300 запросов в минуту на проект и является общей для обоих кодов SKU. Цены приведены в основной таблице цен и таблице цен для Индии.