Buscar el clima

La herramienta lookup_weather permite que un LLM recupere las condiciones ambientales de una ubicación: clima, calidad del aire y polen. Una sola solicitud puede consultar una, dos o las tres funciones ambientales para un ID de lugar, una dirección o coordenadas de latitud y longitud.

Las solicitudes que solo consultan el clima o la calidad del aire actual y prevista se facturan con el SKU de Maps Grounding Essentials. Pro agrega previsiones diarias de polen y datos históricos de la calidad del aire de hasta 30 días en el pasado.

Puedes llamar a lookup_weather a través del servidor de MCP o como el método REST lookupWeather. En esta página, se describen las capacidades ambientales, las opciones de solicitud, las opciones de Pro, la estructura de respuesta y las reglas de facturación. Para ver los esquemas completos, consulta la referencia de MCP de lookup_weather y la referencia de REST de lookupWeather.

Capacidades y horizontes temporales

Usa el array capabilities para seleccionar qué dominios ambientales se deben mostrar (WEATHER, AIR_QUALITY, POLLEN). Se requiere capabilities cada vez que configuras weather_options, air_quality_options o language_code. Si omites capabilities, weather_options, air_quality_options y language_code, lookup_weather se ejecuta en el modo de clima heredado y devuelve campos de clima planos de nivel superior.

Todos los valores date y hour se evalúan en la zona horaria local de la ubicación solicitada. En la siguiente tabla, se resumen los períodos y los SKU admitidos para cada función:

Función Condiciones actuales (se omitieron date y hour) Condiciones anteriores Condiciones de previsión SKU
WEATHER Clima actual Hasta 24 horas en el pasado (requiere date y hour; no se admite el pasado date sin hour) Pronóstico por hora de hasta 240 horas (10 días) cuando se establece hour, o pronóstico diario de hasta 10 días cuando solo se establece date Imprescindibles
AIR_QUALITY Calidad del aire actual por hora Hasta 720 horas (30 días) en el pasado para una sola hora cuando se configuran date y hour, o hasta 29 días antes de hoy (hasta 24 entradas por hora) cuando solo se configura date Hasta 96 horas (4 días) en el futuro para una sola hora cuando se configuran date y hour, o desde hoy hasta 3 días después de hoy (hasta 24 entradas por hora) cuando solo se configura date Información esencial para el clima actual, el día de hoy completo y el pronóstico Pro para un date antes de hoy o un hour anterior cuando se devuelve en la respuesta
POLLEN Pronóstico diario de polen para el día actual No se admite (devuelve un error INVALID_ARGUMENT) Previsión diaria de polen hasta 4 días después de hoy, durante 5 días, incluido hoy (se ignora hour para el polen) Pro cuando se devuelve en la respuesta

Para AIR_QUALITY, la ventana de previsión de 720 horas anteriores a 96 horas se fija en la hora actual. Las solicitudes de día completo (date sin hour) abarcan desde las 00:00 hasta las 23:00, hora local, y deben ajustarse a ese período, en la práctica, desde 29 días antes de hoy hasta tres días después de hoy.

Cuando una solicitud incluye varias capacidades, el horizonte temporal de cada capacidad se evalúa de forma independiente. Si los valores de date y hour solicitados están dentro del rango de, al menos, una capacidad solicitada, la respuesta devuelve los contenedores de capacidad admitidos y omite cualquier capacidad cuyo período no se admita. Por ejemplo, si solicitas AIR_QUALITY y POLLEN para una fecha pasada dentro de los 30 días, se devuelve airQuality y se omite pollen. La solicitud devuelve un error INVALID_ARGUMENT si date o hour están fuera del rango admitido de cada capacidad solicitada.

Opciones de solicitud

El LLM establece estas opciones cuando llama a la herramienta, según la solicitud del usuario y la descripción de la herramienta. Puedes influir en las opciones que usa el modelo con tus propias instrucciones. Consulta Controla el uso de Pro.

En la siguiente tabla, se describen las opciones de solicitud para lookup_weather:

Opción Descripción
location Obligatorio. Es la ubicación que se consultará, especificada como un address (una dirección, ciudad o nombre de punto de referencia legible por humanos), un place_id o un lat_lng (latitude y longitude).
capabilities Opcional. Uno o más valores de WEATHER, AIR_QUALITY y POLLEN. Se quitan los valores duplicados. Es obligatorio cuando se configura weather_options, air_quality_options o language_code. Cuando se omiten capabilities y todas esas opciones, se devuelve la respuesta meteorológica heredada de campo plano.
date Opcional. La fecha civil local (year, month, day) en la ubicación solicitada. Omite date y hour para las condiciones actuales.
hour Opcional. Es la hora local (de 0 a 23) en la ubicación solicitada. Requiere que se establezca date. Si configuras hour sin date, se muestra un error INVALID_ARGUMENT.
language_code Opcional. Es el código de idioma BCP-47 para el texto localizado en la respuesta, como en, ja o fr-CA. La configuración predeterminada es en.
weather_options.units_system Opcional. Es el sistema de unidades para los valores del clima: METRIC (predeterminado; Celsius, kilómetros por hora, milímetros) o IMPERIAL (Fahrenheit, millas por hora, pulgadas). Se ignora si no se solicita WEATHER.
air_quality_options.include_pollutant_concentration Opcional. Cuando es true, airQuality.hourlyResults[].pollutants[] incluye las concentraciones de contaminantes medidas, las fuentes de emisión y los efectos en la salud. La configuración predeterminada es false. Se ignora si no se solicita AIR_QUALITY.
air_quality_options.index_region_code Opcional. Código de país o región ISO 3166-1 alfa-2 de dos letras, por ejemplo, US, FR o CN, que se usa para seleccionar una escala de índice de calidad del aire (ICA) local junto con el ICA universal (ICA-U). La región predeterminada es la de la ubicación solicitada. Se ignora si no se solicita AIR_QUALITY.

Opciones de Pro

Dos opciones seleccionan el SKU de Maps Grounding Pro. Una solicitud se factura con el SKU Pro cuando se devuelve cualquiera de las opciones en la respuesta. Para conocer las reglas de facturación de varias funciones, consulta Facturación y cuotas. En la siguiente tabla, se describen las opciones de Pro:

Opción Pro Cuándo se utiliza
POLLEN en capabilities El usuario pregunta sobre los niveles de polen, las alergias estacionales, el polen de árboles, pasto o malezas, o especies de plantas alergénicas específicas.
AIR_QUALITY en capabilities con un date antes de hoy o un hour anterior El usuario pregunta sobre la calidad del aire, el humo o la contaminación históricos de los últimos 30 días en la zona horaria de la ubicación.

Todas las demás solicitudes de lookup_weather se facturan con el SKU de Essentials, incluidas las siguientes:

  • Todas las solicitudes de WEATHER (actuales, historial de 24 horas y pronósticos por hora o diarios de 10 días).
  • Solicitudes actuales, de todo el día de hoy (date establecido en hoy sin hour) y de previsión AIR_QUALITY, incluidas las solicitudes que establecen include_pollutant_concentration en true o especifican index_region_code.

Ejemplo

La siguiente solicitud de MCP pide el clima actual, la calidad del aire (con concentraciones de contaminantes) y el pronóstico de polen de hoy en Tokio. Debido a que capabilities incluye POLLEN, la solicitud se factura con el 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
}

En el siguiente ejemplo, se envía la misma solicitud al método 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"

Reemplaza API_KEY por tu clave de API.

Respuesta

