Sprawdź pogodę

Narzędzie lookup_weather umożliwia LLM pobieranie informacji o warunkach środowiskowych w danej lokalizacji: pogodzie, jakości powietrza i stężeniu pyłków. Pojedyncze żądanie może dotyczyć 1, 2 lub wszystkich 3 funkcji środowiskowych dla identyfikatora miejsca, adresu lub współrzędnych geograficznych.

Żądania, które dotyczą tylko pogody lub bieżącej i prognozowanej jakości powietrza, są rozliczane w ramach kodu SKU Maps Grounding Essentials. Wersja Pro zawiera codzienne prognozy pylenia i historyczne dane o jakości powietrza z ostatnich 30 dni.

Możesz wywołać lookup_weather przez serwer MCP lub jako metodę REST lookupWeather. Na tej stronie opisano możliwości środowiska, opcje żądań, opcje Pro, strukturę odpowiedzi i zasady rozliczeń. Pełne schematy znajdziesz w dokumentacji MCP lookup_weather i dokumentacji interfejsu REST lookupWeather.

Możliwości i horyzonty czasowe

Użyj tablicy capabilities, aby wybrać domeny środowiskowe, które mają zostać zwrócone (WEATHER, AIR_QUALITY, POLLEN). Parametr capabilities jest wymagany, gdy ustawisz weather_options, air_quality_options lub language_code. Jeśli pominiesz capabilities, weather_options, air_quality_options i language_code, lookup_weather będzie działać w starszym trybie pogodowym i zwracać płaskie pola pogodowe najwyższego poziomu.

Wszystkie wartości date i hour są oceniane w lokalnej strefie czasowej żądanej lokalizacji. W tabeli poniżej znajdziesz podsumowanie obsługiwanych zakresów czasu i SKU dla każdej funkcji:

Możliwości Aktualne warunki (pominięto date i hour) Warunki w przeszłości Prognoza warunków SKU
WEATHER Aktualna pogoda Do 24 godzin wstecz (wymaga zarówno date, jak i hour; date bez hour nie jest obsługiwane) Prognoza godzinowa na maksymalnie 240 godzin (10 dni), gdy ustawiona jest wartość hour, lub prognoza dzienna na maksymalnie 10 dni, gdy ustawiona jest tylko wartość date. Essentials
AIR_QUALITY Bieżąca jakość powietrza co godzinę Do 720 godzin (30 dni) wstecz w przypadku pojedynczej godziny, gdy ustawione są parametry date i hour, lub do 29 dni przed dzisiejszym dniem (do 24 wpisów godzinowych), gdy ustawiony jest tylko parametr date. Do 96 godzin (4 dni) w przyszłość w przypadku pojedynczej godziny, gdy ustawione są parametry date i hour, lub od dzisiaj do 3 dni po dzisiejszym dniu (do 24 wpisów godzinowych), gdy ustawiony jest tylko parametr date Podstawowe informacje o bieżącej pogodzie, prognozie na cały dzień i prognozie na przyszłość. Pro dla date przed dzisiejszym dniem lub poprzedniego hour, gdy zostanie zwrócony w odpowiedzi.
POLLEN Prognoza pylenia na bieżący dzień Nieobsługiwane (zwraca błąd INVALID_ARGUMENT) Dzienna prognoza stężenia pyłków do 4 dni po dzisiejszym dniu, na 5 dni, w tym dzisiaj (w przypadku pyłków parametr hour jest ignorowany) Pro, gdy jest zwracany w odpowiedzi.

W przypadku AIR_QUALITY okno prognozy obejmujące okres od 720 godzin wstecz do 96 godzin do przodu jest zakotwiczone w bieżącej godzinie. Prośby o cały dzień (date bez hour) obejmują okres od 00:00 do 23:00 czasu lokalnego i muszą mieścić się w tym przedziale – w praktyce od 29 dni przed dzisiejszą datą do 3 dni po dzisiejszej dacie.

Jeśli żądanie zawiera kilka funkcji, horyzont czasowy każdej z nich jest oceniany niezależnie. Jeśli żądane parametry date i hour mieszczą się w zakresie co najmniej jednej żądanej funkcji, odpowiedź zwraca kontenery obsługiwanych funkcji i pomija wszystkie funkcje, których zakres czasu nie jest obsługiwany. Jeśli na przykład poprosisz o AIR_QUALITY i POLLEN z datą z przeszłości w ciągu 30 dni, otrzymasz airQuality, a pollen zostanie pominięty. Jeśli wartość date lub hour wykracza poza obsługiwany zakres dowolnej z żądanych funkcji, żądanie zwraca błąd INVALID_ARGUMENT.

Opcje żądania

Model LLM ustawia te opcje, gdy wywołuje narzędzie, na podstawie prośby użytkownika i opisu narzędzia. Możesz wpływać na to, których opcji używa model, za pomocą własnych instrukcji. Więcej informacji znajdziesz w artykule o kontrolowaniu korzystania z wersji Pro.

W tabeli poniżej opisano opcje żądania dla lookup_weather:

Opcja Opis
location Wymagane. Lokalizacja, której dotyczy zapytanie, określona jako address (zrozumiały dla człowieka adres, miasto lub nazwa punktu orientacyjnego), place_id lub lat_lng (latitude i longitude).
capabilities Opcjonalnie: Co najmniej 1 wartość z tych: WEATHER, AIR_QUALITY i POLLEN. Zduplikowane wartości są usuwane. Wymagane, gdy ustawiasz weather_options, air_quality_options lub language_code. Jeśli capabilities i wszystkie te opcje zostaną pominięte, zwracana jest starsza odpowiedź dotycząca pogody w formie płaskiego pola.
date Opcjonalnie: Lokalna data cywilna (year, month, day) w żądanej lokalizacji. Pomiń date i hour w przypadku aktualnych warunków.
hour Opcjonalnie: Godzina lokalna (od 0 do 23) w żądanej lokalizacji. Wymaga ustawienia date. Ustawienie hour bez date zwraca błąd INVALID_ARGUMENT.
language_code Opcjonalnie: Kod języka w standardzie BCP-47 dla zlokalizowanego tekstu w odpowiedzi, np. en, ja lub fr-CA. Domyślna wartość to en.
weather_options.units_system Opcjonalnie: System jednostek dla wartości pogodowych: METRIC (domyślny; stopnie Celsjusza, kilometry na godzinę, milimetry) lub IMPERIAL (stopnie Fahrenheita, mile na godzinę, cale). Jeśli nie żądasz WEATHER, ta właściwość jest ignorowana.
air_quality_options.include_pollutant_concentration Opcjonalnie: Gdy true, airQuality.hourlyResults[].pollutants[] zawiera zmierzone stężenia zanieczyszczeń, źródła emisji i wpływ na zdrowie. Domyślna wartość to false. Jeśli nie żądasz AIR_QUALITY, ta właściwość jest ignorowana.
air_quality_options.index_region_code Opcjonalnie: Dwuliterowy kod kraju lub regionu w formacie ISO 3166-1 alfa-2, np. US, FR lub CN, używany do wyboru lokalnej skali indeksu jakości powietrza (AQI) obok uniwersalnego indeksu jakości powietrza (UAQI). Domyślnie jest to region żądanej lokalizacji. Jeśli nie żądasz AIR_QUALITY, ta właściwość jest ignorowana.

Opcje wersji Pro

Wybierz Maps Grounding Pro SKU. Żądanie jest rozliczane w ramach SKU Pro, gdy w odpowiedzi zostanie zwrócona jedna z tych opcji. Informacje o regułach rozliczeniowych dotyczących wielu funkcji znajdziesz w artykule Płatności i limity. Poniższa tabela zawiera opis opcji Pro:

Opcja Pro Kiedy z niego korzystać
POLLEN w: capabilities Użytkownik pyta o poziom pyłków, alergie sezonowe, pyłki drzew, traw lub chwastów albo o konkretne gatunki roślin alergizujących.
AIR_QUALITY w capabilities z date przed dzisiaj lub wcześniejszym hour Użytkownik pyta o historyczne dane dotyczące jakości powietrza, dymu lub zanieczyszczeń w ciągu ostatnich 30 dni w strefie czasowej lokalizacji.

Wszystkie pozostałe żądania lookup_weather są rozliczane w ramach kodu SKU Essentials, w tym:

  • Wszystkie żądania dotyczące WEATHER (bieżące, historia z 24 godzin oraz prognozy godzinowe lub dzienne na 10 dni).
  • Bieżące, całodniowe żądania z dzisiaj (date ustawione na dzisiaj bez hour) i prognozowane żądania AIR_QUALITY, w tym żądania, które ustawiają include_pollutant_concentration na true lub określają index_region_code.

Przykład

To żądanie MCP dotyczy aktualnej pogody, jakości powietrza (ze stężeniem zanieczyszczeń) i dzisiejszej prognozy pylenia w Tokio. Ponieważ capabilities zawiera POLLEN, żądanie jest rozliczane w ramach kodu 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
}

Ten przykładowy kod wysyła to samo żądanie do metody 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"

Zastąp API_KEY swoim kluczem interfejsu API.

Odpowiedź

