ค้นหาสภาพอากาศ

เครื่องมือ lookup_weather ช่วยให้ LLM ดึงข้อมูลสภาพแวดล้อมของสถานที่หนึ่งๆ ได้ ซึ่งได้แก่ สภาพอากาศ คุณภาพอากาศ และละอองเกสรดอกไม้ คำขอเดียวสามารถค้นหาความสามารถด้านสิ่งแวดล้อม 1, 2 หรือทั้ง 3 รายการสำหรับรหัสสถานที่ ที่อยู่ หรือพิกัดละติจูด/ลองจิจูด

คำขอที่ค้นหาเฉพาะสภาพอากาศหรือคุณภาพอากาศปัจจุบันและพยากรณ์คุณภาพอากาศจะเรียกเก็บเงินภายใต้ SKU ของ Maps Grounding Essentials Pro เพิ่มการพยากรณ์ละอองเกสรรายวันและคุณภาพอากาศที่ผ่านมาสูงสุด 30 วัน

คุณสามารถเรียกใช้ lookup_weather ผ่านเซิร์ฟเวอร์ MCP หรือเป็นเมธอด REST lookupWeather ได้ หน้านี้อธิบายความสามารถด้านสิ่งแวดล้อม ตัวเลือกคำขอ ตัวเลือก Pro โครงสร้างการตอบกลับ และกฎการเรียกเก็บเงิน ดูสคีมาทั้งหมดได้ที่เอกสารอ้างอิง MCP ของ lookup_weather และเอกสารอ้างอิง REST ของ lookupWeather

ความสามารถและกรอบเวลา

ใช้อาร์เรย์ capabilities เพื่อเลือกโดเมนสภาพแวดล้อมที่จะแสดงผล (WEATHER, AIR_QUALITY, POLLEN) คุณต้องใช้ capabilities ทุกครั้งที่ตั้งค่า weather_options, air_quality_options หรือ language_code หากคุณละเว้น capabilities, weather_options, air_quality_options และ language_code, lookup_weather จะทำงานในโหมดสภาพอากาศเดิมและแสดงผลช่องสภาพอากาศระดับบนสุดแบบคงที่

ระบบจะประเมินค่า date และ hour ทั้งหมดในเขตเวลาท้องถิ่นของสถานที่ตั้งที่ขอ ตารางต่อไปนี้สรุปช่วงเวลาและ SKU ที่รองรับสำหรับแต่ละความสามารถ

ความสามารถ สภาพอากาศปัจจุบัน (ละเว้น date และ hour) สภาพอากาศที่ผ่านมา สภาพอากาศที่คาดการณ์ SKU
WEATHER สภาพอากาศปัจจุบัน ย้อนหลังได้สูงสุด 24 ชั่วโมง (ต้องใช้ทั้ง date และ hour โดยระบบไม่รองรับ date ที่ผ่านมาซึ่งไม่มี hour) พยากรณ์อากาศรายชั่วโมงสูงสุด 240 ชั่วโมง (10 วัน) เมื่อตั้งค่า hour หรือพยากรณ์อากาศรายวันสูงสุด 10 วันเมื่อตั้งค่าเฉพาะ date Essentials
AIR_QUALITY คุณภาพอากาศรายชั่วโมงในปัจจุบัน สูงสุด 720 ชั่วโมง (30 วัน) ในอดีตสำหรับ 1 ชั่วโมงเมื่อตั้งค่า date และ hour หรือสูงสุด 29 วันก่อนวันนี้ (สูงสุด 24 รายการรายชั่วโมง) เมื่อตั้งค่าเฉพาะ date สูงสุด 96 ชั่วโมง (4 วัน) ในอนาคตสำหรับ 1 ชั่วโมงเมื่อตั้งค่า date และ hour ไว้ หรือตั้งแต่วันนี้จนถึง 3 วันหลังจากวันนี้ (สูงสุด 24 รายการต่อชั่วโมง) เมื่อตั้งค่าเฉพาะ date ไว้ ข้อมูลสำคัญสำหรับสภาพอากาศปัจจุบัน สภาพอากาศตลอดทั้งวัน และพยากรณ์อากาศ Pro สำหรับ date ก่อนวันนี้หรือ hour ที่ผ่านมาเมื่อแสดงในคำตอบ
POLLEN การพยากรณ์ละอองเกสรรายวันของวันปัจจุบัน ไม่รองรับ (แสดงข้อผิดพลาด INVALID_ARGUMENT) การคาดการณ์ละอองเกสรดอกไม้รายวันสูงสุด 4 วันหลังจากวันนี้ รวมเป็น 5 วันรวมวันนี้ (ระบบจะไม่สนใจ hour สำหรับละอองเกสรดอกไม้) Pro เมื่อแสดงในคำตอบ

