Wetter abfragen

Mit dem Tool lookup_weather kann ein LLM Umweltbedingungen für einen Standort abrufen: Wetter, Luftqualität und Pollen. In einer einzelnen Anfrage können eine, zwei oder alle drei Umweltfunktionen für eine Orts-ID, eine Adresse oder Breiten-/Längengradkoordinaten abgefragt werden.

Anfragen, die nur Wetterdaten oder die aktuelle und vorhergesagte Luftqualität abfragen, werden über die Maps Grounding Essentials-SKU abgerechnet. Pro bietet tägliche Pollenvorhersagen und historische Luftqualitätsdaten für bis zu 30 Tage in der Vergangenheit.

Sie können lookup_weather über den MCP-Server oder als REST-Methode lookupWeather aufrufen. Auf dieser Seite werden die Umgebungsfunktionen, Anfrageoptionen, Pro-Optionen, die Antwortstruktur und die Abrechnungsregeln beschrieben. Die vollständigen Schemas finden Sie in der lookup_weather-MCP-Referenz und der lookupWeather-REST-Referenz.

Funktionen und Zeithorizonte

Verwenden Sie das Array capabilities, um auszuwählen, welche Umgebungsbereiche zurückgegeben werden sollen (WEATHER, AIR_QUALITY, POLLEN). capabilities ist immer erforderlich, wenn Sie weather_options, air_quality_options oder language_code festlegen. Wenn Sie capabilities, weather_options, air_quality_options und language_code weglassen, wird lookup_weather im Legacy-Wettermodus ausgeführt und gibt flache Wetterfelder auf oberster Ebene zurück.

Alle date- und hour-Werte werden in der lokalen Zeitzone des angeforderten Standorts ausgewertet. In der folgenden Tabelle sind die unterstützten Zeiträume und SKUs für die einzelnen Funktionen zusammengefasst:

Funktion Aktuelle Bedingungen (date und hour weggelassen) Vergangene Bedingungen Prognosebedingungen SKU
WEATHER Aktuelles Wetter Bis zu 24 Stunden in der Vergangenheit (erfordert sowohl date als auch hour; die Angabe von date ohne hour wird nicht unterstützt) Stündliche Vorhersage für bis zu 240 Stunden (10 Tage), wenn hour festgelegt ist, oder tägliche Vorhersage für bis zu 10 Tage, wenn nur date festgelegt ist Essentials
AIR_QUALITY Aktuelle stündliche Luftqualität Bis zu 720 Stunden (30 Tage) in der Vergangenheit für eine einzelne Stunde, wenn date und hour festgelegt sind, oder bis zu 29 Tage vor dem heutigen Tag (bis zu 24 stündliche Einträge), wenn nur date festgelegt ist Bis zu 96 Stunden (4 Tage) in der Zukunft für eine einzelne Stunde, wenn date und hour festgelegt sind, oder heute bis 3 Tage nach heute (bis zu 24 stündliche Einträge), wenn nur date festgelegt ist Wichtige Informationen zu den aktuellen Bedingungen, zum heutigen Tag und zur Vorhersage. Pro für ein date vor dem heutigen Tag oder ein vergangenes hour, wenn es in der Antwort zurückgegeben wird
POLLEN Tägliche Pollenflugvorhersage für den aktuellen Tag Nicht unterstützt (gibt einen INVALID_ARGUMENT-Fehler zurück) Tägliche Pollenflugvorhersage für bis zu 4 Tage nach dem aktuellen Tag, für 5 Tage einschließlich heute (hour wird für Pollen ignoriert) Pro, wenn in der Antwort zurückgegeben

Für AIR_QUALITY ist das Fenster für die 720 Stunden in der Vergangenheit bis 96 Stunden in der Zukunft an der aktuellen Stunde verankert. Ganztägige Anfragen (date ohne hour) decken 00:00 bis 23:00 Ortszeit ab und müssen in dieses Zeitfenster passen – in der Praxis von 29 Tagen vor dem heutigen Tag bis drei Tage nach dem heutigen Tag.

