Tra cứu thời tiết

Công cụ lookup_weather cho phép LLM truy xuất các điều kiện môi trường cho một vị trí: thời tiết, chất lượng không khí và phấn hoa. Một yêu cầu có thể truy vấn một, hai hoặc cả ba chức năng môi trường cho một mã địa điểm, địa chỉ hoặc toạ độ vĩ độ/kinh độ.

Những yêu cầu chỉ truy vấn thông tin thời tiết hoặc chất lượng không khí hiện tại và dự báo sẽ được tính phí theo SKU Maps Grounding Essentials. Pro bổ sung thông tin dự báo hằng ngày về phấn hoa và dữ liệu về chất lượng không khí trong quá khứ (tối đa 30 ngày trước).

Bạn có thể gọi lookup_weather thông qua máy chủ MCP hoặc dưới dạng phương thức REST lookupWeather. Trang này mô tả các chức năng về môi trường, lựa chọn yêu cầu, lựa chọn Pro, cấu trúc phản hồi và quy tắc thanh toán. Để xem giản đồ đầy đủ, hãy xem tài liệu tham khảo về MCP lookup_weather và tài liệu tham khảo về REST lookupWeather.

Khả năng và khoảng thời gian

Sử dụng mảng capabilities để chọn miền môi trường cần trả về (WEATHER, AIR_QUALITY, POLLEN). Bạn bắt buộc phải sử dụng capabilities bất cứ khi nào bạn đặt weather_options, air_quality_options hoặc language_code. Nếu bạn bỏ qua capabilities, weather_options, air_quality_options và language_code, thì lookup_weather sẽ chạy ở chế độ thời tiết cũ và trả về các trường thời tiết cấp cao nhất.

Tất cả giá trị date và hour đều được đánh giá theo múi giờ địa phương của vị trí được yêu cầu. Bảng sau đây tóm tắt các phạm vi thời gian và SKU được hỗ trợ cho từng chức năng:

Chức năng Điều kiện hiện tại (bỏ qua date và hour) Tình trạng trước đây Điều kiện dự báo SKU
WEATHER Thời tiết hiện tại Tối đa 24 giờ trước (yêu cầu cả date và hour; không hỗ trợ date trước mà không có hour) Thông tin dự báo hằng giờ lên đến 240 giờ (10 ngày) khi bạn đặt hour hoặc thông tin dự báo hằng ngày lên đến 10 ngày khi bạn chỉ đặt date Essentials
AIR_QUALITY Chất lượng không khí hiện tại theo giờ Tối đa 720 giờ (30 ngày) trong quá khứ cho một giờ khi bạn đặt date và hour, hoặc tối đa 29 ngày trước hôm nay (tối đa 24 mục hằng giờ) khi bạn chỉ đặt date Tối đa 96 giờ (4 ngày) trong tương lai cho một giờ khi bạn đặt date và hour, hoặc từ hôm nay đến 3 ngày sau hôm nay (tối đa 24 mục hằng giờ) khi bạn chỉ đặt date Thông tin thiết yếu về thời tiết hiện tại, cả ngày hôm nay và dự báo. Pro cho date trước hôm nay hoặc hour trong quá khứ khi được trả về trong câu trả lời
POLLEN Thông tin dự báo hằng ngày về phấn hoa của ngày hiện tại Không được hỗ trợ (trả về lỗi INVALID_ARGUMENT) Dự báo phấn hoa hằng ngày trong tối đa 4 ngày sau hôm nay, trong 5 ngày bao gồm cả hôm nay (hour bị bỏ qua đối với phấn hoa) Pro khi được trả về trong phản hồi

Đối với AIR_QUALITY, khoảng thời gian từ 720 giờ trước đến 96 giờ dự báo được neo vào giờ hiện tại. Yêu cầu cho cả ngày (date không có hour) bao gồm 00:00 đến 23:00 theo giờ địa phương và phải nằm trong khoảng thời gian đó – trên thực tế là từ 29 ngày trước hôm nay đến 3 ngày sau hôm nay.