สำหรับ AIR_QUALITY หน้าต่างการคาดการณ์ 720 ชั่วโมงที่ผ่านมาถึง 96 ชั่วโมงจะยึดตามชั่วโมงปัจจุบัน คำขอแบบเต็มวัน (date ที่ไม่มี hour) จะครอบคลุมเวลา 00:00 ถึง 23:00 ตามเวลาท้องถิ่น และต้องอยู่ภายในกรอบเวลาดังกล่าว ซึ่งในทางปฏิบัติคือตั้งแต่ 29 วันก่อนวันนี้จนถึง 3 วันหลังจากวันนี้

เมื่อคำขอมีหลายความสามารถ ระบบจะประเมินกรอบเวลาของแต่ละความสามารถแยกกัน หาก date และ hour ที่ขออยู่ในช่วงสำหรับความสามารถที่ขออย่างน้อย 1 รายการ การตอบกลับจะแสดงคอนเทนเนอร์ความสามารถที่รองรับและละเว้นความสามารถที่ระบบไม่รองรับช่วงเวลา ตัวอย่างเช่น การขอ AIR_QUALITY และ POLLEN สำหรับวันที่ที่ผ่านมาภายใน 30 วันจะแสดงผล airQuality และละเว้น pollen คำขอจะแสดงข้อผิดพลาด INVALID_ARGUMENT หาก date หรือ hour อยู่นอกช่วงที่รองรับของความสามารถที่ขอทุกรายการ

ตัวเลือกคำขอ

LLM จะตั้งค่าตัวเลือกเหล่านี้เมื่อเรียกใช้เครื่องมือ โดยอิงตามคำขอของผู้ใช้และคำอธิบายเครื่องมือ คุณสามารถกำหนดตัวเลือกที่โมเดลจะใช้ได้ด้วยคำสั่งของคุณเอง โปรดดูหัวข้อควบคุมการใช้งาน Pro

ตารางต่อไปนี้อธิบายตัวเลือกคำขอสำหรับ lookup_weather

