Cerca il meteo

Lo strumento lookup_weather consente a un LLM di recuperare le condizioni ambientali di una località: meteo, qualità dell'aria e polline. Una singola richiesta può eseguire query su una, due o tutte e tre le funzionalità ambientali per un ID luogo, un indirizzo o le coordinate di latitudine/longitudine.

Le richieste che eseguono query solo sul meteo o sulla qualità dell'aria attuale e prevista vengono fatturate in base allo SKU Maps Grounding Essentials. Pro aggiunge le previsioni giornaliere sui pollini e la cronologia della qualità dell'aria fino a 30 giorni nel passato.

Puoi chiamare lookup_weather tramite il server MCP o come metodo REST lookupWeather. Questa pagina descrive le funzionalità ambientali, le opzioni di richiesta, le opzioni Pro, la struttura della risposta e le regole di fatturazione. Per gli schemi completi, consulta il riferimento MCP lookup_weather e il riferimento REST lookupWeather.

Funzionalità e orizzonti temporali

Utilizza l'array capabilities per selezionare i domini ambientali da restituire (WEATHER, AIR_QUALITY, POLLEN). capabilities è obbligatorio ogni volta che imposti weather_options, air_quality_options o language_code. Se ometti capabilities, weather_options, air_quality_options e language_code, lookup_weather viene eseguito in modalità meteo legacy e restituisce campi meteo di primo livello piatti.

Tutti i valori date e hour vengono valutati nel fuso orario locale della località richiesta. La tabella seguente riassume gli intervalli di tempo e gli SKU supportati per ogni funzionalità:

Capacità Condizioni attuali (date e hour omesse) Condizioni passate Condizioni di previsione SKU
WEATHER Meteo attuale Fino a 24 ore nel passato (richiede sia date che hour; il passato date senza hour non è supportato) Previsione oraria fino a 240 ore (10 giorni) se è impostato hour o previsione giornaliera fino a 10 giorni se è impostato solo date Essentials
AIR_QUALITY Qualità dell'aria oraria attuale Fino a 720 ore (30 giorni) nel passato per una singola ora quando sono impostati date e hour, o fino a 29 giorni prima di oggi (fino a 24 voci orarie) quando è impostato solo date Fino a 96 ore (4 giorni) nel futuro per una singola ora quando sono impostati date e hour oppure da oggi fino a 3 giorni dopo oggi (fino a 24 voci orarie) quando è impostato solo date Informazioni essenziali per le condizioni attuali, l'intera giornata di oggi e le previsioni. Pro per un date precedente a oggi o un hour passato quando viene restituito nella risposta
POLLEN Previsione giornaliera della concentrazione di pollini per il giorno corrente Non supportato (restituisce un errore INVALID_ARGUMENT) Previsione giornaliera della concentrazione di pollini fino a 4 giorni dopo oggi, per 5 giorni incluso oggi (hour viene ignorato per i pollini) Pro quando viene restituito nella risposta

Per AIR_QUALITY, la finestra di previsione che va da 720 ore nel passato a 96 ore nel futuro è ancorata all'ora corrente. Le richieste per l'intera giornata (date senza hour) coprono dalle 00:00 alle 23:00 ora locale e devono rientrare in questo intervallo, in pratica da 29 giorni prima di oggi a tre giorni dopo oggi.

Quando una richiesta include più funzionalità, l'orizzonte temporale di ciascuna funzionalità viene valutato in modo indipendente. Se i valori date e hour richiesti rientrano nell'intervallo per almeno una funzionalità richiesta, la risposta restituisce i container delle funzionalità supportate e omette qualsiasi funzionalità il cui intervallo di tempo non è supportato. Ad esempio, se richiedi AIR_QUALITY e POLLEN per una data passata entro 30 giorni, viene restituito airQuality e viene omesso pollen. La richiesta restituisce un errore INVALID_ARGUMENT se date o hour non rientrano nell'intervallo supportato di ogni funzionalità richiesta.

Opzioni di richiesta

L'LLM imposta queste opzioni quando chiama lo strumento, in base alla richiesta dell'utente e alla descrizione dello strumento. Puoi influenzare le opzioni utilizzate dal modello con le tue istruzioni. Consulta Controlla l'utilizzo di Pro.

La tabella seguente descrive le opzioni di richiesta per lookup_weather:

Opzione Descrizione
location Obbligatorio. La località su cui eseguire la query, specificata come address (un indirizzo, una città o un nome di un punto di riferimento leggibile), place_id o lat_lng (latitude e longitude).
capabilities Facoltativo. Uno o più valori tra WEATHER, AIR_QUALITY e POLLEN. I valori duplicati vengono deduplicati. Obbligatorio quando imposti weather_options, air_quality_options o language_code. Quando capabilities e queste opzioni vengono omesse, viene restituita la risposta meteo con campo piatto precedente.
date Facoltativo. La data civile locale (year, month, day) nella località richiesta. Ometti date e hour per le condizioni attuali.
hour Facoltativo. L'ora locale (da 0 a 23) nella località richiesta. Richiede l'impostazione di date. L'impostazione di hour senza date restituisce un errore INVALID_ARGUMENT.
language_code Facoltativo. Il codice lingua BCP-47 per il testo localizzato nella risposta, ad esempio en, ja o fr-CA. Il valore predefinito è en.
weather_options.units_system Facoltativo. Il sistema di unità di misura per i valori meteo: METRIC (predefinito; Celsius, chilometri orari, millimetri) o IMPERIAL (Fahrenheit, miglia orarie, pollici). Ignorato se WEATHER non è richiesto.
air_quality_options.include_pollutant_concentration Facoltativo. Quando true, airQuality.hourlyResults[].pollutants[] include le concentrazioni di agenti inquinanti misurate, le fonti di emissione e gli effetti sulla salute. Il valore predefinito è false. Ignorato se AIR_QUALITY non è richiesto.
air_quality_options.index_region_code Facoltativo. Codice paese o regione ISO 3166-1 alpha-2 di due lettere, ad esempio US, FR o CN, utilizzato per selezionare una scala dell'indice di qualità dell'aria (IQA) locale insieme all'IQA universale (IQA-U). Il valore predefinito è la regione della località richiesta. Ignorato se AIR_QUALITY non è richiesto.

Opzioni Pro

Due opzioni selezionano lo SKU Maps Grounding Pro. Una richiesta viene fatturata con lo SKU Pro quando nella risposta viene restituita una delle due opzioni. Per le regole di fatturazione per più funzionalità, consulta Fatturazione e quote. La tabella seguente descrive le opzioni Pro:

Opzione Pro Quando utilizzarla
POLLEN in capabilities L'utente chiede informazioni sui livelli di polline, sulle allergie stagionali, sul polline di alberi, erba o piante infestanti o su specie di piante allergeniche specifiche.
AIR_QUALITY in capabilities con un date prima di oggi o un hour passato L'utente chiede informazioni sulla qualità dell'aria, sul fumo o sull'inquinamento storici negli ultimi 30 giorni nel fuso orario della località.

Tutte le altre richieste lookup_weather vengono fatturate in base allo SKU Essentials, tra cui:

  • Tutte le richieste WEATHER (correnti, cronologia di 24 ore e previsioni orarie o giornaliere di 10 giorni).
  • Richieste attuali, per l'intera giornata di oggi (date impostato su oggi senza hour) e di previsione AIR_QUALITY, incluse le richieste che impostano include_pollutant_concentration su true o specificano index_region_code.

Esempio

La seguente richiesta MCP chiede informazioni sul meteo attuale, sulla qualità dell'aria (con concentrazioni di inquinanti) e sulle previsioni dei pollini di oggi a Tokyo. Poiché capabilities include POLLEN, la richiesta viene fatturata con lo 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
}

L'esempio seguente invia la stessa richiesta al metodo 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"

Sostituisci API_KEY con la tua chiave API.

Risposta

