Ancrage avec Google Maps

L'ancrage avec Google Maps associe 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 géolocalisation dans leurs applications. Lorsqu'une requête utilisateur a un contexte lié aux données Maps, le modèle Gemini exploite Google Maps pour fournir des réponses factuellement exactes et à jour, qui sont pertinentes pour l'emplacement spécifié par l'utilisateur ou la zone géographique générale.

• Réponses précises et géolocalisées : exploitez les données complètes et actuelles de Google Maps pour les requêtes géographiques spécifiques.
• Personnalisation améliorée : adaptez les recommandations et les informations en fonction des emplacements fournis par l'utilisateur.

Premiers pas

Cet exemple montre comment intégrer l'ancrage avec Google Maps dans 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 un emplacement utilisateur facultatif, 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.5-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.5-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.5-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 basées sur les données Google Maps pertinentes pour l'emplacement fourni.

Le 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é" ou "musées à San Francisco").
2. Appel d'outil : le modèle Gemini, reconnaissant l'intention géographique, appelle l'outil d'ancrage avec Google Maps. Cet outil peut éventuellement être fourni avec la latitude et la longitude de l'utilisateur. L'outil est un outil de recherche textuelle et se comporte de la même manière que la recherche dans Maps. Les requêtes locales ("à proximité") utilisent les coordonnées, tandis que les requêtes spécifiques ou non locales sont peu susceptibles d'être influencées par l'emplacement 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, des horaires d'ouverture).
4. Génération ancrée : les données Maps récupérées sont utilisées pour informer 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 des 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. Il 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 :

• Fournir des réponses complètes et précises aux questions géographiques spécifiques.
• Créer des planificateurs de voyage conversationnels et des guides locaux.
• Recommander des points d'intérêt en fonction de l'emplacement et des préférences de l'utilisateur, comme des restaurants ou des magasins.
• Créer des expériences géolocalisées pour les services sociaux, de vente au détail ou de livraison de nourriture.

L'ancrage avec Google Maps excelle dans les cas d'utilisation où la proximité et les données factuelles actuelles sont essentielles, par exemple 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 generateContent méthode. Pour activer et configurer l'ancrage avec Google Maps, incluez un googleMaps objet dans le tools paramètre 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 avec les données Google Maps, elle inclut un groundingMetadata champ. Ces données structurées sont essentielles pour vérifier les affirmations et créer une expérience de citation enrichie 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 le groundingMetadata :

• groundingChunks: tableau d'objets contenant les sources maps (uri, placeId et title).
• groundingSupports: tableau de blocs permettant de connecter le texte de réponse du modèle aux sources dans groundingChunks. Chaque bloc associe une étendue de texte (définie par startIndex et endIndex) à un ou plusieurs groundingChunkIndices. Il s'agit de la clé pour créer des citations intégré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 géolocalisés. Les exemples suivants montrent comment différentes requêtes et différents paramètres peuvent exploiter l'ancrage avec Google Maps. Les informations contenues 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.5-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.5-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.5-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 localisation

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.5-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.5-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.5-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}
    }
  }
}'

Aider à 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.5-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.5-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.5-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}
  }
  }
}'

Exigences relatives à l'utilisation du service

Cette section décrit les exigences relatives à l'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 prennent en charge chaque réponse. Les métadonnées suivantes sont également renvoyées :

• URI source
• Titre
• ID

Lorsque vous présentez des résultats 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 de texte Google Maps .
• Affichez le titre de la source fourni dans la réponse.
• Créez un lien vers la source à l'aide de l'élément uri ou googleMapsUri de la réponse.

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

Vous pouvez réduire l'affichage des sources.

Facultatif : Améliorez l'aperçu du lien avec des contenus supplémentaires, tels que :

• Une icône Google Maps est insérée avant l'attribution de texte Google Maps.
• Une photo provenant de l'URL source (og:image).

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

Consignes d'attribution de texte Google Maps

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

• Ne modifiez en aucun cas le texte "Google Maps" :
  • Ne modifiez pas la casse de "Google Maps".
  • N'insérez pas "Google Maps" sur plusieurs lignes.
  • Ne traduisez 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 "Google Maps" comme décrit dans le tableau suivant :

Exemple d'élément CSS

L'élément 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 d'emplacement et l'ID d'avis. Vous pouvez mettre en cache, stocker et exporter les données de réponse suivantes :

• placeId
• reviewId

Les restrictions concernant la mise en cache dans les Conditions d'utilisation de l'ancrage avec Google Maps ne s'appliquent pas.

Activité et territoire interdits

L'ancrage avec Google Maps comporte 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 la section Territoires interdits sur Google Maps Platform. La liste des territoires interdits peut être mise à jour de temps à autre.

Bonnes pratiques

• Fournir l'emplacement de l'utilisateur : pour obtenir les réponses les plus pertinentes et personnalisées, incluez toujours user_location (latitude et longitude) dans votre configuration googleMapsGrounding lorsque l'emplacement de l'utilisateur est connu.
• Informer les utilisateurs finaux : informez 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 des réponses ancrées reste dans des seuils acceptables afin de maintenir une expérience utilisateur fluide.
• Désactiver lorsque ce n'est pas nécessaire : l'ancrage avec Google Maps est désactivé par défaut. Ne l'activez ("tools": [{"googleMaps": {}}]) que lorsqu'une requête a 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'est actuellement pas compatible avec 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 API.

Tarifs et limites de débit

Les tarifs de l'ancrage avec Google Maps sont basés sur les requêtes. Le tarif actuel est de 25 $ par 1 000 requêtes ancrées. Le niveau sans frais propose également jusqu'à 500 requêtes par jour. Une requête n'est comptabilisée dans le quota que lorsqu'une requête renvoie au moins un résultat ancré Google Maps (c'est-à-dire des résultats contenant au moins une source Google Maps). Si plusieurs requêtes sont envoyées à Google Maps à partir d'une seule requête, elles sont comptabilisées comme une seule requête dans la limite de débit.

Pour en savoir plus sur les tarifs, consultez la page Tarifs de l'API Gemini.

Modèles compatibles

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

Combinaisons d'outils compatibles

Les modèles Gemini 3 sont compatibles avec la combinaison d'outils intégrés (comme l'ancrage avec Google Maps) et d'outils personnalisés (appel de fonction). Pour en savoir plus, consultez la page Combinaisons d'outils.

Étape suivante

• Essayez l'ancrage avec la recherche Google dans le livre de recettes de l'API Gemini.
• Découvrez 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 Paramètres de sécurité.