Khi một yêu cầu bao gồm nhiều chức năng, khoảng thời gian của mỗi chức năng sẽ được đánh giá độc lập. Nếu date và hour được yêu cầu nằm trong phạm vi của ít nhất một chức năng được yêu cầu, thì phản hồi sẽ trả về các vùng chứa chức năng được hỗ trợ và bỏ qua mọi chức năng có phạm vi thời gian không được hỗ trợ. Ví dụ: khi bạn yêu cầu AIR_QUALITY và POLLEN cho một ngày trong quá khứ trong vòng 30 ngày, hệ thống sẽ trả về airQuality và bỏ qua pollen. Yêu cầu sẽ trả về lỗi INVALID_ARGUMENT nếu date hoặc hour nằm ngoài phạm vi được hỗ trợ của mọi chức năng được yêu cầu.

Lựa chọn yêu cầu

LLM đặt các tuỳ chọn này khi gọi công cụ, dựa trên yêu cầu của người dùng và nội dung mô tả công cụ. Bạn có thể tác động đến các lựa chọn mà mô hình sử dụng bằng hướng dẫn của riêng bạn; hãy xem phần Kiểm soát việc sử dụng Pro.

Bảng sau đây mô tả các tuỳ chọn yêu cầu cho lookup_weather:

Phương thức Mô tả
location Bắt buộc. Vị trí cần truy vấn, được chỉ định dưới dạng address (địa chỉ, thành phố hoặc tên địa danh mà con người có thể đọc được), place_id hoặc lat_lng (latitude và longitude).
capabilities Không bắt buộc. Một hoặc nhiều giá trị từ WEATHER, AIR_QUALITY và POLLEN. Các giá trị trùng lặp sẽ được loại bỏ. Bắt buộc khi đặt weather_options, air_quality_options hoặc language_code. Khi capabilities và tất cả các tuỳ chọn đó đều bị bỏ qua, hàm này sẽ trả về phản hồi thời tiết dạng phẳng cũ.
date Không bắt buộc. Ngày dương lịch địa phương (year, month, day) tại vị trí được yêu cầu. Bỏ qua date và hour cho điều kiện hiện tại.
hour Không bắt buộc. Giờ địa phương (0 đến 23) tại vị trí được yêu cầu. Yêu cầu phải đặt date. Nếu bạn đặt hour mà không đặt date, hệ thống sẽ trả về lỗi INVALID_ARGUMENT.
language_code Không bắt buộc. Mã ngôn ngữ BCP-47 cho văn bản đã bản địa hoá trong phản hồi, chẳng hạn như en, ja hoặc fr-CA. Giá trị mặc định là en.
weather_options.units_system Không bắt buộc. Hệ đơn vị cho các giá trị thời tiết: METRIC (mặc định; độ C, kilomet/giờ, milimet) hoặc IMPERIAL (độ F, dặm/giờ, inch). Bỏ qua nếu không yêu cầu WEATHER.
air_quality_options.include_pollutant_concentration Không bắt buộc. Khi true, airQuality.hourlyResults[].pollutants[] sẽ bao gồm nồng độ chất gây ô nhiễm đo được, nguồn phát thải và ảnh hưởng đến sức khoẻ. Mặc định là false. Bỏ qua nếu không yêu cầu AIR_QUALITY.
air_quality_options.index_region_code Không bắt buộc. Mã quốc gia hoặc khu vực gồm hai chữ cái theo tiêu chuẩn ISO 3166-1 alpha-2 (ví dụ: US, FR hoặc CN) dùng để chọn thang đo Chỉ số chất lượng không khí (AQI) tại địa phương cùng với Chỉ số chất lượng không khí chung (UAQI). Giá trị mặc định là khu vực của vị trí được yêu cầu. Bỏ qua nếu không yêu cầu AIR_QUALITY.

Lựa chọn chuyên nghiệp

