Use mais recursos das ferramentas de agentes Experimentos do Maps com a SKU Pro. Saiba mais sobre o Pro

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Consultar o clima

A ferramenta lookup_weather permite que um LLM recupere as condições ambientais de um local: clima, qualidade do ar e pólen. Uma única solicitação pode consultar um, dois ou todos os três recursos ambientais para um ID de lugar, endereço ou coordenadas de latitude/longitude.

As solicitações que consultam apenas o clima ou a qualidade do ar atual e prevista são cobradas pela SKU Maps Grounding Essentials. O Pro adiciona previsões diárias de pólen e o histórico de qualidade do ar de até 30 dias atrás.

É possível chamar lookup_weather pelo servidor MCP ou como o método REST lookupWeather. Nesta página, descrevemos os recursos ambientais, as opções de solicitação, as opções Pro, a estrutura de resposta e as regras de faturamento. Para ver os esquemas completos, consulte a referência do MCP do lookup_weather e a referência REST do lookupWeather.

Recursos e horizontes de tempo

Use a matriz capabilities para selecionar quais domínios ambientais retornar (WEATHER, AIR_QUALITY, POLLEN). capabilities é obrigatório sempre que você define weather_options, air_quality_options ou language_code. Se você omitir capabilities, weather_options, air_quality_options e language_code, lookup_weather será executado no modo de clima legado e retornará campos de clima simples de nível superior.

Todos os valores de date e hour são avaliados no fuso horário local do local solicitado. A tabela a seguir resume os períodos e as SKUs compatíveis com cada recurso:

Capacidade	Condições atuais (`date` e `hour` omitidos)	Condições anteriores	Condições de previsão	SKU
`WEATHER`	Tempo no momento	Até 24 horas no passado (requer `date` e `hour`; o passado `date` sem `hour` não é compatível)	Previsão por hora de até 240 horas (10 dias) quando `hour` está definido ou previsão diária de até 10 dias quando apenas `date` está definido.	Essentials
`AIR_QUALITY`	Qualidade do ar atual por hora	Até 720 horas (30 dias) no passado para uma única hora quando `date` e `hour` estão definidos, ou até 29 dias antes de hoje (até 24 entradas por hora) quando apenas `date` está definido	Até 96 horas (4 dias) no futuro para uma única hora quando `date` e `hour` estão definidos, ou de hoje até 3 dias depois de hoje (até 24 entradas por hora) quando apenas `date` está definido	Informações essenciais para o momento atual, o dia de hoje e a previsão. Pro para um `date` antes de hoje ou um `hour` anterior quando retornado na resposta
`POLLEN`	Previsão diária de pólen para o dia atual	Não compatível (retorna um erro `INVALID_ARGUMENT`)	Previsão diária de pólen para até 4 dias após hoje, por 5 dias, incluindo hoje (`hour` é ignorado para pólen)	Pro quando retornada na resposta.

Para AIR_QUALITY, a janela de previsão de 720 horas anteriores a 96 horas é ancorada na hora atual. As solicitações de dia inteiro (date sem hour) abrangem de 00:00 a 23:00 no horário local e precisam se encaixar nessa janela, na prática, de 29 dias antes de hoje até três dias depois de hoje.

Quando uma solicitação inclui vários recursos, o horizonte de tempo de cada um é avaliado de forma independente. Se os valores de date e hour solicitados estiverem dentro do intervalo de pelo menos um recurso solicitado, a resposta vai retornar os contêineres de recursos compatíveis e omitir qualquer recurso com um período incompatível. Por exemplo, solicitar AIR_QUALITY e POLLEN para uma data anterior em até 30 dias retorna airQuality e omite pollen. A solicitação vai retornar um erro INVALID_ARGUMENT se date ou hour estiver fora do intervalo aceito de cada recurso solicitado.

Opções de solicitação

O LLM define essas opções ao chamar a ferramenta, com base na solicitação do usuário e na descrição da ferramenta. É possível influenciar as opções que o modelo usa com suas próprias instruções. Consulte Controlar o uso do Pro.

A tabela a seguir descreve as opções de solicitação para lookup_weather:

