Grounding con Google Maps

Grounding con Google Maps collega le funzionalità generative di Gemini ai dati ricchi, oggettivi e aggiornati di Google Maps. Questa funzionalità consente agli sviluppatori di incorporare facilmente funzionalità basate sulla posizione nelle loro applicazioni. Quando una query utente ha un contesto correlato ai dati di Maps, il modello Gemini sfrutta Google Maps per fornire risposte oggettive e aggiornate pertinenti alla posizione specificata dall'utente o all'area generale.

• Risposte accurate e basate sulla posizione:sfrutta i dati estesi e aggiornati di Google Maps per le query geograficamente specifiche.
• Personalizzazione avanzata: personalizza i consigli e le informazioni in base alle località fornite dagli utenti.

Inizia

Questo esempio mostra come integrare Grounding con Google Maps nella tua applicazione per fornire risposte accurate e basate sulla posizione alle query degli utenti. Il prompt chiede consigli locali con una posizione dell'utente facoltativa, consentendo al modello Gemini di utilizzare i dati di 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}
    }
  }
}'

Come funziona Grounding con Google Maps

Grounding con Google Maps integra l'API Gemini con l'ecosistema Google Geo utilizzando l'API di Google Maps come fonte di grounding. Quando la query di un utente contiene un contesto geografico, il modello Gemini può richiamare lo strumento Grounding con Google Maps. Il modello può quindi generare risposte basate sui dati di Google Maps pertinenti alla posizione fornita.

In genere, la procedura prevede:

1. Query dell'utente: un utente invia una query alla tua applicazione, potenzialmente incluso il contesto geografico (ad es. "bar nelle vicinanze", "musei a San Francisco").
2. Richiamo dello strumento:il modello Gemini, riconoscendo l'intento geografico, richiama lo strumento Grounding con Google Maps. Questo strumento può essere fornito facoltativamente con latitude e longitude dell'utente. Lo strumento è uno strumento di ricerca testuale e si comporta in modo simile alla ricerca su Maps, in quanto le query locali ("vicino a me") utilizzano le coordinate, mentre è improbabile che le query specifiche o non locali siano influenzate dalla posizione esplicita.
3. Recupero dei dati: il servizio Grounding con Google Maps esegue query su Google Maps per informazioni pertinenti (ad es. luoghi, recensioni, foto, indirizzi, orari di apertura).
4. Generazione fondata:i dati di Maps recuperati vengono utilizzati per informare la risposta del modello Gemini, garantendo accuratezza e pertinenza.
5. Risposta:il modello restituisce una risposta di testo che include citazioni di fonti di Google Maps.

Perché e quando utilizzare Grounding con Google Maps

Il grounding con Google Maps è ideale per le applicazioni che richiedono informazioni accurate, aggiornate e specifiche per la posizione. Migliora l'esperienza utente fornendo contenuti pertinenti e personalizzati supportati dall'ampio database di Google Maps di oltre 250 milioni di luoghi in tutto il mondo.

Devi utilizzare Grounding con Google Maps quando la tua applicazione deve:

• Fornisci risposte complete e accurate alle domande specifiche per area geografica.
• Crea agenti di viaggio e guide locali conversazionali.
• Consiglia punti di interesse in base alla posizione e alle preferenze dell'utente, come ristoranti o negozi.
• Crea esperienze basate sulla posizione per servizi social, di vendita al dettaglio o di consegna di cibo.

La base con Google Maps eccelle nei casi d'uso in cui la vicinanza e i dati fattuali attuali sono fondamentali, ad esempio per trovare il "miglior bar vicino a me" o ricevere indicazioni stradali.

Metodi e parametri dell'API

Il grounding con Google Maps viene esposto tramite l'API Gemini come strumento all'interno del metodo generateContent. Puoi attivare e configurare Grounding con Google Maps includendo un oggetto googleMaps nel parametro tools della tua richiesta.

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

Inoltre, lo strumento supporta il passaggio della posizione contestuale come toolConfig.

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

Informazioni sulla risposta di grounding

Quando una risposta viene generata correttamente con i dati di Google Maps, la risposta include un campo groundingMetadata. Questi dati strutturati sono essenziali per verificare le rivendicazioni e creare un'esperienza di citazione avanzata nella tua applicazione, nonché per soddisfare i requisiti di utilizzo del servizio.

