Utilisez davantage de fonctionnalités des outils d'agent Maps Experience avec le SKU Pro ! En savoir plus sur Pro

Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Consulter la météo

L'outil lookup_weather permet à un LLM de récupérer les conditions environnementales d'un lieu : météo, qualité de l'air et pollen. Une même requête peut interroger une, deux ou les trois fonctionnalités environnementales pour un ID de lieu, une adresse ou des coordonnées de latitude/longitude.

Les requêtes qui n'interrogent que la météo ou la qualité de l'air actuelle et prévue sont facturées au titre du SKU Maps Grounding Essentials. Pro ajoute des prévisions quotidiennes sur le pollen et l'historique de la qualité de l'air jusqu'à 30 jours en arrière.

Vous pouvez appeler lookup_weather via le serveur MCP ou en tant que méthode REST lookupWeather. Cette page décrit les fonctionnalités environnementales, les options de requête, les options Pro, la structure des réponses et les règles de facturation. Pour obtenir les schémas complets, consultez la documentation de référence sur le MCP lookup_weather et la documentation de référence sur REST lookupWeather.

Fonctionnalités et horizons temporels

Utilisez le tableau capabilities pour sélectionner les domaines environnementaux à renvoyer (WEATHER, AIR_QUALITY, POLLEN). capabilities est obligatoire chaque fois que vous définissez weather_options, air_quality_options ou language_code. Si vous omettez capabilities, weather_options, air_quality_options et language_code, lookup_weather s'exécute en mode météo ancien et renvoie des champs météo plats de niveau supérieur.

Toutes les valeurs date et hour sont évaluées dans le fuseau horaire local de l'emplacement demandé. Le tableau suivant récapitule les périodes et les SKU compatibles pour chaque fonctionnalité :

Capacité	Conditions actuelles (`date` et `hour` omis)	Antécédents médicaux	Conditions de prévision	SKU
`WEATHER`	Météo actuelle	Jusqu'à 24 heures dans le passé (nécessite à la fois `date` et `hour` ; le passé `date` sans `hour` n'est pas accepté)	Prévisions heure par heure jusqu'à 240 heures (10 jours) lorsque `hour` est défini, ou prévisions quotidiennes jusqu'à 10 jours lorsque seul `date` est défini	Essentials
`AIR_QUALITY`	Qualité de l'air actuelle par heure	Jusqu'à 720 heures (30 jours) dans le passé pour une seule heure lorsque `date` et `hour` sont définis, ou jusqu'à 29 jours avant aujourd'hui (jusqu'à 24 entrées horaires) lorsque seul `date` est défini	Jusqu'à 96 heures (4 jours) dans le futur pour une seule heure lorsque `date` et `hour` sont définis, ou d'aujourd'hui à 3 jours après aujourd'hui (jusqu'à 24 entrées horaires) lorsque seul `date` est défini	Informations essentielles pour la météo actuelle, celle de la journée et les prévisions. Pro pour un `date` antérieur à aujourd'hui ou un `hour` passé lorsqu'il est renvoyé dans la réponse
`POLLEN`	Prévisions polliniques quotidiennes pour le jour même	Non compatible (renvoie une erreur `INVALID_ARGUMENT`)	Prévisions polliniques quotidiennes jusqu'à quatre jours après aujourd'hui, pour cinq jours, aujourd'hui inclus (`hour` est ignoré pour le pollen)	Pro lorsqu'il est renvoyé dans la réponse

Pour AIR_QUALITY, la période de prévision de 720 heures passées à 96 heures est ancrée à l'heure actuelle. Les requêtes portant sur une journée complète (date sans hour) couvrent la période de 00:00 à 23:00 (heure locale) et doivent s'inscrire dans cette période, en pratique de 29 jours avant aujourd'hui à trois jours après aujourd'hui.

Lorsqu'une requête inclut plusieurs fonctionnalités, l'horizon temporel de chaque fonctionnalité est évalué indépendamment. Si les valeurs date et hour demandées se trouvent dans la plage d'au moins une fonctionnalité demandée, la réponse renvoie les conteneurs de fonctionnalités compatibles et omet toute fonctionnalité dont la période n'est pas compatible. Par exemple, si vous demandez AIR_QUALITY et POLLEN pour une date passée dans les 30 jours, airQuality est renvoyé et pollen est omis. La requête renvoie une erreur INVALID_ARGUMENT si date ou hour se trouve en dehors de la plage acceptée pour chaque fonctionnalité demandée.

Options de requête

Le LLM définit ces options lorsqu'il appelle l'outil, en fonction de la requête de l'utilisateur et de la description de l'outil. Vous pouvez influencer les options utilisées par le modèle avec vos propres instructions. Consultez Contrôler l'utilisation de Pro.