ตัวเลือก คำอธิบาย
location ต้องระบุ สถานที่ที่จะค้นหา ซึ่งระบุเป็น address (ที่อยู่ เมือง หรือชื่อจุดสังเกตที่มนุษย์อ่านได้) place_id หรือ lat_lng (latitude และ longitude)
capabilities ไม่บังคับ ค่าอย่างน้อย 1 ค่าจาก WEATHER, AIR_QUALITY และ POLLEN ระบบจะกรองค่าที่ซ้ำกันออก ต้องระบุเมื่อตั้งค่า weather_options, air_quality_options หรือ language_code เมื่อละเว้น capabilities และตัวเลือกเหล่านั้นทั้งหมด ระบบจะแสดงผลการตอบกลับสภาพอากาศแบบ Flat-Field เดิม
date ไม่บังคับ วันที่ตามปฏิทินท้องถิ่น (year, month, day) ณ สถานที่ที่ขอ ละเว้น date และ hour สำหรับสภาพอากาศปัจจุบัน
hour ไม่บังคับ ชั่วโมงท้องถิ่น (0 ถึง 23) ณ สถานที่ตั้งที่ขอ ต้องตั้งค่า date การตั้งค่า hour โดยไม่มี date จะแสดงข้อผิดพลาด INVALID_ARGUMENT
language_code ไม่บังคับ รหัสภาษา BCP-47 สำหรับข้อความที่แปลแล้วในการตอบกลับ เช่น en, ja หรือ fr-CA ค่าเริ่มต้นคือ en
weather_options.units_system ไม่บังคับ ระบบหน่วยสำหรับค่าสภาพอากาศ: METRIC (ค่าเริ่มต้น เซลเซียส กิโลเมตรต่อชั่วโมง มิลลิเมตร) หรือ IMPERIAL (ฟาเรนไฮต์ ไมล์ต่อชั่วโมง นิ้ว) ระบบจะไม่สนใจหากไม่ได้ขอ WEATHER
air_quality_options.include_pollutant_concentration ไม่บังคับ เมื่อtrueมีข้อมูล airQuality.hourlyResults[].pollutants[] จะรวมความเข้มข้นของสารมลพิษที่วัดได้ แหล่งปล่อยก๊าซ และผลกระทบต่อสุขภาพ ค่าเริ่มต้นคือ false ระบบจะไม่สนใจหากไม่ได้ขอ AIR_QUALITY
air_quality_options.index_region_code ไม่บังคับ รหัสประเทศหรือภูมิภาค ISO 3166-1 alpha-2 แบบ 2 ตัวอักษร เช่น US, FR หรือ CN ซึ่งใช้เพื่อเลือกมาตราส่วนดัชนีคุณภาพอากาศ (AQI) ในพื้นที่ควบคู่ไปกับ AQI สากล (UAQI) ค่าเริ่มต้นคือภูมิภาคของสถานที่ตั้งที่ขอ ระบบจะไม่สนใจหากไม่ได้ขอ AIR_QUALITY

ตัวเลือก Pro

ตัวเลือกที่ 2 ให้เลือก Maps Grounding Pro SKU ระบบจะเรียกเก็บเงินคำขอภายใต้ SKU แบบ Pro เมื่อมีการแสดงผลตัวเลือกใดตัวเลือกหนึ่งในการตอบกลับ สำหรับกฎการเรียกเก็บเงินสำหรับความสามารถหลายอย่าง โปรดดูหัวข้อการเรียกเก็บเงินและโควต้า ตารางต่อไปนี้จะอธิบายตัวเลือก Pro

ตัวเลือก Pro ใช้เมื่อใด
POLLEN ใน capabilities ผู้ใช้ถามเกี่ยวกับระดับละอองเกสรดอกไม้ อาการแพ้ตามฤดูกาล ละอองเกสรจากต้นไม้ หญ้า หรือวัชพืช หรือพืชชนิดที่ก่อให้เกิดอาการแพ้โดยเฉพาะ
AIR_QUALITYในcapabilitiesที่มีdateก่อนวันนี้หรือhourที่ผ่านมา ผู้ใช้ถามเกี่ยวกับคุณภาพอากาศ ควัน หรือมลพิษที่ผ่านมาในช่วง 30 วันที่ผ่านมาในเขตเวลาของสถานที่นั้น

คำขอ lookup_weather อื่นๆ ทั้งหมดจะเรียกเก็บเงินภายใต้ SKU Essentials ซึ่งรวมถึงรายการต่อไปนี้

  • คำขอ WEATHER ทั้งหมด (ปัจจุบัน, ประวัติ 24 ชั่วโมง และพยากรณ์อากาศรายชั่วโมงหรือรายวัน 10 วัน)
  • คำขอ AIR_QUALITY ปัจจุบัน, เต็มวันของวันนี้ (date ตั้งค่าเป็นวันนี้โดยไม่มี hour) และการคาดการณ์ รวมถึงคำขอที่ตั้งค่า include_pollutant_concentration เป็น true หรือระบุ index_region_code

ตัวอย่าง

คำขอ MCP ต่อไปนี้จะขอข้อมูลสภาพอากาศปัจจุบัน คุณภาพอากาศ (พร้อมความเข้มข้นของสารมลพิษ) และการพยากรณ์ละอองเกสรดอกไม้ของวันนี้ในโตเกียว เนื่องจาก capabilities มี POLLEN ระบบจึงเรียกเก็บเงินสำหรับคำขอภายใต้ 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
}