Wenn eine Anfrage mehrere Funktionen enthält, wird der Zeithorizont jeder Funktion unabhängig voneinander ausgewertet. Wenn die angeforderten date und hour für mindestens eine angeforderte Funktion im Bereich liegen, werden in der Antwort die unterstützten Funktionscontainer zurückgegeben und alle Funktionen, deren Zeitraum nicht unterstützt wird, werden weggelassen. Wenn Sie beispielsweise AIR_QUALITY und POLLEN für ein vergangenes Datum innerhalb von 30 Tagen anfordern, wird airQuality zurückgegeben und pollen weggelassen. Die Anfrage gibt den Fehler INVALID_ARGUMENT zurück, wenn date oder hour außerhalb des unterstützten Bereichs aller angeforderten Funktionen liegt.

Anfrageoptionen

Das LLM legt diese Optionen fest, wenn es das Tool aufruft, basierend auf der Anfrage des Nutzers und der Toolbeschreibung. Sie können mit Ihren eigenen Anweisungen beeinflussen, welche Optionen das Modell verwendet. Weitere Informationen finden Sie unter Nutzung von Pro steuern.

In der folgenden Tabelle werden die Anfrageoptionen für lookup_weather beschrieben:

Option Beschreibung
location Erforderlich. Der abzufragende Ort, angegeben als address (eine menschenlesbare Adresse, Stadt oder ein Wahrzeichen), als place_id oder als lat_lng (latitude und longitude).
capabilities Optional. Ein oder mehrere Werte aus WEATHER, AIR_QUALITY und POLLEN. Doppelte Werte werden dedupliziert. Erforderlich, wenn weather_options, air_quality_options oder language_code festgelegt wird. Wenn capabilities und diese Optionen alle weggelassen werden, wird die alte Wetterantwort mit flachen Feldern zurückgegeben.
date Optional. Das lokale bürgerliche Datum (year, month, day) am angeforderten Ort. Lassen Sie date und hour für die aktuellen Bedingungen weg.
hour Optional. Die lokale Stunde (0 bis 23) am angeforderten Ort. date muss festgelegt sein. Wenn Sie hour ohne date festlegen, wird der Fehler INVALID_ARGUMENT zurückgegeben.
language_code Optional. Der BCP-47-Sprachcode für lokalisierten Text in der Antwort, z. B. en, ja oder fr-CA. Die Standardeinstellung ist en.
weather_options.units_system Optional. Das Einheitensystem für Wetterwerte: METRIC (Standard; Celsius, Kilometer pro Stunde, Millimeter) oder IMPERIAL (Fahrenheit, Meilen pro Stunde, Zoll). Wird ignoriert, wenn WEATHER nicht angefordert wird.
air_quality_options.include_pollutant_concentration Optional. Wenn true, enthält airQuality.hourlyResults[].pollutants[] gemessene Schadstoffkonzentrationen, Emissionsquellen und gesundheitliche Auswirkungen. Die Standardeinstellung ist false. Wird ignoriert, wenn AIR_QUALITY nicht angefordert wird.
air_quality_options.index_region_code Optional. Zweistelliger Ländercode nach ISO 3166-1 alpha-2, z. B. US, FR oder CN, der verwendet wird, um neben dem Universal Air Quality Index (UAQI) eine lokale Luftqualitätsindex-Skala (LQI) auszuwählen. Die Standardeinstellung ist die Region des angeforderten Standorts. Wird ignoriert, wenn AIR_QUALITY nicht angefordert wird.

Pro-Optionen

Zwei Optionen wählen die Maps Grounding Pro-SKU aus. Eine Anfrage wird unter der Pro-SKU abgerechnet, wenn eine der beiden Optionen in der Antwort zurückgegeben wird. Informationen zu Abrechnungsregeln für mehrere Funktionen finden Sie unter Abrechnung und Kontingente. In der folgenden Tabelle werden die Pro-Optionen beschrieben:

Pro-Option Anwendungsbereich
POLLEN in capabilities Der Nutzer fragt nach Pollenkonzentrationen, saisonalen Allergien, Baum-, Gras- oder Unkrautpollen oder bestimmten allergenen Pflanzenarten.
AIR_QUALITY in capabilities mit einem date vor dem heutigen Tag oder einem hour in der Vergangenheit Der Nutzer fragt nach der Luftqualität, dem Rauch oder der Verschmutzung in den letzten 30 Tagen in der Zeitzone des Standorts.

Alle anderen lookup_weather-Anfragen werden unter der Essentials-SKU abgerechnet, darunter:

  • Alle WEATHER-Anfragen (aktuelle, 24-Stunden-Verlauf und 10-Tage-Vorhersagen pro Stunde oder Tag).
  • Aktuelle, ganztägige (date auf heute festgelegt, ohne hour) und prognostizierte AIR_QUALITY-Anfragen, einschließlich Anfragen, bei denen include_pollutant_concentration auf true festgelegt ist oder index_region_code angegeben ist.

Beispiel

In der folgenden MCP-Anfrage werden das aktuelle Wetter, die Luftqualität (mit Schadstoffkonzentrationen) und die heutige Pollenvorhersage für Tokio abgefragt. Da capabilities POLLEN enthält, wird die Anfrage unter der Pro-SKU abgerechnet:

{
  "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
}

Im folgenden Beispiel wird dieselbe Anfrage an die REST-Methode lookupWeather gesendet:

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"

Ersetzen Sie dabei API_KEY durch Ihren eigenen API-Schlüssel.

Antwort

Wenn in einer Anfrage capabilities angegeben ist, werden in der Antwort domainspezifische Container für jede angeforderte Funktion zusammen mit Standortmetadaten ausgegeben:

  • returnedLocation: Der aufgelöste Standort (address, placeId oder latLng, entsprechend dem Eingabetyp location) für die Umweltdaten.
  • timeZone: Die aufgelöste IANA-Zeitzonenkennung für den Standort, z. B. "America/Los_Angeles" oder "Asia/Tokyo".
  • weather: Wird ausgefüllt, wenn WEATHER angefordert wird:
    • dateTime (für aktuelle und stündliche Abfragen) als UTC-Zeitstempel oder date (für tägliche Vorhersageabfragen). Wenn Sie Ortszeiten anzeigen möchten, konvertieren Sie dateTime mit dem Feld timeZone.
    • Temperatur (temperature, feelsLikeTemperature, heatIndex oder täglich maxTemperature, minTemperature, feelsLikeMaxTemperature, feelsLikeMinTemperature, maxHeatIndex).
    • weatherCondition, precipitation, wind, airPressure, relativeHumidity, uvIndex, thunderstormProbability, cloudCover, und tägliche sunEvents und moonEvents. Die Zeiten für Sonnenaufgang, Sonnenuntergang, Mondaufgang und Monduntergang sind UTC-Zeitstempel.
    • attribution: Die Quellenangabe, die Sie mit den Wetterdaten anzeigen müssen.
  • airQuality: Wird ausgefüllt, wenn AIR_QUALITY angefordert wird:
    • hourlyResults[]: Enthält einen Eintrag für aktuelle oder einstündige Abfragen oder bis zu 24 Einträge für den gesamten lokalen Tag (00:00 bis 23:00), wenn nur date festgelegt ist. Wenn date der aktuelle Tag ist und hour weggelassen wird, enthalten die Einträge die früheren Stunden des aktuellen Tages, die aktuelle Stunde und die verbleibenden Prognosestunden. Jeder Eintrag enthält:
      • dateTime: Das lokale Datum und die lokale Uhrzeit (year, month, day, hours, minutes, seconds und utcOffset) in der Zeitzone des Standorts.
      • indexes[]: Universeller LQI und, falls verfügbar, der lokale LQI (displayName, value, valueDisplay, category und dominantPollutant).
      • pollutants[]: Wird ausgefüllt, wenn include_pollutant_concentration true ist (displayName, fullName, concentration in ppb oder µg/m³ und additionalInfo mit Emission sources und Gesundheit effects).
      • healthRecommendations: Anleitung für generalPopulation, elderly, lungDiseasePopulation, heartDiseasePopulation, athletes, pregnantWomen und children.
    • attribution: Die Quellenangabe, die Sie mit den Luftqualitätsdaten anzeigen müssen.
  • pollen: Wird ausgefüllt, wenn POLLEN angefordert wird:
    • dailyForecast: Die Pollenflugvorhersage für die angeforderte date:
      • date: Das Datum der Vorhersage im bürgerlichen Kalender.
      • categories[]: Allgemeine Allergenkategorien (Tree, Grass und Weed), jeweils mit displayName, inSeason, Universal Pollen Index index (Skala von 0 bis 5, category und description) und healthRecommendations[].
      • plantSpecies[]: Bestimmte allergene Pflanzenarten (z. B. Birke, Beifuß-Ambrosie oder Sicheltanne), jeweils mit code, displayName, botanischem family, inSeason, Universal Pollen Index index, typischer Blütezeit season und crossReactions.
    • attribution: Die Zuordnung, die Sie mit den Pollendaten anzeigen müssen.

