날씨 조회

lookup_weather 도구를 사용하면 LLM이 위치의 환경 조건(날씨, 공기질, 꽃가루)을 검색할 수 있습니다. 단일 요청으로 장소 ID, 주소 또는 위도/경도 좌표에 대한 환경 기능 중 하나, 둘 또는 세 가지 모두를 쿼리할 수 있습니다.

날씨 또는 현재 및 예측 공기질만 쿼리하는 요청은 Maps Grounding Essentials SKU로 청구됩니다. Pro는 일일 꽃가루 예보와 최대 30일 전의 과거 공기질을 추가합니다.

MCP 서버를 통해 또는 lookupWeather REST 메서드로 lookup_weather를 호출할 수 있습니다. 이 페이지에서는 환경 기능, 요청 옵션, Pro 옵션, 응답 구조, 결제 규칙을 설명합니다. 전체 스키마는 lookup_weather MCP 참조 및 lookupWeather REST 참조를 확인하세요.

기능 및 기간

capabilities 배열을 사용하여 반환할 환경 도메인(WEATHER, AIR_QUALITY, POLLEN)을 선택합니다. weather_options, air_quality_options 또는 language_code를 설정할 때마다 capabilities가 필요합니다. capabilities, weather_options, air_quality_options, language_code를 생략하면 lookup_weather가 기존 날씨 모드에서 실행되고 플랫 최상위 날씨 필드를 반환합니다.

모든 date 및 hour 값은 요청된 위치의 현지 시간대에서 평가됩니다. 다음 표에는 각 기능에 지원되는 기간과 SKU가 요약되어 있습니다.

기능	현재 상태(`date` 및 `hour` 생략됨)	이전 상태	예측 조건	SKU
`WEATHER`	현재 날씨	최대 24시간 전(`date` 및 `hour` 모두 필요, `hour` 없이 `date`만 있는 경우는 지원되지 않음)	`hour`가 설정된 경우 최대 240시간(10일)의 시간별 예측, `date`만 설정된 경우 최대 10일의 일일 예측	Essentials
`AIR_QUALITY`	현재 시간별 공기질	`date` 및 `hour`가 설정된 경우 과거 최대 720시간(30일) 중 1시간, 또는 `date`만 설정된 경우 오늘 이전 최대 29일(최대 24시간 항목)	`date` 및 `hour`가 설정된 경우 향후 최대 96시간(4일) 동안 1시간 단위로, `date`만 설정된 경우 오늘부터 오늘 이후 3일까지(최대 24시간 단위 항목)	현재, 오늘 하루, 일기예보의 필수 정보입니다. 응답에서 반환될 때 오늘 이전의 `date` 또는 과거의 `hour`에 대한 Pro
`POLLEN`	오늘의 일일 꽃가루 예보	지원되지 않음(`INVALID_ARGUMENT` 오류 반환)	오늘부터 최대 4일 후까지의 일일 꽃가루 예보, 오늘을 포함한 5일(`hour`은 꽃가루에 무시됨)	응답으로 반환될 때 Pro

AIR_QUALITY의 경우 720시간 전부터 96시간 예측 기간이 현재 시간에 고정됩니다. 하루 종일 요청(hour가 없는 date)은 현지 시간으로 00:00부터 23:00까지를 포함하며, 해당 기간 내에 맞아야 합니다. 실제로는 오늘로부터 29일 전부터 오늘로부터 3일 후까지입니다.

요청에 여러 기능이 포함된 경우 각 기능의 기간은 독립적으로 평가됩니다. 요청된 date 및 hour가 하나 이상의 요청된 기능 범위 내에 있는 경우 응답은 지원되는 기능 컨테이너를 반환하고 기간이 지원되지 않는 기능은 생략합니다. 예를 들어 30일 이내의 과거 날짜에 대해 AIR_QUALITY 및 POLLEN를 요청하면 airQuality가 반환되고 pollen는 생략됩니다. date 또는 hour가 요청된 모든 기능의 지원되는 범위를 벗어나면 요청에서 INVALID_ARGUMENT 오류를 반환합니다.

요청 옵션

LLM은 사용자의 요청과 도구 설명을 기반으로 도구를 호출할 때 이러한 옵션을 설정합니다. 자체 안내를 통해 모델이 사용하는 옵션에 영향을 줄 수 있습니다. Pro 사용량 제어를 참조하세요.

다음 표에서는 lookup_weather의 요청 옵션을 설명합니다.

옵션	설명
`location`	필수 항목입니다. 쿼리할 위치로, `address`(인간이 읽을 수 있는 주소, 도시 또는 명소 이름), `place_id` 또는 `lat_lng`(`latitude` 및 `longitude`)로 지정됩니다.
`capabilities`	선택사항입니다. `WEATHER`, `AIR_QUALITY`, `POLLEN`의 값 하나 이상입니다. 중복 값은 중복 삭제됩니다. `weather_options`, `air_quality_options` 또는 `language_code`를 설정할 때 필요합니다. `capabilities` 및 이러한 옵션이 모두 생략되면 기존 플랫 필드 날씨 응답을 반환합니다.
`date`	선택사항입니다. 요청된 위치의 현지 민간 날짜(`year`, `month`, `day`)입니다. 현재 상태의 경우 `date` 및 `hour`를 생략합니다.
`hour`	선택사항입니다. 요청된 위치의 현지 시간(`0`~`23`)입니다. `date`를 설정해야 합니다. `date` 없이 `hour`를 설정하면 `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`	선택사항입니다. 범용 공기질 지수(UAQI)와 함께 현지 공기질 지수(AQI) 척도를 선택하는 데 사용되는 두 자리 ISO 3166-1 alpha-2 국가 또는 지역 코드(예: `US`, `FR`, `CN`)입니다. 기본값은 요청된 위치의 리전입니다. `AIR_QUALITY`가 요청되지 않으면 무시됩니다.