{
  "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 restituisce le seguenti informazioni con groundingMetadata:

• groundingChunks: array di oggetti contenenti le origini maps (uri, placeId e title).
• groundingSupports: Array di blocchi per collegare il testo della risposta del modello alle fonti in groundingChunks. Ogni blocco collega un intervallo di testo (definito da startIndex e endIndex) a uno o più groundingChunkIndices. Questa è la chiave per creare citazioni in linea.

Per uno snippet di codice che mostra come eseguire il rendering delle citazioni in linea nel testo, consulta l'esempio nella documentazione di Grounding con la Ricerca Google.

Casi d'uso

Il grounding con Google Maps supporta una serie di casi d'uso basati sulla posizione. Gli esempi seguenti mostrano come diversi prompt e parametri possono sfruttare Grounding con Google Maps. Le informazioni nei Risultati fondati di Google Maps potrebbero differire dalle condizioni effettive.

Gestione delle domande specifiche per luogo

Poni domande dettagliate su un luogo specifico per ottenere risposte basate sulle recensioni degli utenti di Google e su altri dati di 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}
    }
  }
}'

Fornire personalizzazione basata sulla posizione

Ricevi consigli personalizzati in base alle preferenze di un utente e a una specifica area geografica.

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

Aiuto con la pianificazione dell'itinerario

Genera piani di più giorni con indicazioni stradali e informazioni su varie località, perfetti per le applicazioni di viaggio.

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

Requisiti per l'utilizzo dei servizi

Questa sezione descrive i requisiti di utilizzo del servizio per Grounding con Google Maps.

Informa l'utente dell'utilizzo delle fonti di Google Maps

Per ogni risultato fondato di Google Maps, riceverai le fonti in groundingChunks che supportano ogni risposta. Vengono restituiti anche i seguenti metadati:

• source uri
• titolo
• ID

Quando presenti i risultati di Grounding con Google Maps, devi specificare le fonti di Google Maps associate e informare gli utenti di quanto segue:

• Le fonti di Google Maps devono seguire immediatamente i contenuti generati che supportano le fonti. Questi contenuti generati sono anche chiamati Risultato fondato di Google Maps.
• Le fonti di Google Maps devono essere visualizzabili con una sola interazione dell'utente.

Visualizzare le fonti di Google Maps con i link di Google Maps

Per ogni origine in groundingChunks e in grounding_chunks.maps.placeAnswerSources.reviewSnippets, deve essere generata un'anteprima del link in base ai seguenti requisiti:

• Attribuisci ogni sorgente a Google Maps seguendo le linee guida per l'attribuzione del testo di Google Maps.
• Mostra il titolo della fonte fornito nella risposta.
• Link alla fonte utilizzando uri o googleMapsUri dalla risposta.

Queste immagini mostrano i requisiti minimi per la visualizzazione delle fonti e dei link a Maps.

Puoi comprimere la visualizzazione delle fonti.

(Facoltativo) Migliora l'anteprima del link con contenuti aggiuntivi, ad esempio:

• Una favicon di Google Maps viene inserita prima dell'attribuzione del testo di Google Maps.
• Una foto dall'URL di origine (og:image).

Per ulteriori informazioni su alcuni dei nostri fornitori di dati di Google Maps e sui relativi termini di licenza, consulta le note legali di Google Maps e Google Earth.

Linee guida per l'attribuzione di testo di Google Maps

Quando attribuisci le fonti a Google Maps nel testo, segui queste linee guida:

• Non modificare in alcun modo il testo Google Maps:
  • Non modificare le maiuscole di Google Maps.
  • Non mandare a capo Google Maps su più righe.
  • Non localizzare Google Maps in un'altra lingua.
  • Impedisci ai browser di tradurre Google Maps utilizzando l'attributo HTML translate="no".
• Formatta il testo di Google Maps come descritto nella tabella seguente:

CSS di esempio

Il seguente CSS esegue il rendering di Google Maps con lo stile tipografico e il colore appropriati su uno sfondo bianco o chiaro.

@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 luogo e ID recensione

I dati di Google Maps includono l'ID luogo e l'ID recensione. Potresti memorizzare nella cache, archiviare ed esportare i seguenti dati delle risposte:

• placeId
• reviewId

Le limitazioni alla memorizzazione nella cache previste dai Termini del grounding con Google Maps non si applicano.

Attività e territorio vietati

Grounding con Google Maps prevede ulteriori limitazioni per determinati contenuti e attività per mantenere una piattaforma sicura e affidabile. Oltre alle limitazioni all'utilizzo riportate nei Termini:

• Non utilizzerai Grounding con Google Maps per attività ad alto rischio, inclusi i servizi di risposta alle emergenze.
• Non distribuirai né commercializzerai la tua applicazione che offre Grounding con Google Maps in un Territorio vietato. Per ulteriori informazioni, consulta Territori vietati di Google Maps Platform. L'elenco dei Territori vietati potrebbe essere aggiornato di tanto in tanto.

Best practice

• Fornisci la posizione dell'utente:per ottenere risposte più pertinenti e personalizzate, includi sempre user_location (latitudine e longitudine) nella configurazione googleMapsGrounding quando la posizione dell'utente è nota.
• Informa gli utenti finali:informa chiaramente gli utenti finali che i dati di Google Maps vengono utilizzati per rispondere alle loro query, soprattutto quando lo strumento è abilitato.
• Monitora la latenza:per le applicazioni conversazionali, assicurati che la latenza P95 per le risposte basate su dati reali rimanga entro soglie accettabili per mantenere un'esperienza utente fluida.
• Disattivazione quando non è necessario: il grounding con Google Maps è disattivato per impostazione predefinita. Attivalo ("tools": [{"googleMaps": {}}]) solo quando una query ha un contesto geografico chiaro, per ottimizzare prestazioni e costi.

Limitazioni

• Ambito geografico:il grounding con Google Maps è disponibile a livello globale
• Supporto del modello: consulta la sezione Modelli supportati.
• Input/output multimodali: il grounding con Google Maps al momento non supporta input o output multimodali oltre al testo.
• Stato predefinito:lo strumento Grounding con Google Maps è disattivato per impostazione predefinita. Devi abilitarla esplicitamente nelle richieste API.

Prezzi e limiti di frequenza

I prezzi di Grounding con Google Maps variano a seconda della generazione del modello:

• Gemini 3 e modelli più recenti:il tuo progetto viene fatturato per ogni query di ricerca che il modello decide di eseguire, con 5000 richieste senza costi al mese condivise tra tutti i modelli Gemini 3 e più recenti, e poi 14$per 1000 query di ricerca. Un singolo prompt di ricerca (la tua richiesta API al modello) potrebbe comportare l'esecuzione di più query di ricerca da parte del modello per trovare le informazioni necessarie. Ciascuna di queste query viene conteggiata come utilizzo fatturabile dello strumento.
• Gemini 2.5 e modelli precedenti: il tuo progetto viene fatturato per prompt di ricerca (25 $ per 1000 prompt basati su dati reali). Una richiesta viene fatturata solo se il prompt restituisce correttamente almeno un risultato fondato di Google Maps, indipendentemente dal numero di singole query di ricerca eseguite internamente dal modello per ottenere quel risultato.

La quota per Grounding con Google Maps in genere è in linea con i limiti di frequenza del modello Gemini sottostante. Per informazioni più dettagliate sui prezzi, consulta la pagina dei prezzi dell'API Gemini.

Modelli supportati

I seguenti modelli supportano Grounding con Google Maps:

Combinazioni di strumenti supportate

Puoi utilizzare Grounding con Google Maps con altri strumenti integrati come Grounding con la Ricerca Google (supportato su Gemini 3.5 Flash-Lite e modelli successivi) per gestire casi d'uso più complessi. I modelli Gemini 3 supportano anche la combinazione di questi strumenti integrati con strumenti personalizzati (chiamata di funzioni). Scopri di più nella pagina Combinazioni di strumenti.

Passaggi successivi

• Prova la funzionalità Grounding con la Ricerca Google nel cookbook dell'API Gemini.
• Scopri di più sugli altri strumenti disponibili.
• Per saperne di più sulle best practice per l'AI responsabile e sui filtri di sicurezza dell'API Gemini, consulta la guida alle impostazioni di sicurezza.