Le tableau suivant décrit les options de requête pour lookup_weather :

Option	Description
`location`	Obligatoire. Lieu à interroger, spécifié sous la forme d'une `address` (adresse, ville ou nom de point de repère lisible par l'humain), d'un `place_id` ou d'une `lat_lng` (`latitude` et `longitude`).
`capabilities`	Facultatif. Une ou plusieurs valeurs parmi `WEATHER`, `AIR_QUALITY` et `POLLEN`. Les valeurs en double sont dédupliquées. Obligatoire lors de la définition de `weather_options`, `air_quality_options` ou `language_code`. Lorsque `capabilities` et ces options sont tous omis, renvoie l'ancienne réponse météo à champ plat.
`date`	Facultatif. Date civile locale (`year`, `month`, `day`) à l'emplacement demandé. Omettez `date` et `hour` pour les conditions actuelles.
`hour`	Facultatif. Heure locale (`0` à `23`) à l'emplacement demandé. Nécessite que `date` soit défini. Si vous définissez `hour` sans `date`, une erreur `INVALID_ARGUMENT` est renvoyée.
`language_code`	Facultatif. Code de langue BCP-47 pour le texte localisé dans la réponse, par exemple `en`, `ja` ou `fr-CA`. La valeur par défaut est `en`.
`weather_options.units_system`	Facultatif. Système d'unités pour les valeurs météorologiques : `METRIC` (par défaut ; Celsius, kilomètres par heure, millimètres) ou `IMPERIAL` (Fahrenheit, miles par heure, pouces). Ignoré si `WEATHER` n'est pas demandé.
`air_quality_options.include_pollutant_concentration`	Facultatif. Lorsque la valeur est `true`, `airQuality.hourlyResults[].pollutants[]` inclut les concentrations de polluants mesurées, les sources d'émission et les effets sur la santé. La valeur par défaut est `false`. Ignoré si `AIR_QUALITY` n'est pas demandé.
`air_quality_options.index_region_code`	Facultatif. Code pays ou région ISO 3166-1 alpha-2 à deux lettres (par exemple, `US`, `FR` ou `CN`) utilisé pour sélectionner une échelle d'indice de la qualité de l'air (IQA) locale en plus de l'IQA universel (IQAU). La valeur par défaut est la région de l'emplacement demandé. Ignoré si `AIR_QUALITY` n'est pas demandé.

Options Pro

Deux options sélectionnent le SKU Maps Grounding Pro. Une requête est facturée sous le SKU Pro lorsque l'une ou l'autre option est renvoyée dans la réponse. Pour connaître les règles de facturation multicapacité, consultez Facturation et quotas. Le tableau suivant décrit les options Pro :

Option Pro	Quand l'utiliser ?
`POLLEN` dans `capabilities`	L'utilisateur pose des questions sur les niveaux de pollen, les allergies saisonnières, le pollen d'arbre, d'herbe ou de mauvaises herbes, ou sur des espèces de plantes allergènes spécifiques.
`AIR_QUALITY` dans `capabilities` avec un `date` antérieur à aujourd'hui ou un `hour` passé	L'utilisateur demande des informations sur l'historique de la qualité de l'air, de la fumée ou de la pollution au cours des 30 derniers jours dans le fuseau horaire du lieu.

Toutes les autres requêtes lookup_weather sont facturées sous le SKU Essentials, y compris :

Toutes les requêtes WEATHER (actuelles, historique sur 24 heures et prévisions horaires ou quotidiennes sur 10 jours).
Requêtes AIR_QUALITY actuelles, pour la journée complète (date défini sur aujourd'hui sans hour) et prévisionnelles, y compris les requêtes qui définissent include_pollutant_concentration sur true ou spécifient index_region_code.

Exemple

La requête MCP suivante demande la météo actuelle, la qualité de l'air (avec les concentrations de polluants) et les prévisions de pollen pour aujourd'hui à Tokyo. Comme capabilities inclut POLLEN, la requête est facturée sous le 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
}

L'exemple suivant envoie la même requête à la méthode 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"

Remplacez API_KEY par votre clé API.

Réponse

Lorsqu'une requête spécifie capabilities, la réponse remplit des conteneurs spécifiques au domaine pour chaque fonctionnalité demandée, ainsi que des métadonnées de lieu :