Pro 옵션

두 가지 옵션은 Maps Grounding Pro SKU를 선택합니다. 응답에서 두 옵션 중 하나가 반환되면 요청은 Pro SKU로 청구됩니다. 다중 기능 결제 규칙은 결제 및 할당량을 참고하세요. 다음 표에서는 Pro 옵션을 설명합니다.

Pro 옵션	사용 시기
`capabilities`의 `POLLEN`	사용자가 꽃가루 수치, 계절성 알레르기, 나무, 잔디, 잡초 꽃가루 또는 특정 알레르기 유발 식물 종에 관해 질문합니다.
`capabilities`의 `AIR_QUALITY`(오늘 이전의 `date` 또는 이전 `hour`)	사용자가 해당 위치의 시간대를 기준으로 지난 30일 동안의 과거 공기질, 연기 또는 오염에 대해 질문합니다.

다른 모든 lookup_weather 요청은 Essentials SKU로 청구됩니다. 여기에는 다음이 포함됩니다.

모든 WEATHER 요청(현재, 24시간 기록, 10일 시간별 또는 일일 예보)
현재, 오늘 하루 전체(hour 없이 date가 오늘로 설정됨), 예측 AIR_QUALITY 요청(include_pollutant_concentration를 true로 설정하거나 index_region_code를 지정하는 요청 포함)

예

다음 MCP 요청은 도쿄의 현재 날씨, 공기질(오염 물질 농도 포함), 오늘의 꽃가루 예보를 요청합니다. capabilities에 POLLEN가 포함되어 있으므로 요청은 Pro SKU로 청구됩니다.

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

다음 예시에서는 동일한 요청을 lookupWeather REST 메서드로 전송합니다.

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: 환경 데이터의 확인된 위치(입력 location 유형과 일치하는 address, placeId 또는 latLng)입니다.
timeZone: 위치에 대해 확인된 IANA 시간대 식별자입니다(예: "America/Los_Angeles" 또는 "Asia/Tokyo").
weather: WEATHER가 요청될 때 채워집니다.
- dateTime(현재 및 시간별 쿼리) - UTC 타임스탬프 또는 date(일일 예측 쿼리) 현지 시간을 표시하려면 timeZone 필드를 사용하여 dateTime를 변환합니다.
- 온도(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개 또는 date만 설정된 경우 전체 현지 날짜(00:00~23:00)를 포함하는 최대 24개의 항목이 포함됩니다. 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: 꽃가루 데이터와 함께 표시해야 하는 저작자 표시입니다.

기능 전반의 부분 가용성

요청에 여러 기능이 포함된 경우 각 기능은 독립적으로 평가되고 가져옵니다. 요청된 위치에서 하나의 기능을 사용할 수 없거나, 지원되는 기간을 벗어나거나, 일시적으로 실패하는 반면 다른 기능이 하나 이상 성공하면 응답은 사용 가능한 기능 컨테이너를 반환하고 사용할 수 없거나 실패한 컨테이너를 생략합니다. 요청된 모든 기능이 실패하는 경우에만 요청이 오류와 함께 실패합니다.

전체 필드 세부정보는 lookup_weather 참조를 확인하세요.

결제 및 할당량

capabilities가 동일한 호출에서 2개 또는 3개의 환경 도메인을 요청하는 경우에도 각 lookup_weather 요청은 하나의 청구 가능한 이벤트입니다.

요청은 성공하고 응답에서 반환되는 기능 중 가장 높은 SKU 등급으로 청구됩니다.
- 응답에 pollen 또는 과거 airQuality(오늘 이전의 date 또는 해당 위치의 시간대에서 과거의 hour)가 포함된 경우 요청은 Maps Grounding Pro SKU에 따라 청구됩니다. 한 번의 호출로 POLLEN와 이전 AIR_QUALITY를 모두 요청하는 경우에도 Pro 청구 가능 이벤트 1개로 계산됩니다.
- 그렇지 않으면 요청은 지도 그라운딩 Essentials SKU에 따라 청구됩니다.
위치에서 사용할 수 없거나, 지원되는 기간을 벗어나거나, 일시적으로 실패하여 다중 기능 요청에서 Pro 기능이 생략되고 응답에 Essentials 기능만 반환되는 경우 요청은 Essentials SKU로 청구됩니다.

lookup_weather 할당량은 프로젝트당 분당 300개의 쿼리이며 두 SKU가 공유합니다. 가격은 기본 가격표 및 인도 가격표를 참조하세요.