Quando una richiesta specifica capabilities, la risposta compila i container specifici del dominio per ogni funzionalità richiesta insieme ai metadati sulla posizione:

  • returnedLocation: la località risolta (address, placeId o latLng, corrispondente al tipo di location di input) per i dati ambientali.
  • timeZone: l'identificatore del fuso orario IANA risolto per la località, ad esempio "America/Los_Angeles" o "Asia/Tokyo".
  • weather: compilato quando viene richiesto WEATHER:
    • dateTime (per le query attuali e orarie), come timestamp UTC, o date (per le query di previsione giornaliera). Per mostrare gli orari locali, converti dateTime con il campo timeZone.
    • Temperatura (temperature, feelsLikeTemperature, heatIndex o maxTemperature, minTemperature, feelsLikeMaxTemperature, feelsLikeMinTemperature, maxHeatIndex giornaliera).
    • weatherCondition, precipitation, wind, airPressure, relativeHumidity, uvIndex, thunderstormProbability, cloudCover, sunEvents e moonEvents giornalieri. Gli orari di alba, tramonto, sorgere e tramontare della luna sono timestamp UTC.
    • attribution: l'attribuzione che devi mostrare con i dati meteo.
  • airQuality: compilato quando viene richiesto AIR_QUALITY:
    • hourlyResults[]: contiene una voce per le query attuali o di una singola ora oppure fino a 24 voci che coprono l'intera giornata locale (da 00:00 a 23:00) quando è impostato solo date. Quando date è oggi e hour viene omesso, le voci combinano le ore storiche precedenti di oggi, l'ora corrente e le ore di previsione rimanenti. Ogni voce include:
      • dateTime: la data e l'ora civili locali (year, month, day, hours, minutes, seconds e utcOffset) nel fuso orario della località.
      • indexes[]: l'IQA universale e, se disponibile, l'IQA locale (displayName, value, valueDisplay, category e dominantPollutant).
      • pollutants[]: compilato quando include_pollutant_concentration è true (displayName, fullName, concentration in ppb o µg/m³ e additionalInfo con emissione sources e salute effects).
      • healthRecommendations: indicazioni per generalPopulation, elderly, lungDiseasePopulation, heartDiseasePopulation, athletes, pregnantWomen e children.
    • attribution: l'attribuzione che devi mostrare con i dati sulla qualità dell'aria.
  • pollen: compilato quando viene richiesto POLLEN:
    • dailyForecast: la previsione della concentrazione di polline per l'date richiesto:
      • date: la data del calendario civile della previsione.
      • categories[]: categorie generali di allergeni (Tree, Grass e Weed), ciascuna con displayName, inSeason, indice universale dei pollini index (scala da 0 a 5, category e description) e healthRecommendations[].
      • plantSpecies[]: specie di piante allergeniche specifiche (come betulla, ambrosia o cedro giapponese), ciascuna con code, displayName, family botanico, inSeason, indice universale dei pollini index, season di fioritura tipica e crossReactions.
    • attribution: l'attribuzione che devi mostrare con i dati sui pollini.

Disponibilità parziale delle funzionalità

Quando una richiesta include più funzionalità, ogni funzionalità viene valutata e recuperata in modo indipendente. Se una funzionalità non è disponibile per la località richiesta, non rientra nell'intervallo di tempo supportato o non riesce temporaneamente mentre almeno un'altra funzionalità ha esito positivo, la risposta restituisce i container delle funzionalità disponibili e omette il container non disponibile o non riuscito. La richiesta non va a buon fine con un errore solo se tutte le funzionalità richieste non vanno a buon fine.

Per i dettagli completi dei campi, consulta il riferimento lookup_weather.

Fatturazione e quote

Ogni richiesta lookup_weather è un evento fatturabile, anche quando capabilities richiede due o tre domini ambientali nella stessa chiamata:

  • Una richiesta viene fatturata in base al livello SKU più alto tra le funzionalità che hanno esito positivo e vengono restituite nella risposta:
    • Se la risposta include pollen o airQuality storici (un date prima di oggi o un hour passato nel fuso orario della località), la richiesta viene fatturata con lo SKU Maps Grounding Pro. La richiesta di POLLEN e AIR_QUALITY storici in un'unica chiamata viene comunque conteggiata come un evento fatturabile Pro.
    • In caso contrario, la richiesta viene fatturata in base allo SKU Maps Grounding Essentials.
  • Se una funzionalità Pro viene omessa in una richiesta con più funzionalità, perché non è disponibile per la località, non rientra nell'intervallo di tempo supportato o non riesce temporaneamente, e nella risposta vengono restituite solo le funzionalità Essentials, la richiesta viene fatturata in base allo SKU Essentials.

La quota di lookup_weather è di 300 query al minuto per ogni progetto, condivisa da entrambi gli SKU. Per i prezzi, consulta la tabella dei prezzi principale e la tabella dei prezzi per l'India.