Gdy żądanie określa capabilities, odpowiedź wypełnia kontenery dla poszczególnych domen dla każdej żądanej funkcji wraz z metadanymi lokalizacji:

  • returnedLocation: określona lokalizacja (address, placeId lub latLng, odpowiadająca typowi danych wejściowych location) dla danych środowiskowych.
  • timeZone: rozpoznany identyfikator strefy czasowej IANA dla lokalizacji, np. "America/Los_Angeles" lub "Asia/Tokyo".
  • weather: wypełniane, gdy żądany jest parametr WEATHER:
    • dateTime (w przypadku zapytań o bieżącą i godzinową prognozę) jako sygnatura czasowa UTC lub date (w przypadku zapytań o prognozę dzienną). Aby wyświetlać czas lokalny, przekonwertuj dateTime za pomocą pola timeZone.
    • Temperatura (temperature, feelsLikeTemperature, heatIndex lub dzienna maxTemperature, minTemperature, feelsLikeMaxTemperature, feelsLikeMinTemperature, maxHeatIndex).
    • weatherCondition, precipitation, wind, airPressure, relativeHumidity, uvIndex, thunderstormProbability, cloudCover, oraz codzienne sunEvents i moonEvents. Godziny wschodu i zachodu słońca oraz wschodu i zachodu księżyca są podawane w formacie sygnatur czasowych UTC.
    • attribution: atrybucja, którą musisz wyświetlać wraz z danymi o pogodzie.
  • airQuality: wypełniane, gdy żądany jest parametr AIR_QUALITY:
    • hourlyResults[]: zawiera 1 wpis dotyczący bieżących lub jednogodzinnych zapytań albo maksymalnie 24 wpisy obejmujące cały dzień lokalny (00:00 do 23:00), gdy ustawiony jest tylko parametr date. Gdy date to dzisiaj, a parametr hour jest pominięty, wpisy łączą wcześniejsze godziny historyczne z dzisiaj, bieżącą godzinę i pozostałe godziny prognozy. Każdy wpis zawiera:
      • dateTime: lokalna data i godzina (year, month, day, hours, minutes, seconds i utcOffset) w strefie czasowej lokalizacji.
      • indexes[]: uniwersalny wskaźnik AQI oraz, jeśli jest dostępny, lokalny wskaźnik AQI (displayName, value, valueDisplay, category i dominantPollutant).
      • pollutants[]: wypełniane, gdy include_pollutant_concentration to true (displayName, fullName, concentration w ppb lub µg/m³ oraz additionalInfo z emisją sources i stanem effects).
      • healthRecommendations: wskazówki dotyczące generalPopulation, elderly, lungDiseasePopulation, heartDiseasePopulation, athletes, pregnantWomen i children.
    • attribution: atrybucja, którą musisz wyświetlać wraz z danymi o jakości powietrza.
  • pollen: wypełniane, gdy żądany jest parametr POLLEN:
    • dailyForecast: prognoza pylenia dla lokalizacji date:
      • date: data prognozy w kalendarzu cywilnym.
      • categories[]: ogólne kategorie alergenów (Tree, Grass i Weed), z których każda zawiera displayName, inSeason, uniwersalny indeks pyłków index (skala od 0 do 5, category i description) oraz healthRecommendations[].
      • plantSpecies[]: konkretne gatunki roślin alergizujących (takich jak brzoza, ambrozja czy kryptomeria japońska), z których każdy ma code, displayName, botaniczny family, inSeason, uniwersalny indeks pylenia index, typowy okres kwitnienia season i crossReactions.
    • attribution: atrybucja, którą musisz wyświetlać wraz z danymi o pyleniu.

Częściowa dostępność funkcji

Jeśli żądanie zawiera kilka funkcji, każda z nich jest oceniana i pobierana niezależnie. Jeśli jedna z funkcji jest niedostępna w żądanej lokalizacji, poza obsługiwanym zakresem czasu lub tymczasowo nie działa, a co najmniej jedna inna funkcja działa, odpowiedź zwraca kontenery dostępnych funkcji i pomija niedostępny lub uszkodzony kontener. Żądanie nie powiedzie się i zostanie wyświetlony błąd tylko wtedy, gdy nie uda się zrealizować żadnej z żądanych funkcji.

Szczegółowe informacje o polach znajdziesz w dokumentacji lookup_weather.

Rozliczenia i limity

Każde żądanie lookup_weather to jedno zdarzenie podlegające rozliczeniu, nawet jeśli capabilities żąda 2 lub 3 domen środowiskowych w tym samym wywołaniu:

  • Żądanie jest rozliczane według najwyższego poziomu SKU spośród funkcji, które zostały pomyślnie wykonane i zwrócone w odpowiedzi:
    • Jeśli odpowiedź zawiera pollen lub historyczne airQuality (date przed dzisiejszym dniem lub wcześniejszą hour w strefie czasowej lokalizacji), żądanie jest rozliczane w ramach SKU Maps Grounding Pro. Żądanie zarówno POLLEN, jak i historycznych danych AIR_QUALITY w jednym wywołaniu nadal liczy się jako jedno zdarzenie podlegające opłacie w ramach wersji Pro.
    • W przeciwnym razie żądanie jest rozliczane w ramach kodu SKU Maps Grounding Essentials.
  • Jeśli w żądaniu dotyczącym wielu funkcji pominięto funkcję Pro, ponieważ jest ona niedostępna w danej lokalizacji, poza obsługiwanym zakresem czasu lub tymczasowo nie działa, a w odpowiedzi zwracane są tylko funkcje Essentials, żądanie jest rozliczane według SKU Essentials.

Limit lookup_weather wynosi 300 zapytań na minutę w przypadku każdego projektu i jest współdzielony przez oba kody SKU. Ceny znajdziesz w głównej tabeli cen i tabeli cen w Indiach.