Teilweise Verfügbarkeit von Funktionen

Wenn eine Anfrage mehrere Funktionen enthält, wird jede Funktion unabhängig voneinander ausgewertet und abgerufen. Wenn eine Funktion für den angeforderten Standort nicht verfügbar ist, außerhalb des unterstützten Zeitraums liegt oder vorübergehend fehlschlägt, während mindestens eine andere Funktion erfolgreich ist, werden in der Antwort die verfügbaren Funktionscontainer zurückgegeben und der nicht verfügbare oder fehlgeschlagene Container wird weggelassen. Die Anfrage schlägt nur dann mit einem Fehler fehl, wenn alle angeforderten Funktionen fehlschlagen.

Ausführliche Informationen zu den Feldern finden Sie in der lookup_weather-Referenz.

Abrechnung und Kontingente

Jede lookup_weather-Anfrage ist ein abrechenbares Ereignis, auch wenn capabilities zwei oder drei Umgebungsbereiche im selben Aufruf anfordert:

  • Eine Anfrage wird gemäß der höchsten SKU-Stufe der Funktionen abgerechnet, die erfolgreich ausgeführt und in der Antwort zurückgegeben werden:
    • Wenn die Antwort pollen oder historische airQuality (ein date vor dem heutigen Tag oder ein vergangenes hour in der Zeitzone des Standorts) enthält, wird die Anfrage gemäß der Maps Grounding Pro-SKU abgerechnet. Wenn Sie sowohl POLLEN als auch historische AIR_QUALITY in einem Aufruf anfordern, wird dies weiterhin als ein abrechenbares Pro-Ereignis gezählt.
    • Andernfalls wird die Anfrage über die Maps Grounding Essentials-SKU abgerechnet.
  • Wenn eine Pro-Funktion in einer Anfrage mit mehreren Funktionen weggelassen wird, weil sie für den Standort nicht verfügbar ist, außerhalb des unterstützten Zeitraums liegt oder vorübergehend fehlschlägt, und in der Antwort nur Essentials-Funktionen zurückgegeben werden, wird die Anfrage unter der Essentials-SKU abgerechnet.

Das lookup_weather-Kontingent beträgt 300 Abfragen pro Minute für jedes Projekt, die von beiden SKUs gemeinsam genutzt werden. Informationen zu den Preisen finden Sie in der Hauptpreistabelle und in der Preistabelle für Indien.