ตัวอย่างต่อไปนี้จะส่งคำขอเดียวกันไปยังเมธอด 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"

แทนที่ API_KEY ด้วยคีย์ API ของคุณ

คำตอบ

เมื่อคำขอระบุ capabilities การตอบกลับจะสร้างคอนเทนเนอร์เฉพาะโดเมนสำหรับความสามารถที่ขอแต่ละรายการพร้อมกับข้อมูลเมตาตำแหน่ง ดังนี้

  • returnedLocation: ตำแหน่งที่แก้ไขแล้ว (address, placeId หรือ latLng ซึ่งตรงกับประเภท location ที่ป้อน) สำหรับข้อมูลด้านสิ่งแวดล้อม
  • timeZone: ตัวระบุเขตเวลา IANA ที่แก้ไขแล้วสำหรับสถานที่ตั้ง เช่น "America/Los_Angeles" หรือ "Asia/Tokyo"
  • weather: ระบบจะป้อนข้อมูลเมื่อมีการขอ WEATHER:
    • dateTime (สำหรับการค้นหาปัจจุบันและรายชั่วโมง) เป็นการประทับเวลา UTC หรือ date (สำหรับการค้นหาพยากรณ์รายวัน) หากต้องการแสดงเวลาท้องถิ่น ให้แปลง dateTime ด้วยช่อง timeZone
    • อุณหภูมิ (temperature, feelsLikeTemperature, heatIndex หรือmaxTemperature, minTemperature, feelsLikeMaxTemperature, feelsLikeMinTemperature, maxHeatIndex รายวัน)
    • weatherCondition, precipitation, wind, airPressure, relativeHumidity, uvIndex, thunderstormProbability, cloudCover, และsunEventsกับmoonEventsรายวัน เวลาที่พระอาทิตย์ขึ้น พระอาทิตย์ตก ดวงจันทร์ขึ้น และดวงจันทร์ตกคือการประทับเวลา UTC
    • attribution: การระบุแหล่งที่มาที่คุณต้องแสดงพร้อมกับข้อมูลสภาพอากาศ
  • airQuality: ป้อนข้อมูลเมื่อมีการขอ AIR_QUALITY:
    • hourlyResults[]: มี 1 รายการสำหรับการค้นหาปัจจุบันหรือการค้นหาแบบชั่วโมงเดียว หรือมีได้สูงสุด 24 รายการซึ่งครอบคลุมทั้งวันตามเวลาท้องถิ่น (00:00 ถึง 23:00) เมื่อตั้งค่าเฉพาะ date ไว้ เมื่อ date คือวันนี้และละเว้น hour รายการจะรวมชั่วโมงที่ผ่านมาของวันนี้ ชั่วโมงปัจจุบัน และชั่วโมงที่คาดการณ์ที่เหลือ โดยแต่ละรายการจะมีข้อมูลต่อไปนี้
      • dateTime: วันที่และเวลาตามปฏิทินท้องถิ่น (year, month, day, hours, minutes, seconds และ utcOffset) ในเขตเวลาของสถานที่ตั้ง
      • indexes[]: AQI สากล และ AQI ในพื้นที่ (หากมี) (displayName, value, valueDisplay, category และ dominantPollutant)
      • pollutants[]: ป้อนข้อมูลเมื่อ include_pollutant_concentration เป็น true (displayName, fullName, concentration ใน ppb หรือ µg/m³ และ additionalInfo ที่มีการปล่อยก๊าซ sources และสุขภาพ effects)
      • healthRecommendations: คำแนะนำสำหรับ generalPopulation, elderly, lungDiseasePopulation, heartDiseasePopulation, athletes, pregnantWomen และ children
    • attribution: การระบุแหล่งที่มาที่คุณต้องแสดงพร้อมกับข้อมูลคุณภาพอากาศ
  • pollen: ป้อนข้อมูลเมื่อมีการขอ POLLEN:
    • dailyForecast: การคาดการณ์ละอองเกสรสำหรับdateที่ขอ:
      • date: วันที่ตามปฏิทินพลเรือนของการคาดการณ์
      • categories[]: หมวดหมู่สารก่อภูมิแพ้แบบกว้าง (Tree, Grass และ Weed) โดยแต่ละหมวดหมู่จะมีdisplayName, inSeason, ดัชนีละอองเกสรแบบสากล index (สเกล 0 ถึง 5, category และ description) และhealthRecommendations[]
      • plantSpecies[]: พันธุ์พืชที่ก่อให้เกิดอาการแพ้โดยเฉพาะ (เช่น เบิร์ช แร็กวีด หรือซีดาร์ญี่ปุ่น) ซึ่งแต่ละชนิดจะมีcode, displayName, familyทางพฤกษศาสตร์, inSeason, ดัชนีละอองเกสรแบบสากล index, seasonที่ออกดอกตามปกติ และcrossReactions
    • attribution: การระบุแหล่งที่มาที่คุณต้องแสดงพร้อมกับข้อมูลละอองเกสร

