Hava durumuna bakma

lookup_weather aracı, LLM'nin bir konumun hava durumu, hava kalitesi ve polen gibi çevre koşullarını almasına olanak tanır. Tek bir istek; bir yer kimliği, adres veya enlem/boylam koordinatları için bir, iki veya üç çevresel özelliği sorgulayabilir.

Yalnızca hava durumunu veya mevcut ve tahmini hava kalitesini sorgulayan istekler, Maps Grounding Essentials SKU'su kapsamında faturalandırılır. Pro, günlük polen tahminlerini ve son 30 güne ait geçmiş hava kalitesi verilerini ekler.

lookup_weather aracını MCP sunucusu üzerinden veya lookupWeather REST yöntemi olarak çağırabilirsiniz. Bu sayfada ortam özellikleri, istek seçenekleri, Pro seçenekleri, yanıt yapısı ve faturalandırma kuralları açıklanmaktadır. Şemaların tamamı için lookup_weather MCP referansına ve lookupWeather REST referansına bakın.

Yetenekler ve zaman dilimleri

Döndürülecek ortam alanlarını (WEATHER, AIR_QUALITY, POLLEN) seçmek için capabilities dizisini kullanın. weather_options, air_quality_options veya language_code değerlerini ayarladığınızda capabilities gereklidir. capabilities, weather_options, air_quality_options ve language_code parametrelerini atlarsanız lookup_weather, eski hava durumu modunda çalışır ve düz üst düzey hava durumu alanları döndürür.

Tüm date ve hour değerleri, istenen konumun yerel saat diliminde değerlendirilir. Aşağıdaki tabloda, her bir özellik için desteklenen zaman aralıkları ve SKU'lar özetlenmiştir:

Kapasite Mevcut koşullar (date ve hour atlandı) Geçmiş koşullar Tahmin koşulları SKU
WEATHER Şu anki hava durumu Geçmişte 24 saate kadar (hem date hem de hour gereklidir; hour olmadan geçmiş date desteklenmez) hour ayarlandığında 240 saate (10 gün) kadar saatlik tahmin veya yalnızca date ayarlandığında 10 güne kadar günlük tahmin Essentials
AIR_QUALITY Saatlik hava kalitesi date ve hour ayarlandığında tek bir saat için geçmişte 720 saate (30 gün) kadar veya yalnızca date ayarlandığında bugünden 29 gün öncesine kadar (24 saatlik girişlere kadar) date ve hour ayarlandığında gelecekteki 96 saate (4 gün) kadar tek bir saat için veya yalnızca date ayarlandığında bugünden itibaren 3 gün sonrasına kadar (24 saate kadar giriş) Mevcut, bugünün tam günü ve tahmin için temel bilgiler. Yanıtta döndürüldüğünde bugünden önceki bir date veya geçmişteki bir hour için Pro
POLLEN Geçerli günün günlük polen tahmini Desteklenmiyor (INVALID_ARGUMENT hatası döndürür) Bugünden sonraki 4 güne kadar günlük polen tahmini, bugün dahil 5 gün için (hour polen için yoksayılır) Yanıtta döndürüldüğünde Pro

AIR_QUALITY için 720 saatlik geçmişten 96 saatlik tahmin penceresine kadar olan süre, geçerli saate sabitlenir. Tam gün istekleri (hour olmadan date), yerel saatle 00:00 ile 23:00 arasını kapsar ve bu aralığa sığmalıdır. Pratikte bu, bugünden 29 gün öncesinden bugünden üç gün sonrasına kadar olan süreyi kapsar.

Bir istek birden fazla özellik içerdiğinde her özelliğin zaman aralığı bağımsız olarak değerlendirilir. İstenen date ve hour, istenen en az bir özellik için aralık içindeyse yanıt, desteklenen özellik kapsayıcılarını döndürür ve zaman aralığı desteklenmeyen özellikleri atlar. Örneğin, son 30 gün içindeki geçmiş bir tarih için AIR_QUALITY ve POLLEN istenirken airQuality döndürülür ve pollen atlanır. date veya hour, istenen her özelliğin desteklenen aralığının dışındaysa istek bir INVALID_ARGUMENT hatası döndürür.

İstek seçenekleri

LLM, aracı çağırırken kullanıcının isteğine ve aracın açıklamasına göre bu seçenekleri ayarlar. Kendi talimatlarınızla modelin hangi seçenekleri kullanacağını etkileyebilirsiniz. Pro kullanımını kontrol etme başlıklı makaleyi inceleyin.

Aşağıdaki tabloda lookup_weather için istek seçenekleri açıklanmaktadır:

Seçenek Açıklama
location Zorunlu. Sorgulanacak konum. address (kullanıcıların okuyabileceği bir adres, şehir veya önemli nokta adı), place_id ya da lat_lng (latitude ve longitude) olarak belirtilir.
capabilities İsteğe bağlıdır. WEATHER, AIR_QUALITY ve POLLEN değerlerinden biri veya daha fazlası. Yinelenen değerler tekilleştirilir. weather_options, air_quality_options veya language_code ayarlanırken gereklidir. capabilities ve bu seçeneklerin tümü atlandığında eski düz alan hava durumu yanıtını döndürür.
date İsteğe bağlıdır. İstenen konumdaki yerel sivil tarih (year, month, day). Şu anki koşullar için date ve hour değerlerini atlayın.
hour İsteğe bağlıdır. İstenen konumdaki yerel saat (0 - 23). date değerinin ayarlanması gerekir. date olmadan hour ayarlanırsa INVALID_ARGUMENT hatası döndürülür.
language_code İsteğe bağlıdır. Yanıttaki yerelleştirilmiş metnin BCP-47 dil kodu (ör. en, ja veya fr-CA). Varsayılan değer en'dir.
weather_options.units_system İsteğe bağlıdır. Hava durumu değerleri için birim sistemi: METRIC (varsayılan; santigrat, kilometre/saat, milimetre) veya IMPERIAL (fahrenhayt, mil/saat, inç). WEATHER istenmezse yoksayılır.
air_quality_options.include_pollutant_concentration İsteğe bağlıdır. true, airQuality.hourlyResults[].pollutants[] ölçülen kirletici konsantrasyonlarını, emisyon kaynaklarını ve sağlık üzerindeki etkileri içerir. Varsayılan değer false'dir. AIR_QUALITY istenmezse yoksayılır.
air_quality_options.index_region_code İsteğe bağlıdır. Evrensel HKİ (UHKİ) ile birlikte yerel bir Hava Kalitesi İndeksi (HKİ) ölçeği seçmek için kullanılan iki harfli ISO 3166-1 alfa-2 ülke veya bölge kodu (örneğin, US, FR veya CN). Varsayılan olarak, istenen konumun bölgesine ayarlanır. AIR_QUALITY istenmezse yoksayılır.

Pro seçenekleri

Maps Grounding Pro SKU'sunu seçmek için iki seçenek vardır. Yanıtta her iki seçenek de döndürüldüğünde istek, Pro SKU kapsamında faturalandırılır. Çoklu özellik faturalandırma kuralları için Faturalandırma ve kotalar başlıklı makaleyi inceleyin. Aşağıdaki tabloda Pro seçenekleri açıklanmaktadır:

Pro seçeneği Ne zaman kullanılır?
capabilities POLLEN Kullanıcı; polen seviyeleri, mevsimsel alerjiler, ağaç, çim veya yabani ot polenleri ya da belirli alerjen bitki türleri hakkında sorular soruyor.
capabilities içinde, bugünden önce date veya geçmişte hour olan AIR_QUALITY Kullanıcı, konumun saat diliminde son 30 gün içindeki geçmiş hava kalitesi, duman veya kirlilik hakkında soru soruyor.

Diğer tüm lookup_weather istekleri, aşağıdakiler de dahil olmak üzere Essentials SKU'su kapsamında faturalandırılır:

  • Tüm WEATHER istekleri (mevcut, 24 saatlik geçmiş ve 10 günlük saatlik veya günlük tahminler).
  • Mevcut, tam gün bugün (date, hour olmadan bugüne ayarlanır) ve tahmin AIR_QUALITY istekleri (include_pollutant_concentration değerini true olarak ayarlayan veya index_region_code değerini belirten istekler dahil).

Örnek

Aşağıdaki MCP isteği, Tokyo'daki mevcut hava durumunu, hava kalitesini (kirletici konsantrasyonlarıyla birlikte) ve bugünün polen tahminini sorar. capabilities, POLLEN içerdiğinden istek, Pro SKU'su kapsamında faturalandırılır:

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

Aşağıdaki örnekte, aynı istek lookupWeather REST yöntemine gönderilmektedir:

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 kısmını API anahtarınızla değiştirin.

Yanıt