returnedLocation : emplacement validé (address, placeId ou latLng, correspondant au type location d'entrée) pour les données environnementales.
timeZone : identifiant de fuseau horaire IANA résolu pour l'emplacement, par exemple "America/Los_Angeles" ou "Asia/Tokyo".
weather : renseigné lorsque WEATHER est demandé :
- dateTime (pour les requêtes actuelles et horaires), sous forme de code temporel UTC, ou date (pour les requêtes de prévisions quotidiennes). Pour afficher les heures locales, convertissez dateTime avec le champ timeZone.
- Température (temperature, feelsLikeTemperature, heatIndex ou maxTemperature, minTemperature, feelsLikeMaxTemperature, feelsLikeMinTemperature, maxHeatIndex quotidiens).
- weatherCondition, precipitation, wind, airPressure, relativeHumidity, uvIndex, thunderstormProbability, cloudCover, et sunEvents et moonEvents quotidiens. Les heures de lever et de coucher du soleil, ainsi que de lever et de coucher de la lune, sont des codes temporels UTC.
- attribution : attribution que vous devez afficher avec les données météorologiques.
airQuality : renseigné lorsque AIR_QUALITY est demandé :
- hourlyResults[] : contient une entrée pour les requêtes actuelles ou d'une seule heure, ou jusqu'à 24 entrées couvrant l'intégralité de la journée locale (00:00 à 23:00) lorsque seul date est défini. Lorsque date correspond à aujourd'hui et que hour est omis, les entrées combinent les heures historiques précédentes d'aujourd'hui, l'heure actuelle et les heures de prévision restantes. Chaque entrée inclut les éléments suivants :
  - dateTime : date et heure civiles locales (year, month, day, hours, minutes, seconds et utcOffset) dans le fuseau horaire de l'emplacement.
  - indexes[] : IQA universel et, si disponible, l'IQA local (displayName, value, valueDisplay, category et dominantPollutant).
  - pollutants[] : renseigné lorsque include_pollutant_concentration est défini sur true (displayName, fullName, concentration dans ppb ou µg/m³, et additionalInfo avec l'émission sources et l'état effects).
  - healthRecommendations : conseils pour generalPopulation, elderly, lungDiseasePopulation, heartDiseasePopulation, athletes, pregnantWomen et children.
- attribution : attribution que vous devez afficher avec les données sur la qualité de l'air.
pollen : renseigné lorsque POLLEN est demandé :
- dailyForecast : prévisions de pollen pour la date demandée :
  - date : date du calendrier civil de la prévision.
  - categories[] : grandes catégories d'allergènes (Tree, Grass et Weed), chacune avec displayName, inSeason, l'indice universel de pollen index (échelle de 0 à 5, category et description) et healthRecommendations[].
  - plantSpecies[] : espèces de plantes allergènes spécifiques (comme le bouleau, l'ambroisie ou le cèdre du Japon), chacune avec code, displayName, family botanique, inSeason, l'indice universel de pollen index, la season de floraison typique et crossReactions.
- attribution : attribution que vous devez afficher avec les données sur le pollen.

Disponibilité partielle des fonctionnalités

Lorsqu'une requête inclut plusieurs fonctionnalités, chacune d'elles est évaluée et récupérée indépendamment. Si une fonctionnalité n'est pas disponible pour l'emplacement demandé, en dehors de sa période de disponibilité, ou si elle échoue temporairement alors qu'au moins une autre fonctionnalité réussit, la réponse renvoie les conteneurs de fonctionnalités disponibles et omet le conteneur indisponible ou défaillant. La requête échoue avec une erreur uniquement si toutes les fonctionnalités demandées échouent.

Pour en savoir plus sur les champs, consultez la documentation de référence sur lookup_weather.

Facturation et quotas

Chaque requête lookup_weather correspond à un événement facturable, même lorsque capabilities demande deux ou trois domaines environnementaux dans le même appel :

Une requête est facturée au niveau de SKU le plus élevé parmi les fonctionnalités qui aboutissent et sont renvoyées dans la réponse :
- Si la réponse inclut pollen ou un airQuality historique (un date avant aujourd'hui ou un hour passé dans le fuseau horaire de l'emplacement), la requête est facturée sous le SKU Maps Grounding Pro. Demander à la fois POLLEN et l'historique AIR_QUALITY dans un seul appel est toujours comptabilisé comme un seul événement facturable Pro.
- Sinon, la requête est facturée au titre du SKU Maps Grounding Essentials.
Si une fonctionnalité Pro est omise dans une requête multifonctionnalité (car elle n'est pas disponible pour l'emplacement, qu'elle se trouve en dehors de la période acceptée ou qu'elle échoue temporairement) et que seules les fonctionnalités Essentials sont renvoyées dans la réponse, la requête est facturée au SKU Essentials.

Le quota lookup_weather est de 300 requêtes par minute pour chaque projet, partagé par les deux SKU. Pour connaître les tarifs, consultez la grille tarifaire principale et la grille tarifaire pour l'Inde.