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 est liée à des données Maps, le modèle Gemini exploite Google Maps pour fournir des réponses factuellement exactes et récentes, pertinentes pour le lieu ou la zone géographique générale spécifiés par l'utilisateur.

  • 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 lieux fournis par l'utilisateur.
  • Informations contextuelles et widgets : utilisez des jetons de contexte pour afficher des widgets Google Maps interactifs à côté du contenu généré.

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. L'invite demande des recommandations locales avec une position utilisateur facultative, ce qui permet au modèle Gemini d'utiliser les données Google Maps.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    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

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

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    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

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-flash-preview",
    "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 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 le lieu 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. Il s'agit d'un outil de recherche textuelle qui 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 le lieu 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 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 et, éventuellement, d'afficher un widget Google Maps contextuel.

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 Google Maps de 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 exactes à des 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 du lieu 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.

Cas d'utilisation

L'ancrage avec Google Maps est compatible avec différents cas d'utilisation géolocalisés.

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

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    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

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

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    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

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    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

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

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    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();

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.

Python

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-flash-preview",
    input=prompt,
    tools=[{
        "type": "google_maps",
        "latitude": 37.78193,
        "longitude": -122.40476,
        "enable_widget": True
    }]
)
# ... code to process response and widget token

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    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,
      enableWidget: true
    }],
});

REST

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-flash-preview",
    "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,
      "enable_widget": true
    }]
  }'

Conditions d'utilisation du service

Cette section décrit les conditions 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é de Google Maps, vous recevrez des annotations de source sur les blocs de contenu de l'étape model_output qui prennent en charge chaque réponse. Les métadonnées suivantes sont renvoyées :

  • URL de la source
  • nom

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é de 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 textuelle de Google Maps .
  • Affichez le nom de la source fourni dans la réponse.
  • Créez un lien vers la source à l'aide de l'url de l'annotation.

Consignes d'attribution textuelle de 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".

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

  • Fournissez la position de l'utilisateur : pour obtenir les réponses les plus pertinentes et personnalisées, incluez toujours la latitude et la longitude dans la configuration de votre outil google_maps lorsque la position de l'utilisateur est connue.
  • Affichez le widget contextuel Google Maps : le widget contextuel est affiché à l'aide du jeton de contexte google_maps_widget_context_token, qui est renvoyé dans la réponse de l'API Gemini et peut être utilisé pour afficher du contenu visuel à partir de Google Maps.
  • 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'option lorsque vous n'en avez pas besoin : l'ancrage avec Google Maps est désactivé par défaut. Ne l'activez ("tools": [{"type": "google_maps"}]) que lorsqu'une requête a un contexte géographique clair, afin d'optimiser les performances et les coûts.

Limites

  • L'ancrage avec Google Maps n'est actuellement compatible qu'avec les requêtes et les réponses en anglais.
  • L'outil peut ne pas être disponible dans toutes les régions.
  • Les résultats peuvent varier en fonction de la précision de la position 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 sont basés sur les requêtes. Le tarif actuel est de 25 $ par 1 000 prompts ancrés. 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 invite renvoie au moins un résultat ancré de 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 :

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

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 sur les combinaisons d'outils.

Étape suivante