Gunakan lebih banyak kemampuan alat agen Maps Experience dengan SKU Pro. Pelajari Pro

Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Mencari info cuaca

Alat lookup_weather memungkinkan LLM mengambil kondisi lingkungan untuk suatu lokasi: cuaca, kualitas udara, dan serbuk sari. Satu permintaan dapat mengkueri satu, dua, atau ketiga kemampuan lingkungan untuk ID tempat, alamat, atau koordinat lintang/bujur.

Permintaan yang hanya mengkueri cuaca atau kualitas udara saat ini dan prakiraan akan ditagih berdasarkan SKU Maps Grounding Essentials. Pro menambahkan perkiraan serbuk sari harian dan kualitas udara historis hingga 30 hari terakhir.

Anda dapat memanggil lookup_weather melalui server MCP atau sebagai metode REST lookupWeather. Halaman ini menjelaskan kemampuan lingkungan, opsi permintaan, opsi Pro, struktur respons, dan aturan penagihan. Untuk skema lengkapnya, lihat referensi MCP lookup_weather dan referensi REST lookupWeather.

Kemampuan dan rentang waktu

Gunakan array capabilities untuk memilih domain lingkungan yang akan ditampilkan (WEATHER, AIR_QUALITY, POLLEN). capabilities diperlukan setiap kali Anda menetapkan weather_options, air_quality_options, atau language_code. Jika Anda menghilangkan capabilities, weather_options, air_quality_options, dan language_code, lookup_weather akan berjalan dalam mode cuaca lama dan menampilkan kolom cuaca tingkat teratas yang datar.

Semua nilai date dan hour dievaluasi dalam zona waktu lokal lokasi yang diminta. Tabel berikut merangkum rentang waktu dan SKU yang didukung untuk setiap kemampuan:

Kemampuan	Kondisi saat ini (`date` dan `hour` dihilangkan)	Riwayat kondisi	Kondisi perkiraan	SKU
`WEATHER`	Cuaca saat ini	Hingga 24 jam yang lalu (memerlukan `date` dan `hour`; `date` yang lalu tanpa `hour` tidak didukung)	Perkiraan per jam hingga 240 jam (10 hari) jika `hour` ditetapkan, atau perkiraan harian hingga 10 hari jika hanya `date` yang ditetapkan	Essentials
`AIR_QUALITY`	Kualitas udara per jam saat ini	Hingga 720 jam (30 hari) sebelumnya untuk satu jam saat `date` dan `hour` ditetapkan, atau hingga 29 hari sebelum hari ini (hingga 24 entri per jam) jika hanya `date` yang ditetapkan	Hingga 96 jam (4 hari) ke depan untuk satu jam saat `date` dan `hour` ditetapkan, atau hari ini hingga 3 hari setelah hari ini (hingga 24 entri per jam) jika hanya `date` yang ditetapkan	Informasi penting untuk cuaca saat ini, sepanjang hari ini, dan prakiraan cuaca. Pro untuk `date` sebelum hari ini atau `hour` sebelumnya saat ditampilkan dalam respons
`POLLEN`	Prakiraan serbuk sari harian untuk hari ini	Tidak didukung (menampilkan error `INVALID_ARGUMENT`)	Perkiraan serbuk sari harian hingga 4 hari setelah hari ini, selama 5 hari termasuk hari ini (`hour` diabaikan untuk serbuk sari)	Pro saat ditampilkan dalam respons

Untuk AIR_QUALITY, jendela perkiraan 720 jam terakhir hingga 96 jam ke depan dikaitkan ke jam saat ini. Permintaan satu hari penuh (date tanpa hour) mencakup 00:00 hingga 23:00 waktu setempat dan harus sesuai dengan periode tersebut—dalam praktiknya, dari 29 hari sebelum hari ini hingga tiga hari setelah hari ini.

Jika permintaan menyertakan beberapa kemampuan, rentang waktu setiap kemampuan akan dievaluasi secara independen. Jika date dan hour yang diminta berada dalam rentang untuk setidaknya satu kemampuan yang diminta, respons akan menampilkan container kemampuan yang didukung dan menghilangkan kemampuan yang rentang waktunya tidak didukung. Misalnya, meminta AIR_QUALITY dan POLLEN untuk tanggal yang telah berlalu dalam 30 hari akan menampilkan airQuality dan menghilangkan pollen. Permintaan akan menampilkan error INVALID_ARGUMENT jika date atau hour berada di luar rentang yang didukung dari setiap kemampuan yang diminta.

Opsi permintaan

LLM menetapkan opsi ini saat memanggil alat, berdasarkan permintaan pengguna dan deskripsi alat. Anda dapat memengaruhi opsi yang digunakan model dengan petunjuk Anda sendiri; lihat Mengontrol penggunaan Pro.

