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, récentes et pertinentes par rapport à la zone géographique ou à la région générale spécifiée par l'utilisateur.

  • 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 : adaptez les recommandations et les informations en fonction des lieux fournis par les utilisateurs.

Premiers pas

Cet exemple montre comment intégrer l'ancrage à Google Maps dans votre application pour fournir des réponses précises et adaptées à la localisation aux requêtes des utilisateurs. Le prompt 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.

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="What are the best Italian restaurants within a 15-minute walk from here?",
    tools=[{
        "type": "google_maps",
        "latitude": 34.050481,
        "longitude": -118.248526
    }]
)

# Print the model's text response and annotations
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f"  - {annotation.name}: {annotation.url}")

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    input: "What are the best Italian restaurants within a 15-minute walk from here?",
    tools: [{
      type: "google_maps",
      latitude: 34.050481,
      longitude: -118.248526
    }]
  });

  // Print the model's text response and annotations
  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - {annotation.name}: {annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "What are the best Italian restaurants within a 15-minute walk from here?",
    "tools": [{
      "type": "google_maps",
      "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 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 indiqué.

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é" ou "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 se comporte 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, 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 et annotations : le modèle renvoie une réponse textuelle avec des annotations intégrées renvoyant aux sources Google Maps, ce qui permet aux développeurs d'afficher des citations.

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, grâce à la vaste base de données de Google Maps qui compte plus de 250 millions de lieux dans le monde entier.

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 voyages 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 géolocalisées 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.

Cas d'utilisation

L'ancrage avec Google Maps est compatible avec différents cas d'utilisation basés sur la localisation.

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.

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Is there a cafe near the corner of 1st and Main that has outdoor seating?",
    tools=[{
        "type": "google_maps",
        "latitude": 34.050481,
        "longitude": -118.248526
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f"  - {annotation.name}: {annotation.url}")

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    input: "Is there a cafe near the corner of 1st and Main that has outdoor seating?",
    tools: [{
      type: "google_maps",
      latitude: 34.050481,
      longitude: -118.248526
    }]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

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.

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Which family-friendly restaurants near here have the best playground reviews?",
    tools=[{
        "type": "google_maps",
        "latitude": 30.2672,
        "longitude": -97.7431
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f"  - {annotation.name}: {annotation.url}")

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    input: "Which family-friendly restaurants near here have the best playground reviews?",
    tools: [{
      type: "google_maps",
      latitude: 30.2672,
      longitude: -97.7431
    }]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

Aide à la planification d'itinéraires

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

Python

# This will only work for SDK newer than 2.0.0
from google import genai

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."

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input=prompt,
    tools=[{
        "type": "google_maps",
        "latitude": 37.78193,
        "longitude": -122.40476
    }]
)
# ... code to process response

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    input: "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: [{
      type: "google_maps",
      latitude: 37.78193,
      longitude: -122.40476
    }]
  });
}

main();

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "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": [{
      "type": "google_maps",
      "latitude": 37.78193,
      "longitude": -122.40476
    }]
  }'

Conditions d'utilisation du service

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

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

Pour chaque résultat ancré Google Maps, vous recevrez des annotations de source sur les blocs de contenu de l'étape model_output qui étayent chaque réponse. Les métadonnées suivantes sont renvoyées :

  • URL source
  • nom

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 soutiennent. 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 annotation de source, 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 de Google Maps.
  • Affichez le nom de la source fourni dans la réponse.
  • Associez la source à l'aide de url à partir de l'annotation.

Consignes relatives à 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 casse de Google Maps.
    • Ne pas envelopper 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".

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.

Bonnes pratiques

  • Indiquez la position de l'utilisateur : pour obtenir les réponses les plus pertinentes et personnalisées, incluez toujours latitude et longitude dans la configuration de votre outil google_maps 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é.
  • 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": [{"type": "google_maps"}]) que lorsqu'une requête présente un contexte géographique clair, afin d'optimiser les performances et les coûts.

Limites

  • L'ancrage avec Google Maps n'est actuellement disponible qu'en anglais pour les requêtes et les réponses.
  • Il est possible que l'outil ne soit pas disponible dans toutes les régions.
  • Les résultats peuvent varier en fonction de la précision de la localisation et des données Maps disponibles.
  • Couverture géographique : l'ancrage avec Google Maps est disponible dans le monde entier.
  • É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 varient selon la génération du modèle :

  • Modèles Gemini 3 : votre projet est facturé pour chaque requête de recherche que le modèle décide d'exécuter. Un seul prompt de recherche (votre requête API adressée 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 comptabilisé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. Une requête n'est facturée que si l'invite 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.

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 :

Modèle Ancrage avec Google Maps
Gemini 3.5 Flash ✔️
Preview Gemini 3.1 Pro ✔️
Gemini 3.1 Flash-Lite ✔️
Preview Gemini 3 Flash ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️

Combinaisons d'outils compatibles

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

Étape suivante