Hai lựa chọn chọn SKU Maps Grounding Pro. Yêu cầu được tính phí theo SKU Pro khi một trong hai lựa chọn được trả về trong phản hồi. Để biết các quy tắc thanh toán cho nhiều chức năng, hãy xem phần Thanh toán và hạn mức. Bảng sau đây mô tả các lựa chọn của gói Pro:

Lựa chọn chuyên nghiệp Trường hợp sử dụng
POLLEN tại capabilities Người dùng hỏi về nồng độ phấn hoa, dị ứng theo mùa, phấn hoa cây, cỏ hoặc cỏ dại, hoặc các loài thực vật gây dị ứng cụ thể.
AIR_QUALITY trong capabilities có date trước hôm nay hoặc hour trước đây Người dùng hỏi về chất lượng không khí, khói hoặc tình trạng ô nhiễm trong quá khứ trong vòng 30 ngày qua theo múi giờ của vị trí đó.

Tất cả các yêu cầu lookup_weather khác đều được tính phí theo SKU Essentials, bao gồm:

  • Tất cả yêu cầu WEATHER (hiện tại, nhật ký 24 giờ và thông tin dự báo hằng giờ hoặc hằng ngày trong 10 ngày).
  • Yêu cầu hiện tại, cả ngày hôm nay (date được đặt thành hôm nay mà không có hour) và dự báo AIR_QUALITY, bao gồm cả những yêu cầu đặt include_pollutant_concentration thành true hoặc chỉ định index_region_code.

Ví dụ

Yêu cầu MCP sau đây yêu cầu thông tin về thời tiết hiện tại, chất lượng không khí (với nồng độ chất gây ô nhiễm) và thông tin dự báo về phấn hoa hôm nay ở Tokyo. Vì capabilities bao gồm POLLEN, nên yêu cầu này được tính phí theo 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
}

Ví dụ sau đây gửi cùng một yêu cầu đến phương thức 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"

Thay thế API_KEY bằng khoá API của bạn.

Phản hồi

Khi một yêu cầu chỉ định capabilities, phản hồi sẽ điền vào các vùng chứa theo miền cụ thể cho từng chức năng được yêu cầu cùng với siêu dữ liệu vị trí:

  • returnedLocation: Vị trí đã phân giải (address, placeId hoặc latLng, khớp với loại location đầu vào) cho dữ liệu môi trường.
  • timeZone: Giá trị nhận dạng múi giờ IANA đã phân giải cho vị trí, chẳng hạn như "America/Los_Angeles" hoặc "Asia/Tokyo".
  • weather: Được điền sẵn khi WEATHER được yêu cầu:
    • dateTime (đối với truy vấn hiện tại và hằng giờ), dưới dạng dấu thời gian UTC hoặc date (đối với truy vấn dự báo hằng ngày). Để hiển thị giờ địa phương, hãy chuyển đổi dateTime bằng trường timeZone.
    • Nhiệt độ (temperature, feelsLikeTemperature, heatIndex hoặc maxTemperature, minTemperature, feelsLikeMaxTemperature, feelsLikeMinTemperature, maxHeatIndex hằng ngày).
    • weatherCondition, precipitation, wind, airPressure, relativeHumidity, uvIndex, thunderstormProbability, cloudCover, sunEvents và moonEvents hằng ngày. Thời gian mặt trời mọc, mặt trời lặn, mặt trăng mọc và mặt trăng lặn là dấu thời gian theo giờ UTC.
    • attribution: Thông tin ghi nhận tác giả mà bạn phải hiển thị cùng với dữ liệu thời tiết.
  • airQuality: Được điền sẵn khi AIR_QUALITY được yêu cầu:
    • hourlyResults[]: Chứa một mục nhập cho các truy vấn hiện tại hoặc một giờ, hoặc tối đa 24 mục nhập bao gồm toàn bộ ngày địa phương (00:00 đến 23:00) khi chỉ đặt date. Khi date là hôm nay và hour bị bỏ qua, các mục nhập sẽ kết hợp giờ trước đó của ngày hôm nay, giờ hiện tại và giờ dự báo còn lại. Mỗi mục nhập bao gồm:
      • dateTime: Ngày và giờ dân sự tại địa phương (year, month, day, hours, minutes, seconds và utcOffset) theo múi giờ của vị trí.
      • indexes[]: AQI chung và AQI địa phương (nếu có) (displayName, value, valueDisplay, category và dominantPollutant).
      • pollutants[]: Được điền sẵn khi include_pollutant_concentration là true (displayName, fullName, concentration trong ppb hoặc µg/m³, và additionalInfo có lượng khí thải sources và tình trạng effects).
      • healthRecommendations: Hướng dẫn cho generalPopulation, elderly, lungDiseasePopulation, heartDiseasePopulation, athletes, pregnantWomen và children.
    • attribution: Thông tin ghi nhận tác giả mà bạn phải hiển thị cùng với dữ liệu chất lượng không khí.
  • pollen: Được điền sẵn khi POLLEN được yêu cầu:
    • dailyForecast: Thông tin dự báo về phấn hoa cho date được yêu cầu:
      • date: Ngày theo lịch dân sự của thông tin dự báo.
      • categories[]: Các danh mục chất gây dị ứng rộng (Tree, Grass và Weed), mỗi danh mục có displayName, inSeason, Chỉ số phấn hoa chung index (thang điểm từ 0 đến 5, category và description) và healthRecommendations[].
      • plantSpecies[]: Các loài thực vật gây dị ứng cụ thể (chẳng hạn như Bạch dương, Cỏ phấn hương hoặc Tuyết tùng Nhật Bản), mỗi loài có code, displayName, family thực vật, inSeason, Chỉ số phấn hoa chung index, season nở hoa điển hình và crossReactions.
    • attribution: Thông tin ghi nhận tác giả mà bạn phải hiển thị cùng với dữ liệu về phấn hoa.