Opção	Descrição
`location`	Obrigatório. O local a ser consultado, especificado como um `address` (um endereço, cidade ou nome de ponto de referência legível por humanos), um `place_id` ou um `lat_lng` (`latitude` e `longitude`).
`capabilities`	Opcional. Um ou mais valores de `WEATHER`, `AIR_QUALITY` e `POLLEN`. Os valores duplicados são eliminados. Obrigatório ao definir `weather_options`, `air_quality_options` ou `language_code`. Quando `capabilities` e essas opções são omitidas, retorna a resposta meteorológica de campo plano legada.
`date`	Opcional. A data civil local (`year`, `month`, `day`) no local solicitado. Omita `date` e `hour` para as condições atuais.
`hour`	Opcional. A hora local (`0` a `23`) no local solicitado. Requer que `date` seja definido. Definir `hour` sem `date` retorna um erro `INVALID_ARGUMENT`.
`language_code`	Opcional. O código de idioma BCP-47 para texto localizado na resposta, como `en`, `ja` ou `fr-CA`. O padrão é `en`.
`weather_options.units_system`	Opcional. O sistema de unidades para valores climáticos: `METRIC` (padrão; Celsius, quilômetros por hora, milímetros) ou `IMPERIAL` (Fahrenheit, milhas por hora, polegadas). Será ignorado se `WEATHER` não for solicitado.
`air_quality_options.include_pollutant_concentration`	Opcional. Quando `true`, `airQuality.hourlyResults[].pollutants[]` inclui concentrações de poluentes medidas, fontes de emissão e efeitos na saúde. O valor padrão é `false`. Será ignorado se `AIR_QUALITY` não for solicitado.
`air_quality_options.index_region_code`	Opcional. Código de país ou região ISO 3166-1 alfa-2 de duas letras (por exemplo, `US`, `FR` ou `CN`) usado para selecionar uma escala de índice de qualidade do ar (IQA) local junto com o IQA universal (UAQI). O padrão é a região do local solicitado. Será ignorado se `AIR_QUALITY` não for solicitado.

Opções do Pro

Duas opções selecionam a SKU do Maps Grounding Pro. Uma solicitação é faturada com a SKU Pro quando uma das opções é retornada na resposta. Para regras de faturamento de vários recursos, consulte Faturamento e cotas. A tabela a seguir descreve as opções do Pro:

Opção Pro	Quando usar
`POLLEN` em `capabilities`	O usuário pergunta sobre níveis de pólen, alergias sazonais, pólen de árvores, grama ou ervas daninhas ou espécies de plantas alergênicas específicas.
`AIR_QUALITY` em `capabilities` com um `date` antes de hoje ou um `hour` anterior	O usuário pergunta sobre o histórico de qualidade do ar, fumaça ou poluição nos últimos 30 dias no fuso horário do local.

Todas as outras solicitações de lookup_weather são faturadas na SKU Essentials, incluindo:

Todas as solicitações de WEATHER (histórico atual de 24 horas e previsões por hora ou diárias de 10 dias).
Solicitações atuais, de dia inteiro (date definido como hoje sem hour) e de previsão AIR_QUALITY, incluindo solicitações que definem include_pollutant_concentration como true ou especificam index_region_code.

Exemplo

A solicitação do MCP a seguir pede o clima atual, a qualidade do ar (com concentrações de poluentes) e a previsão de pólen de hoje em Tóquio. Como capabilities inclui POLLEN, a solicitação é faturada na SKU 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
}

O exemplo a seguir envia a mesma solicitação para o método 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"

Substitua API_KEY pela sua chave de API.

Resposta

Quando uma solicitação especifica capabilities, a resposta preenche contêineres específicos do domínio para cada recurso solicitado, além de metadados de local:

returnedLocation: o local resolvido (address, placeId ou latLng, correspondente ao tipo de entrada location) para os dados ambientais.
timeZone: o identificador de fuso horário da IANA resolvido para o local, como "America/Los_Angeles" ou "Asia/Tokyo".
weather: preenchido quando WEATHER é solicitado:
- dateTime (para consultas atuais e por hora), como um carimbo de data/hora UTC, ou date (para consultas de previsão diária). Para mostrar os horários locais, converta dateTime com o campo timeZone.
- Temperatura (temperature, feelsLikeTemperature, heatIndex ou maxTemperature, minTemperature, feelsLikeMaxTemperature, feelsLikeMinTemperature, maxHeatIndex diários).
- weatherCondition, precipitation, wind, airPressure, relativeHumidity, uvIndex, thunderstormProbability, cloudCover e sunEvents e moonEvents diários. Os horários do nascer e do pôr do sol e da lua são carimbos de data/hora UTC.
- attribution: a atribuição que você precisa mostrar com os dados meteorológicos.
airQuality: preenchido quando AIR_QUALITY é solicitado:
- hourlyResults[]: contém uma entrada para consultas atuais ou de uma única hora, ou até 24 entradas que cobrem o dia local completo (00:00 a 23:00) quando apenas date está definido. Quando date é hoje e hour é omitido, as entradas combinam as horas históricas anteriores de hoje, a hora atual e as horas de previsão restantes. Cada entrada inclui:
  - dateTime: a data e hora civil local (year, month, day, hours, minutes, seconds e utcOffset) no fuso horário do local.
  - indexes[]: IQA universal e, quando disponível, o IQA local (displayName, value, valueDisplay, category e dominantPollutant).
  - pollutants[]: preenchido quando include_pollutant_concentration é true (displayName, fullName, concentration em ppb ou µg/m³ e additionalInfo com emissão sources e saúde effects).
  - healthRecommendations: orientações para generalPopulation, elderly, lungDiseasePopulation, heartDiseasePopulation, athletes, pregnantWomen e children.
- attribution: a atribuição que você precisa mostrar com os dados de qualidade do ar.
pollen: preenchido quando POLLEN é solicitado:
- dailyForecast: a previsão de pólen para o date solicitado:
  - date: a data do calendário civil da previsão.
  - categories[]: categorias amplas de alérgenos (Tree, Grass e Weed), cada uma com displayName, inSeason, Índice Universal de Pólen index (escala de 0 a 5, category e description) e healthRecommendations[].
  - plantSpecies[]: espécies de plantas alergênicas específicas (como bétula, ambrosia ou cedro japonês), cada uma com code, displayName, family botânico, inSeason, índice universal de pólen index, season de floração típica e crossReactions.
- attribution: a atribuição que você precisa mostrar com os dados de pólen.

Disponibilidade parcial em todos os recursos

Quando uma solicitação inclui vários recursos, cada um é avaliado e buscado de forma independente. Se um recurso não estiver disponível para o local solicitado, fora do período aceito ou falhar temporariamente enquanto pelo menos outro recurso for bem-sucedido, a resposta vai retornar os contêineres de recursos disponíveis e omitir o contêiner indisponível ou com falha. A solicitação só vai falhar com um erro se todas as capacidades solicitadas falharem.

Para detalhes completos do campo, consulte a referência de lookup_weather.

Faturamento e cotas

Cada solicitação lookup_weather é um evento faturável, mesmo quando capabilities solicita dois ou três domínios ambientais na mesma chamada:

Uma solicitação é faturada de acordo com o nível de SKU mais alto entre os recursos que são bem-sucedidos e retornados na resposta:
- Se a resposta incluir pollen ou airQuality histórico (um date antes de hoje ou um hour anterior no fuso horário do local), a solicitação será faturada de acordo com a SKU do Maps Grounding Pro. Solicitar POLLEN e AIR_QUALITY histórico em uma chamada ainda conta como um evento faturável do Pro.
- Caso contrário, a solicitação será cobrada de acordo com a SKU Maps Grounding Essentials.
Se um recurso Pro for omitido em uma solicitação com vários recursos, porque ele não está disponível para o local, está fora do período aceito ou falha temporariamente, e apenas os recursos Essentials são retornados na resposta, a solicitação é faturada de acordo com a SKU Essentials.

A cota de lookup_weather é de 300 consultas por minuto para cada projeto, compartilhada por ambas as SKUs. Para saber os preços, consulte a tabela de preços principal e a tabela de preços da Índia.