ความพร้อมใช้งานบางส่วนในความสามารถต่างๆ

เมื่อคำขอมีความสามารถหลายอย่าง ระบบจะประเมินและดึงข้อมูลความสามารถแต่ละอย่างแยกกัน หากความสามารถหนึ่งไม่พร้อมใช้งานสำหรับสถานที่ที่ขอ อยู่นอกช่วงเวลาที่รองรับ หรือดำเนินการไม่สำเร็จชั่วคราวขณะที่ความสามารถอื่นๆ อย่างน้อย 1 รายการดำเนินการสำเร็จ การตอบกลับจะแสดงคอนเทนเนอร์ความสามารถที่พร้อมใช้งานและละเว้นคอนเทนเนอร์ที่ไม่พร้อมใช้งานหรือดำเนินการไม่สำเร็จ คำขอจะดำเนินการไม่สำเร็จและแสดงข้อผิดพลาดก็ต่อเมื่อความสามารถที่ขอทั้งหมดดำเนินการไม่สำเร็จ

ดูรายละเอียดช่องทั้งหมดได้ในข้อมูลอ้างอิง lookup_weather

การเรียกเก็บเงินและโควต้า

คำขอ lookup_weather แต่ละรายการเป็นเหตุการณ์ที่เรียกเก็บเงินได้ 1 รายการ แม้ว่า capabilities จะขอโดเมนสภาพแวดล้อม 2 หรือ 3 รายการในการเรียกเดียวกันก็ตาม

  • ระบบจะเรียกเก็บเงินคำขอภายใต้ระดับ SKU สูงสุดในบรรดาความสามารถที่ทำงานสำเร็จและแสดงผลในการตอบกลับ ดังนี้
    • หากการตอบกลับมี pollen หรือ airQuality ในอดีต (date ก่อนวันนี้หรือ hour ที่ผ่านมาในเขตเวลาของสถานที่) ระบบจะเรียกเก็บเงินคำขอภายใต้ SKU ของ Maps Grounding Pro การขอทั้ง POLLEN และ AIR_QUALITY ในอดีตในการเรียกใช้ครั้งเดียวยังคงนับเป็นเหตุการณ์ที่เรียกเก็บเงินได้ของ Pro 1 รายการ
    • ไม่เช่นนั้น ระบบจะเรียกเก็บเงินสำหรับคำขอภายใต้ SKU ของ Maps Grounding Essentials
  • หากไม่มีความสามารถระดับ Pro ในคำขอที่มีความสามารถหลายอย่าง เนื่องจากไม่พร้อมให้บริการในสถานที่นั้น อยู่นอกช่วงเวลาที่รองรับ หรือไม่สำเร็จชั่วคราว และระบบแสดงเฉพาะความสามารถระดับ Essentials ในการตอบกลับ ระบบจะเรียกเก็บเงินสำหรับคำขอนั้นภายใต้ SKU ระดับ Essentials

โควต้า lookup_weather คือ 300 คำค้นหาต่อนาทีสำหรับแต่ละโปรเจ็กต์ ซึ่งแชร์โดย SKU ทั้ง 2 รายการ ดูราคาได้ที่ตารางราคาหลักและตารางราคาสำหรับอินเดีย