Một số tính năng có thể không dùng được

Khi một yêu cầu bao gồm nhiều chức năng, mỗi chức năng sẽ được đánh giá và tìm nạp độc lập. Nếu một chức năng không hoạt động tại vị trí được yêu cầu, nằm ngoài phạm vi thời gian được hỗ trợ hoặc tạm thời không hoạt động trong khi ít nhất một chức năng khác hoạt động, thì phản hồi sẽ trả về các vùng chứa chức năng hoạt động và bỏ qua vùng chứa không hoạt động hoặc không thành công. Yêu cầu chỉ không thành công và báo lỗi nếu mọi chức năng được yêu cầu đều không thành công.

Để biết thông tin chi tiết về trường, hãy xem tài liệu tham khảo về lookup_weather.

Thanh toán và hạn mức

Mỗi yêu cầu lookup_weather là một sự kiện có thể tính phí, ngay cả khi capabilities yêu cầu hai hoặc ba miền môi trường trong cùng một lệnh gọi:

  • Một yêu cầu được tính phí theo cấp SKU cao nhất trong số các chức năng thành công và được trả về trong phản hồi:
    • Nếu phản hồi bao gồm pollen hoặc airQuality trong quá khứ (date trước hôm nay hoặc hour trong quá khứ theo múi giờ của vị trí), thì yêu cầu sẽ được tính phí theo SKU Maps Grounding Pro. Việc yêu cầu cả POLLEN và AIR_QUALITY trước đây trong một lệnh gọi vẫn được tính là một sự kiện có tính phí của Gemini Pro.
    • Nếu không, yêu cầu sẽ được tính phí theo SKU Maps Grounding Essentials.
  • Nếu một chức năng Pro bị bỏ qua trong yêu cầu nhiều chức năng (vì chức năng đó không có sẵn cho vị trí, nằm ngoài phạm vi thời gian được hỗ trợ hoặc tạm thời không hoạt động) và chỉ có các chức năng Essentials được trả về trong phản hồi, thì yêu cầu đó sẽ được tính phí theo SKU Essentials.

Hạn mức lookup_weather là 300 truy vấn mỗi phút cho mỗi dự án, được chia sẻ bởi cả hai SKU. Để biết thông tin về giá, hãy xem Bảng giá chính và Bảng giá tại Ấn Độ.