Cuando una solicitud especifica capabilities, la respuesta propaga contenedores específicos del dominio para cada capacidad solicitada junto con los metadatos de ubicación:

  • returnedLocation: Es la ubicación resuelta (address, placeId o latLng, que coincide con el tipo de location de entrada) para los datos ambientales.
  • timeZone: Es el identificador de zona horaria de IANA resuelto para la ubicación, como "America/Los_Angeles" o "Asia/Tokyo".
  • weather: Se completa cuando se solicita WEATHER:
    • dateTime (para consultas actuales y por hora), como una marca de tiempo UTC, o date (para consultas de previsión diarias). Para mostrar las horas locales, convierte dateTime con el campo timeZone.
    • Temperatura (temperature, feelsLikeTemperature, heatIndex o maxTemperature, minTemperature, feelsLikeMaxTemperature, feelsLikeMinTemperature, maxHeatIndex diarios).
    • weatherCondition, precipitation, wind, airPressure, relativeHumidity, uvIndex, thunderstormProbability, cloudCover, y sunEvents y moonEvents diarios. Las horas de salida y puesta del sol, y de salida y puesta de la luna son marcas de tiempo UTC.
    • attribution: Es la atribución que debes mostrar con los datos meteorológicos.
  • airQuality: Se completa cuando se solicita AIR_QUALITY:
    • hourlyResults[]: Contiene una entrada para las consultas actuales o de una sola hora, o hasta 24 entradas que abarcan todo el día local (de 00:00 a 23:00) cuando solo se establece date. Cuando date es hoy y se omite hour, las entradas combinan las horas históricas anteriores de hoy, la hora actual y las horas de previsión restantes. Cada entrada incluye lo siguiente:
      • dateTime: Es la fecha y hora civil local (year, month, day, hours, minutes, seconds y utcOffset) en la zona horaria de la ubicación.
      • indexes[]: ICA universal y, cuando esté disponible, el ICA local (displayName, value, valueDisplay, category y dominantPollutant).
      • pollutants[]: Se completa cuando include_pollutant_concentration es true (displayName, fullName, concentration en ppb o µg/m³, y additionalInfo con emisión sources y estado effects).
      • healthRecommendations: Orientación para generalPopulation, elderly, lungDiseasePopulation, heartDiseasePopulation, athletes, pregnantWomen y children.
    • attribution: Es la atribución que debes mostrar con los datos de calidad del aire.
  • pollen: Se completa cuando se solicita POLLEN:
    • dailyForecast: Es la previsión de polen para el date solicitado:
      • date: Es la fecha del calendario civil de la previsión.
      • categories[]: Categorías amplias de alérgenos (Tree, Grass y Weed), cada una con displayName, inSeason, índice universal de polen index (escala de 0 a 5, category y description) y healthRecommendations[].
      • plantSpecies[]: Especies de plantas alergénicas específicas (como el abedul, la ambrosía o el cedro japonés), cada una con code, displayName, family botánico, inSeason, índice universal de polen index, season típica y crossReactions.
    • attribution: Es la atribución que debes mostrar con los datos de polen.

Disponibilidad parcial en todas las funciones

Cuando una solicitud incluye varias capacidades, cada una se evalúa y recupera de forma independiente. Si una función no está disponible para la ubicación solicitada, está fuera de su período admitido o falla de forma transitoria mientras al menos otra función se ejecuta correctamente, la respuesta devuelve los contenedores de funciones disponibles y omite el contenedor no disponible o con errores. La solicitud falla con un error solo si fallan todas las capacidades solicitadas.

Para obtener detalles completos de los campos, consulta la referencia de lookup_weather.

Facturación y cuotas

Cada solicitud de lookup_weather es un evento facturable, incluso cuando capabilities solicita dos o tres dominios ambientales en la misma llamada:

  • Una solicitud se factura según el nivel de SKU más alto entre las capacidades que se ejecutan correctamente y se devuelven en la respuesta:
    • Si la respuesta incluye pollen o airQuality históricos (un date anterior al día de hoy o un hour pasado en la zona horaria de la ubicación), la solicitud se factura con el SKU de Maps Grounding Pro. Solicitar POLLEN y AIR_QUALITY históricos en una sola llamada se sigue considerando un evento facturable de Pro.
    • De lo contrario, la solicitud se factura con el SKU de Maps Grounding Essentials.
  • Si se omite una función de Pro en una solicitud de varias funciones (porque no está disponible para la ubicación, está fuera del período admitido o falla de forma transitoria) y solo se devuelven funciones de Essentials en la respuesta, la solicitud se factura con el SKU de Essentials.

La cuota de lookup_weather es de 300 consultas por minuto para cada proyecto, que comparten ambos SKU. Para conocer los precios, consulta la tabla de precios principal y la tabla de precios de India.