Bir istek capabilities değerini belirttiğinde yanıt, istenen her özellik için alana özgü kapsayıcıları konum meta verileriyle birlikte doldurur:

  • returnedLocation: Çevre verileri için çözümlenen konum (giriş location türüyle eşleşen address, placeId veya latLng).
  • timeZone: Konum için çözümlenen IANA saat dilimi tanımlayıcısı (ör. "America/Los_Angeles" veya "Asia/Tokyo").
  • weather: WEATHER istendiğinde doldurulur:
    • dateTime (mevcut ve saatlik sorgular için), UTC zaman damgası olarak veya date (günlük tahmin sorguları için). Yerel saatleri göstermek için dateTime değerini timeZone alanıyla dönüştürün.
    • Sıcaklık (temperature, feelsLikeTemperature, heatIndex veya günlük maxTemperature, minTemperature, feelsLikeMaxTemperature, feelsLikeMinTemperature, maxHeatIndex).
    • weatherCondition, precipitation, wind, airPressure, relativeHumidity, uvIndex, thunderstormProbability, cloudCover, ve günlük sunEvents ve moonEvents. Gün doğumu, gün batımı, ayın doğuşu ve ayın batışı saatleri UTC zaman damgalarıdır.
    • attribution: Hava durumu verileriyle birlikte göstermeniz gereken ilişkilendirme.
  • airQuality: AIR_QUALITY istendiğinde doldurulur:
    • hourlyResults[]: Mevcut veya tek saatlik sorgular için bir giriş ya da yalnızca date ayarlandığında tüm yerel günü (00:00 - 23:00) kapsayan en fazla 24 giriş içerir. date bugün olduğunda ve hour atlandığında girişler, bugünün önceki geçmiş saatlerini, geçerli saati ve kalan tahmin saatlerini birleştirir. Her giriş şunları içerir:
      • dateTime: Konumun saat dilimindeki yerel sivil tarih ve saat (year, month, day, hours, minutes, seconds ve utcOffset).
      • indexes[]: Evrensel HKİ ve varsa yerel HKİ (displayName, value, valueDisplay, category ve dominantPollutant).
      • pollutants[]: include_pollutant_concentration, true olduğunda doldurulur (ppb veya µg/m³'da displayName, fullName, concentration ve emisyon sources ve sağlık effects ile additionalInfo).
      • healthRecommendations: generalPopulation, elderly, lungDiseasePopulation, heartDiseasePopulation, athletes, pregnantWomen ve children için rehberlik.
    • attribution: Hava kalitesi verileriyle birlikte göstermeniz gereken ilişkilendirme.
  • pollen: POLLEN istendiğinde doldurulur:
    • dailyForecast: İstenen date için polen tahmini:
      • date: : Tahminin sivil takvim tarihi.
      • categories[]: Her biri displayName, inSeason, Evrensel Polen İndeksi index (0-5 ölçeği, category ve description) ve healthRecommendations[] içeren geniş alerjen kategorileri (Tree, Grass ve Weed).
      • plantSpecies[]: Her biri code, displayName, botanik family, inSeason, Evrensel Polen İndeksi index, tipik çiçeklenme season ve crossReactions içeren belirli alerjen bitki türleri (ör. huş ağacı, yakup otu veya Japon sediri).
    • attribution: Polen verileriyle birlikte göstermeniz gereken ilişkilendirme.

Özelliklerin kısmi kullanılabilirliği

Bir istek birden fazla özellik içerdiğinde her özellik bağımsız olarak değerlendirilir ve getirilir. İstenen konum için bir özellik kullanılamıyorsa, desteklenen zaman aralığının dışındaysa veya en az bir özellik başarılı olurken geçici olarak başarısız oluyorsa yanıt, kullanılabilir özellik kapsayıcılarını döndürür ve kullanılamayan veya başarısız olan kapsayıcıyı atlar. İstek, yalnızca istenen her özellik başarısız olursa hatayla başarısız olur.

Alanlarla ilgili tüm ayrıntılar için lookup_weather referansına bakın.

Faturalandırma ve kotalar

capabilities aynı çağrıda iki veya üç çevresel alan istese bile her lookup_weather isteği, faturalandırılabilir bir etkinliktir:

  • Bir istek, başarılı olan ve yanıtta döndürülen özellikler arasında en yüksek SKU katmanına göre faturalandırılır:
    • Yanıt, pollen veya geçmişe ait airQuality (konumun saat diliminde bugünden önceki bir date veya geçmişteki bir hour) içeriyorsa istek, Maps Grounding Pro SKU'su kapsamında faturalandırılır. Tek bir çağrıda hem POLLEN hem de geçmiş AIR_QUALITY verilerini istemek, bir Pro faturalandırılabilir etkinlik olarak sayılır.
    • Aksi takdirde istek, Maps Grounding Essentials SKU'su kapsamında faturalandırılır.
  • Çoklu özellik isteğinde bir Pro özelliği atlanırsa (konum için kullanılamaması, desteklenen zaman aralığının dışında olması veya geçici olarak başarısız olması nedeniyle) ve yanıtta yalnızca Essentials özellikleri döndürülürse istek, Essentials SKU'su kapsamında faturalandırılır.

lookup_weather kotası, her iki SKU tarafından paylaşılan her proje için dakikada 300 sorgudur. Fiyatlandırma için Ana fiyatlandırma tablosu ve Hindistan fiyatlandırma tablosu'na bakın.