Ancrage avec Google Maps

L'ancrage avec Google Maps permet d'associer les capacités génératives de Gemini aux données riches, factuelles et à jour de Google Maps. Cette fonctionnalité permet aux développeurs d'intégrer facilement des fonctionnalités de localisation dans leurs applications. Lorsqu'une requête utilisateur comporte un contexte lié aux données Maps, le modèle Gemini s'appuie sur Google Maps pour fournir des réponses factuelles et récentes qui sont pertinentes pour la zone géographique spécifiée par l'utilisateur ou la zone géographique générale.

• Des réponses précises et géolocalisées : exploitez les données actuelles et exhaustives de Google Maps pour les requêtes géographiques spécifiques.
• Personnalisation améliorée : personnalisez les recommandations et les informations en fonction des lieux fournis par les utilisateurs.

Commencer

Cet exemple montre comment intégrer l'ancrage avec Google Maps à votre application pour fournir des réponses précises et géolocalisées aux requêtes des utilisateurs. La requête demande des recommandations locales avec une position de l'utilisateur facultative, ce qui permet au modèle Gemini d'utiliser les données Google Maps.

from google import genai
from google.genai import types

client = genai.Client()

prompt = "What are the best Italian restaurants within a 15-minute walk from here?"

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=prompt,
    config=types.GenerateContentConfig(
        # Turn on grounding with Google Maps
        tools=[types.Tool(google_maps=types.GoogleMaps())],
        # Optionally provide the relevant location context (this is in Los Angeles)
        tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
            lat_lng=types.LatLng(
                latitude=34.050481, longitude=-118.248526))),
    ),
)

print("Generated Response:")
print(response.text)

if grounding := response.candidates[0].grounding_metadata:
  if grounding.grounding_chunks:
    print('-' * 40)
    print("Sources:")
    for chunk in grounding.grounding_chunks:
      print(f'- [{chunk.maps.title}]({chunk.maps.uri})')

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function generateContentWithMapsGrounding() {
  const response = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    contents: "What are the best Italian restaurants within a 15-minute walk from here?",
    config: {
      // Turn on grounding with Google Maps
      tools: [{ googleMaps: {} }],
      toolConfig: {
        retrievalConfig: {
          // Optionally provide the relevant location context (this is in Los Angeles)
          latLng: {
            latitude: 34.050481,
            longitude: -118.248526,
          },
        },
      },
    },
  });

  console.log("Generated Response:");
  console.log(response.text);

  const grounding = response.candidates[0]?.groundingMetadata;
  if (grounding?.groundingChunks) {
    console.log("-".repeat(40));
    console.log("Sources:");
    for (const chunk of grounding.groundingChunks) {
      if (chunk.maps) {
        console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
      }
    }
  }
}

generateContentWithMapsGrounding();

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "What are the best Italian restaurants within a 15-minute walk from here?"
    }]
  }],
  "tools": [{"googleMaps": {}}],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {"latitude": 34.050481, "longitude": -118.248526}
    }
  }
}'

Fonctionnement de l'ancrage avec Google Maps

L'ancrage avec Google Maps intègre l'API Gemini à l'écosystème Google Geo en utilisant l'API Google Maps comme source d'ancrage. Lorsque la requête d'un utilisateur contient un contexte géographique, le modèle Gemini peut appeler l'outil d'ancrage avec Google Maps. Le modèle peut ensuite générer des réponses ancrées dans les données Google Maps pertinentes pour le lieu fourni.

Ce processus implique généralement les étapes suivantes :

1. Requête utilisateur : un utilisateur envoie une requête à votre application, qui peut inclure un contexte géographique (par exemple, "cafés à proximité", "musées à San Francisco").
2. Invocation de l'outil : le modèle Gemini, qui reconnaît l'intention géographique, invoque l'outil d'ancrage avec Google Maps. Cet outil peut éventuellement être fourni avec les latitude et longitude de l'utilisateur. Cet outil de recherche textuelle fonctionne de la même manière que la recherche dans Maps. Les requêtes locales ("près de moi") utilisent les coordonnées, tandis que les requêtes spécifiques ou non locales sont peu susceptibles d'être influencées par la position explicite.
3. Récupération des données : le service d'ancrage avec Google Maps interroge Google Maps pour obtenir des informations pertinentes (par exemple, des lieux, des avis, des photos, des adresses ou des horaires d'ouverture).
4. Génération ancrée : les données Maps récupérées sont utilisées pour étayer la réponse du modèle Gemini, ce qui garantit l'exactitude et la pertinence des faits.
5. Réponse : le modèle renvoie une réponse textuelle, qui inclut des citations de sources Google Maps.