Tabel berikut menjelaskan opsi permintaan untuk lookup_weather:

Opsi	Deskripsi
`location`	Wajib. Lokasi yang akan dikueri, yang ditentukan sebagai `address` (alamat, kota, atau nama tempat terkenal yang dapat dibaca manusia), `place_id`, atau `lat_lng` (`latitude` dan `longitude`).
`capabilities`	Opsional. Satu atau beberapa nilai dari `WEATHER`, `AIR_QUALITY`, dan `POLLEN`. Nilai duplikat akan dihapus duplikatnya. Wajib diisi saat menetapkan `weather_options`, `air_quality_options`, atau `language_code`. Jika `capabilities` dan semua opsi tersebut dihilangkan, respons cuaca kolom datar lama akan ditampilkan.
`date`	Opsional. Tanggal sipil lokal (`year`, `month`, `day`) di lokasi yang diminta. Hilangkan `date` dan `hour` untuk kondisi saat ini.
`hour`	Opsional. Jam lokal (`0` hingga `23`) di lokasi yang diminta. Memerlukan penetapan `date`. Menetapkan `hour` tanpa `date` akan menampilkan error `INVALID_ARGUMENT`.
`language_code`	Opsional. Kode bahasa BCP-47 untuk teks yang dilokalkan dalam respons, seperti `en`, `ja`, atau `fr-CA`. Defaultnya adalah `en`.
`weather_options.units_system`	Opsional. Sistem satuan untuk nilai cuaca: `METRIC` (default; Celsius, kilometer per jam, milimeter) atau `IMPERIAL` (Fahrenheit, mil per jam, inci). Diabaikan jika `WEATHER` tidak diminta.
`air_quality_options.include_pollutant_concentration`	Opsional. Saat `true`, `airQuality.hourlyResults[].pollutants[]` mencakup konsentrasi polutan yang diukur, sumber emisi, dan dampak kesehatan. Default-nya adalah `false`. Diabaikan jika `AIR_QUALITY` tidak diminta.
`air_quality_options.index_region_code`	Opsional. Kode negara atau wilayah ISO 3166-1 alpha-2 dua huruf—misalnya, `US`, `FR`, atau `CN`—yang digunakan untuk memilih skala Indeks Kualitas Udara (AQI) lokal bersama dengan AQI Universal (UAQI). Default-nya adalah wilayah lokasi yang diminta. Diabaikan jika `AIR_QUALITY` tidak diminta.

Opsi Pro

Dua opsi memilih SKU Maps Grounding Pro. Permintaan akan ditagih berdasarkan SKU Pro jika salah satu opsi ditampilkan dalam respons. Untuk aturan penagihan multi-kemampuan, lihat Penagihan dan kuota. Tabel berikut menjelaskan opsi Pro:

Opsi Pro	Kapan menggunakannya
`POLLEN` di `capabilities`	Pengguna bertanya tentang tingkat serbuk sari, alergi musiman, serbuk sari pohon, rumput, atau gulma, atau spesies tanaman alergenik tertentu.
`AIR_QUALITY` di `capabilities` dengan `date` sebelum hari ini atau `hour` yang lalu	Pengguna bertanya tentang kualitas udara, asap, atau polusi historis selama 30 hari terakhir di zona waktu lokasi.

Semua permintaan lookup_weather lainnya ditagih berdasarkan SKU Essentials, termasuk:

Semua permintaan WEATHER (saat ini, histori 24 jam, dan perkiraan per jam atau harian selama 10 hari).
Permintaan AIR_QUALITY saat ini, sepanjang hari ini (date ditetapkan ke hari ini tanpa hour), dan perkiraan, termasuk permintaan yang menetapkan include_pollutant_concentration ke true atau menentukan index_region_code.

Contoh

Permintaan MCP berikut meminta cuaca saat ini, kualitas udara (dengan konsentrasi polutan), dan perkiraan serbuk sari hari ini di Tokyo. Karena capabilities menyertakan POLLEN, permintaan akan ditagih berdasarkan 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
}

Contoh berikut mengirimkan permintaan yang sama ke metode 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"

Ganti API_KEY dengan kunci API Anda.

Respons

Jika permintaan menentukan capabilities, respons akan mengisi container khusus domain untuk setiap kemampuan yang diminta beserta metadata lokasi:

returnedLocation: Lokasi yang di-resolve (address, placeId, atau latLng, yang cocok dengan jenis location input) untuk data lingkungan.
timeZone: ID zona waktu IANA yang di-resolve untuk lokasi, seperti "America/Los_Angeles" atau "Asia/Tokyo".
weather: Diisi saat WEATHER diminta:
- dateTime (untuk kueri saat ini dan per jam), sebagai stempel waktu UTC, atau date (untuk kueri perkiraan harian). Untuk menampilkan waktu lokal, konversikan dateTime dengan kolom timeZone.
- Suhu (temperature, feelsLikeTemperature, heatIndex, atau maxTemperature, minTemperature, feelsLikeMaxTemperature, feelsLikeMinTemperature, maxHeatIndex harian).
- weatherCondition, precipitation, wind, airPressure, relativeHumidity, uvIndex, thunderstormProbability, cloudCover, serta sunEvents dan moonEvents harian. Waktu matahari terbit, matahari terbenam, bulan terbit, dan bulan terbenam adalah stempel waktu UTC.
- attribution: Atribusi yang harus Anda tampilkan dengan data cuaca.
airQuality: Diisi saat AIR_QUALITY diminta:
- hourlyResults[] 00:0023:00date Jika date adalah hari ini dan hour dihilangkan, entri akan menggabungkan jam historis sebelumnya pada hari ini, jam saat ini, dan jam perkiraan yang tersisa. Setiap entri mencakup:
  - dateTime: Tanggal dan waktu sipil lokal (year, month, day, hours, minutes, seconds, dan utcOffset) di zona waktu lokasi.
  - indexes[]: AQI Universal dan, jika tersedia, AQI lokal (displayName, value, valueDisplay, category, dan dominantPollutant).
  - pollutants[]: Diisi jika include_pollutant_concentration adalah true (displayName, fullName, concentration di ppb atau µg/m³, dan additionalInfo dengan emisi sources dan kesehatan effects).
  - healthRecommendations: Panduan untuk generalPopulation, elderly, lungDiseasePopulation, heartDiseasePopulation, athletes, pregnantWomen, dan children.
- attribution: Atribusi yang harus Anda tampilkan dengan data kualitas udara.
pollen: Diisi saat POLLEN diminta:
- dailyForecast: Prakiraan serbuk sari untuk date yang diminta:
  - date: Tanggal kalender sipil perkiraan.
  - categories[]: Kategori alergen yang luas (Tree, Grass, dan Weed), masing-masing dengan displayName, inSeason, Indeks Serbuk Sari Universal index (skala 0 hingga 5, category, dan description), dan healthRecommendations[].
  - plantSpecies[]: Spesies tanaman alergenik tertentu (seperti Birch, Ragweed, atau Cedar Jepang), masing-masing dengan code, displayName, family botani, inSeason, Indeks Serbuk Sari Universal index, season mekar yang khas, dan crossReactions.
- attribution: Atribusi yang harus Anda tampilkan dengan data serbuk sari.

Ketersediaan parsial di seluruh kemampuan

Jika permintaan menyertakan beberapa kemampuan, setiap kemampuan akan dievaluasi dan diambil secara independen. Jika satu kemampuan tidak tersedia untuk lokasi yang diminta, di luar rentang waktu yang didukung, atau gagal sementara saat setidaknya satu kemampuan lain berhasil, respons akan menampilkan container kemampuan yang tersedia dan menghilangkan container yang tidak tersedia atau gagal. Permintaan akan gagal dengan error hanya jika setiap kemampuan yang diminta gagal.

Untuk mengetahui detail kolom selengkapnya, lihat referensi lookup_weather.

Penagihan dan kuota

Setiap permintaan lookup_weather adalah satu peristiwa yang dapat ditagih, meskipun capabilities meminta dua atau tiga domain lingkungan dalam panggilan yang sama:

Permintaan ditagih berdasarkan tingkat SKU tertinggi di antara kemampuan yang berhasil dan ditampilkan dalam respons:
- Jika respons menyertakan pollen atau airQuality historis (date sebelum hari ini atau hour yang lalu di zona waktu lokasi), permintaan akan ditagih berdasarkan SKU Maps Grounding Pro. Meminta POLLEN dan AIR_QUALITY historis dalam satu panggilan tetap dihitung sebagai satu peristiwa yang dapat ditagih Pro.
- Jika tidak, permintaan akan ditagih berdasarkan SKU Maps Grounding Essentials.
Jika kemampuan Pro dihilangkan dalam permintaan multi-kemampuan—karena tidak tersedia untuk lokasi, di luar rentang waktu yang didukung, atau gagal sementara—dan hanya kemampuan Essentials yang ditampilkan dalam respons, permintaan akan ditagih berdasarkan SKU Essentials.

Kuota lookup_weather adalah 300 kueri per menit untuk setiap project, yang digunakan bersama oleh kedua SKU. Untuk mengetahui harga, lihat Tabel harga utama dan Tabel harga India.