Pourquoi et quand utiliser l'ancrage avec Google Maps

L'ancrage avec Google Maps est idéal pour les applications qui nécessitent des informations précises, à jour et spécifiques à un lieu. Elle améliore l'expérience utilisateur en fournissant des contenus pertinents et personnalisés, basés sur la vaste base de données de Google Maps qui compte plus de 250 millions de lieux dans le monde.

Vous devez utiliser l'ancrage avec Google Maps lorsque votre application doit :

• Fournissez des réponses complètes et précises aux questions spécifiques à une zone géographique.
• Créez des planificateurs de voyage et des guides locaux conversationnels.
• Recommander des points d'intérêt en fonction de la position et des préférences de l'utilisateur (restaurants ou magasins, par exemple).
• Créez des expériences basées sur la localisation pour les services sociaux, de vente au détail ou de livraison de repas.

L'ancrage avec Google Maps excelle dans les cas d'utilisation où la proximité et les données factuelles actuelles sont essentielles, comme pour trouver le "meilleur café à proximité" ou obtenir un itinéraire.

Méthodes et paramètres de l'API

L'ancrage avec Google Maps est exposé via l'API Gemini en tant qu'outil dans la méthode generateContent. Pour activer et configurer l'ancrage avec Google Maps, incluez un objet googleMaps dans le paramètre tools de votre requête.

{
  "contents": [{
    "parts": [
      {"text": "Restaurants near Times Square."}
    ]
  }],
  "tools":  { "googleMaps": {} }
}

De plus, l'outil permet de transmettre l'emplacement contextuel en tant que toolConfig.

{
  "contents": [{
    "parts": [
      {"text": "Restaurants near here."}
    ]
  }],
  "tools":  { "googleMaps": {} },
  "toolConfig":  {
    "retrievalConfig": {
      "latLng": {
        "latitude": 40.758896,
        "longitude": -73.985130
      }
    }
  }
}

Comprendre la réponse d'ancrage

Lorsqu'une réponse est correctement ancrée dans les données Google Maps, elle inclut un champ groundingMetadata. Ces données structurées sont essentielles pour valider les affirmations et créer une expérience de citation riche dans votre application, ainsi que pour répondre aux exigences d'utilisation du service.

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "CanteenM is an American restaurant with..."
          }
        ],
        "role": "model"
      },
      "groundingMetadata": {
        "groundingChunks": [
          {
            "maps": {
              "uri": "https://maps.google.com/?cid=13100894621228039586",
              "title": "Heaven on 7th Marketplace",
              "placeId": "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
            },
            // repeated ...
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 0,
              "endIndex": 79,
              "text": "CanteenM is an American restaurant with a 4.6-star rating and is open 24 hours."
            },
            "groundingChunkIndices": [0]
          },
          // repeated ...
        ],
        "webSearchQueries": [
          "restaurants near me"
        ]
      }
    }
  ]
}

L'API Gemini renvoie les informations suivantes avec groundingMetadata :

• groundingChunks : tableau d'objets contenant les sources maps (uri, placeId et title).
• groundingSupports : tableau de blocs permettant de relier le texte de la réponse du modèle aux sources dans groundingChunks. Chaque bloc associe une plage de texte (définie par startIndex et endIndex) à un ou plusieurs groundingChunkIndices. C'est la clé pour créer des citations insérées.

Pour obtenir un extrait de code montrant comment afficher des citations intégrées dans du texte, consultez l'exemple dans la documentation sur l'ancrage avec la recherche Google.

Cas d'utilisation

L'ancrage avec Google Maps est compatible avec différents cas d'utilisation basés sur la localisation. Les exemples suivants montrent comment différents paramètres et requêtes peuvent exploiter l'ancrage avec Google Maps. Les informations figurant dans les Résultats ancrés Google Maps peuvent différer des conditions réelles.

Gérer les questions spécifiques à un lieu

Posez des questions détaillées sur un lieu spécifique pour obtenir des réponses basées sur les avis des utilisateurs Google et d'autres données Maps.

from google import genai
from google.genai import types

client = genai.Client()

prompt = "Is there a cafe near the corner of 1st and Main that has outdoor seating?"

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=prompt,
    config=types.GenerateContentConfig(
        # Turn on the Maps tool
        tools=[types.Tool(google_maps=types.GoogleMaps())],

        # Provide the relevant location context (this is in Los Angeles)
        tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
            lat_lng=types.LatLng(
                latitude=34.050481, longitude=-118.248526))),
    ),
)

print("Generated Response:")
print(response.text)

if grounding := response.candidates[0].grounding_metadata:
  if chunks := grounding.grounding_chunks:
    print('-' * 40)
    print("Sources:")
    for chunk in chunks:
      print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
  ```

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function run() {
  const prompt = "Is there a cafe near the corner of 1st and Main that has outdoor seating?";

  const response = await ai.models.generateContent({
    model: 'gemini-3.8-flash',
    contents: prompt,
    config: {
      // Turn on the Maps tool
      tools: [{googleMaps: {}}],
      // Provide the relevant location context (this is in Los Angeles)
      toolConfig: {
        retrievalConfig: {
          latLng: {
            latitude: 34.050481,
            longitude: -118.248526
          }
        }
      }
    },
  });

  console.log("Generated Response:");
  console.log(response.text);

  const chunks = response.candidates[0].groundingMetadata?.groundingChunks;
  if (chunks) {
    console.log('-'.repeat(40));
    console.log("Sources:");
    for (const chunk of chunks) {
      if (chunk.maps) {
        console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
      }
    }
  }
}

run();

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "Is there a cafe near the corner of 1st and Main that has outdoor seating?"
    }]
  }],
  "tools": [{"googleMaps": {}}],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {"latitude": 34.050481, "longitude": -118.248526}
    }
  }
}'

Fournir une personnalisation basée sur la position

Obtenez des recommandations adaptées aux préférences d'un utilisateur et à une zone géographique spécifique.

from google import genai
from google.genai import types

client = genai.Client()

prompt = "Which family-friendly restaurants near here have the best playground reviews?"

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=prompt,
    config=types.GenerateContentConfig(
      tools=[types.Tool(google_maps=types.GoogleMaps())],
      tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
          # Provide the location as context; this is Austin, TX.
          lat_lng=types.LatLng(
              latitude=30.2672, longitude=-97.7431))),
    ),
)

print("Generated Response:")
print(response.text)

if grounding := response.candidates[0].grounding_metadata:
  if chunks := grounding.grounding_chunks:
    print('-' * 40)
    print("Sources:")
    for chunk in chunks:
      print(f'- [{chunk.maps.title}]({chunk.maps.uri})')

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function run() {
  const prompt = "Which family-friendly restaurants near here have the best playground reviews?";

  const response = await ai.models.generateContent({
    model: 'gemini-3.8-flash',
    contents: prompt,
    config: {
      tools: [{googleMaps: {}}],
      toolConfig: {
        retrievalConfig: {
          // Provide the location as context; this is Austin, TX.
          latLng: {
            latitude: 30.2672,
            longitude: -97.7431
          }
        }
      }
    },
  });

  console.log("Generated Response:");
  console.log(response.text);

  const chunks = response.candidates[0].groundingMetadata?.groundingChunks;
  if (chunks) {
    console.log('-'.repeat(40));
    console.log("Sources:");
    for (const chunk of chunks) {
      if (chunk.maps) {
        console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
      }
    }
  }
}

run();

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "Which family-friendly restaurants near here have the best playground reviews?"
    }],
  }],
  "tools": [{"googleMaps": {}}],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {"latitude": 30.2672, "longitude": -97.7431}
    }
  }
}'

Aide à la planification d'itinéraires

Générez des plans sur plusieurs jours avec des itinéraires et des informations sur différents lieux, parfaits pour les applications de voyage.

from google import genai
from google.genai import types

client = genai.Client()

prompt = "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner."

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=prompt,
    config=types.GenerateContentConfig(
      tools=[types.Tool(google_maps=types.GoogleMaps())],
      tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
          # Provide the location as context, this is in San Francisco.
          lat_lng=types.LatLng(
              latitude=37.78193, longitude=-122.40476))),
    ),
)

print("Generated Response:")
print(response.text)

if grounding := response.candidates[0].grounding_metadata:
  if grounding.grounding_chunks:
    print('-' * 40)
    print("Sources:")
    for chunk in grounding.grounding_chunks:
      print(f'- [{chunk.maps.title}]({chunk.maps.uri})')

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function run() {
  const prompt = "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.";

  const response = await ai.models.generateContent({
    model: 'gemini-3.8-flash',
    contents: prompt,
    config: {
      tools: [{googleMaps: {}}],
      toolConfig: {
        retrievalConfig: {
          // Provide the location as context, this is in San Francisco.
          latLng: {
            latitude: 37.78193,
            longitude: -122.40476
          }
        }
      }
    },
  });

  console.log("Generated Response:");
  console.log(response.text);

  const groundingMetadata = response.candidates[0]?.groundingMetadata;
  if (groundingMetadata) {
    if (groundingMetadata.groundingChunks) {
      console.log('-'.repeat(40));
      console.log("Sources:");
      for (const chunk of groundingMetadata.groundingChunks) {
        if (chunk.maps) {
          console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
        }
      }
    }
  }
}

run();

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner."
    }]
  }],
  "tools": [{"googleMaps": {}}],
  "toolConfig": {
    "retrievalConfig": {
    "latLng": {"latitude": 37.78193, "longitude": -122.40476}
  }
  }
}'

Conditions d'utilisation des services

Cette section décrit les exigences d'utilisation du service pour l'ancrage avec Google Maps.

Informer l'utilisateur de l'utilisation des sources Google Maps

Pour chaque résultat ancré Google Maps, vous recevrez des sources dans groundingChunks qui étayent chaque réponse. Les métadonnées suivantes sont également renvoyées :

• URI source
• titre
• ID

Lorsque vous présentez des résultats issus de l'ancrage avec Google Maps, vous devez spécifier les sources Google Maps associées et informer vos utilisateurs des points suivants :

• Les sources Google Maps doivent suivre immédiatement le contenu généré qu'elles prennent en charge. Ce contenu généré est également appelé "résultat ancré Google Maps".
• Les sources Google Maps doivent être visibles en une seule interaction de l'utilisateur.

Afficher les sources Google Maps avec des liens Google Maps

Pour chaque source dans groundingChunks et dans grounding_chunks.maps.placeAnswerSources.reviewSnippets, un aperçu du lien doit être généré en respectant les exigences suivantes :

• Attribuez chaque source à Google Maps en suivant les Consignes d'attribution du texte Google Maps.
• Affichez le titre de la source fourni dans la réponse.
• Créez un lien vers la source à l'aide de uri ou googleMapsUri de la réponse.

Ces images montrent les exigences minimales pour afficher les liens vers les sources et Google Maps.

Vous pouvez réduire l'affichage des sources.

Facultatif : Améliorez l'aperçu du lien en ajoutant du contenu, par exemple :

• Un favicon Google Maps est inséré avant l'attribution textuelle Google Maps.
• Photo provenant de l'URL source (og:image).

Pour en savoir plus sur certains de nos fournisseurs de données Google Maps et sur les conditions de licence qu'ils appliquent, consultez les mentions légales de Google Maps et Google Earth.

Consignes concernant l'attribution de texte Google Maps

Lorsque vous attribuez des sources à Google Maps dans un texte, suivez ces consignes :

• Ne modifiez en aucun cas le texte "Google Maps" :
  • Ne modifiez pas la typographie de Google Maps.
  • N'insérez pas Google Maps sur plusieurs lignes.
  • Ne localisez pas Google Maps dans une autre langue.
  • Empêchez les navigateurs de traduire Google Maps en utilisant l'attribut HTML translate="no".
• Mettez en forme le texte de Google Maps comme décrit dans le tableau suivant :

Exemple d'élément CSS

Le code CSS suivant affiche Google Maps avec le style typographique et la couleur appropriés sur un arrière-plan clair ou blanc.

@import url('https://fonts.googleapis.com/css2?family=Roboto&display=swap');

.GMP-attribution {

font-family: Roboto, Sans-Serif;
font-style: normal;
font-weight: 400;
font-size: 1rem;
letter-spacing: normal;
white-space: nowrap;
color: #5e5e5e;
}

ID de lieu et ID d'avis

Les données Google Maps incluent l'ID de lieu et l'ID d'avis. Vous pouvez mettre en cache, stocker et exporter les données de réponse suivantes :

• placeId
• reviewId

Les restrictions de mise en cache des conditions d'utilisation de l'ancrage avec Google Maps ne s'appliquent pas.

Activité et territoire interdits

L'ancrage avec Google Maps est soumis à des restrictions supplémentaires pour certains contenus et activités afin de maintenir une plate-forme sûre et fiable. En plus des restrictions d'utilisation indiquées dans les Conditions d'utilisation :

• Vous n'utiliserez pas l'ancrage avec Google Maps pour des activités à haut risque, y compris les services d'urgence.
• Vous ne distribuerez ni ne commercialiserez votre application qui propose l'ancrage avec Google Maps dans un Territoire interdit. Pour en savoir plus, consultez Territoires interdits sur Google Maps Platform. La liste des territoires interdits peut être mise à jour de temps en temps.

Bonnes pratiques

• Fournissez la position de l'utilisateur : pour obtenir les réponses les plus pertinentes et personnalisées, incluez toujours user_location (latitude et longitude) dans la configuration googleMapsGrounding lorsque la position de l'utilisateur est connue.
• Informez les utilisateurs finaux : indiquez clairement à vos utilisateurs finaux que les données Google Maps sont utilisées pour répondre à leurs requêtes, en particulier lorsque l'outil est activé.
• Surveiller la latence : pour les applications conversationnelles, assurez-vous que la latence P95 pour les réponses ancrées reste dans les seuils acceptables afin de maintenir une expérience utilisateur fluide.
• Désactivez l'ancrage avec Google Maps lorsque vous n'en avez pas besoin : il est désactivé par défaut. Ne l'activez ("tools": [{"googleMaps": {}}]) que lorsqu'une requête présente un contexte géographique clair, afin d'optimiser les performances et les coûts.

Limites

• Couverture géographique : l'ancrage avec Google Maps est disponible dans le monde entier.
• Modèles compatibles : consultez la section Modèles compatibles.
• Entrées/Sorties multimodales : l'ancrage avec Google Maps n'accepte actuellement pas les entrées ni les sorties multimodales au-delà du texte.
• État par défaut : l'outil d'ancrage avec Google Maps est désactivé par défaut. Vous devez l'activer explicitement dans vos requêtes d'API.

Tarifs et limites de débit

Les tarifs de l'ancrage avec Google Maps varient selon la génération du modèle :

• Gemini 3 et modèles ultérieurs : votre projet est facturé pour chaque requête de recherche que le modèle décide d'exécuter, avec 5 000 requêtes sans frais par mois partagées entre tous les modèles Gemini 3 et ultérieurs, puis 14 $ pour 1 000 requêtes de recherche. Une seule requête de recherche (votre requête d'API au modèle) peut entraîner l'exécution de plusieurs requêtes de recherche par le modèle pour trouver les informations nécessaires. Chacune de ces requêtes est considérée comme une utilisation facturable de l'outil.
• Gemini 2.5 et modèles plus anciens : votre projet est facturé par requête de recherche (25 $ pour 1 000 requêtes ancrées). Une requête n'est facturée que si la requête renvoie au moins un résultat ancré Google Maps, quel que soit le nombre de requêtes de recherche individuelles effectuées en interne par le modèle pour obtenir ce résultat.

Le quota d'ancrage avec Google Maps correspond généralement aux limites de débit du modèle Gemini sous-jacent. Pour en savoir plus sur les tarifs, consultez la page des tarifs de l'API Gemini.

Modèles compatibles

Les modèles suivants sont compatibles avec l'ancrage avec Google Maps :

Combinaisons d'outils compatibles

Vous pouvez utiliser l'ancrage avec Google Maps avec d'autres outils intégrés, comme l'ancrage avec la recherche Google (pris en charge sur les modèles Gemini 3.5 Flash-Lite et versions ultérieures), pour des cas d'utilisation plus complexes. Les modèles Gemini 3 prennent également en charge la combinaison de ces outils intégrés avec des outils personnalisés (appel de fonction). Pour en savoir plus, consultez la page sur les combinaisons d'outils.

Étape suivante

• Essayez le livre de recettes sur l'ancrage avec la recherche Google dans l'API Gemini.
• En savoir plus sur les autres outils disponibles
• Pour en savoir plus sur les bonnes pratiques d'IA responsable et les filtres de sécurité de l'API Gemini, consultez le guide sur les paramètres de sécurité.