Messa a terra con Google Maps

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

  • Risposte accurate e basate sulla località: sfrutta i dati estesi e attuali di Google Maps per le query geograficamente specifiche.
  • Personalizzazione avanzata: personalizza i consigli e le informazioni in base alle località fornite dall'utente.
  • Informazioni e widget contestuali: token di contesto per il rendering di widget interattivi di Google Maps insieme ai contenuti generati.

Inizia

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

// 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-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

# 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' \
  -H "Api-Revision: 2026-05-20" \
  -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
    }]
  }'

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 origine 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 località fornita.

In genere, la procedura prevede i seguenti passaggi:

  1. Query utente: un utente invia una query alla tua applicazione, che potrebbe includere un 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 la latitude e la 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 ("nelle vicinanze") utilizzeranno le coordinate, mentre è improbabile che le query specifiche o non locali siano influenzate dalla località esplicita.
  3. Recupero dei dati: il servizio Grounding con Google Maps esegue una query su Google Maps per recuperare informazioni pertinenti (ad es. luoghi, recensioni, foto, indirizzi, orari di apertura).
  4. Generazione basata su dati di fatto: i dati di Maps recuperati vengono utilizzati per informare la risposta del modello Gemini, garantendo accuratezza e pertinenza fattuali.
  5. Risposta e annotazioni: il modello restituisce una risposta di testo con annotazioni in linea che rimandano alle fonti di Google Maps, consentendo agli sviluppatori di visualizzare le citazioni e, facoltativamente, di eseguire il rendering di un widget contestuale di Google Maps.

Perché e quando utilizzare Grounding con Google Maps

Grounding con Google Maps è ideale per le applicazioni che richiedono informazioni accurate, aggiornate e specifiche per la località. 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:

  • Fornire risposte complete e accurate a domande specifiche per la località.
  • Creare pianificatori di viaggi conversazionali e guide locali.
  • Consigliare punti di interesse in base alla località e alle preferenze dell'utente, ad esempio ristoranti o negozi.
  • Creare esperienze basate sulla località per servizi social, di vendita al dettaglio o di consegna di cibo.

Grounding con Google Maps è ideale per i casi d'uso in cui la vicinanza e i dati fattuali attuali sono fondamentali, ad esempio per trovare il "miglior bar nelle vicinanze" o ottenere indicazioni stradali.

Casi d'uso

Grounding con Google Maps supporta una serie di casi d'uso basati sulla località.

Gestire le domande specifiche per i luoghi

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

// 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-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();

Fornire personalizzazione basata sulla località

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

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

// 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-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();

Aiutare a pianificare gli itinerari

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

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

// 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-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
    }]
  });
}

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' \
  -H "Api-Revision: 2026-05-20" \
  -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
    }]
  }'

Requisiti per l'utilizzo del servizio

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

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

Con ogni risultato basato su Google Maps, riceverai annotazioni delle fonti nei blocchi di contenuti del passaggio model_output che supportano ogni risposta. Vengono restituiti i seguenti metadati:

  • URL di origine
  • Nome

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. Questi contenuti generati sono anche chiamati risultati basati su Google Maps.
  • Le fonti di Google Maps devono essere visualizzabili in un'interazione utente.

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

Per ogni annotazione della fonte, deve essere generata un'anteprima del link che soddisfi i seguenti requisiti:

  • Attribuisci ogni fonte a Google Maps seguendo le linee guida per l'attribuzione del testo di Google Maps.
  • Visualizza il nome della fonte fornito nella risposta.
  • Collega alla fonte utilizzando l'url dell'annotazione.

Linee guida per l'attribuzione del 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/minuscole 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".

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.

Best practice

  • Fornisci la località dell'utente: per ottenere le risposte più pertinenti e personalizzate, includi sempre latitude e longitude nella configurazione dello strumento google_maps quando la località dell'utente è nota.
  • Esegui il rendering del widget contestuale di Google Maps: il widget contestuale viene sottoposto a rendering utilizzando il token di contesto google_maps_widget_context_token, che viene restituito nella risposta dell'API Gemini e può essere utilizzato per eseguire il rendering di contenuti visivi da Google Maps.
  • 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.
  • Disattiva quando non è necessario: Grounding con Google Maps è disattivato per impostazione predefinita. Abilitalo ("tools": [{"type": "google_maps"}]) solo quando una query ha un contesto geografico chiaro, per ottimizzare il rendimento e i costi.

Limitazioni

  • Al momento, Grounding con Google Maps supporta solo prompt e risposte in lingua inglese.
  • Lo strumento potrebbe non essere disponibile in tutte le regioni.
  • I risultati possono variare in base all'accuratezza della località e ai dati di Maps disponibili.
  • Ambito geografico: Grounding con Google Maps è disponibile a livello globale.
  • Stato predefinito: lo strumento Grounding con Google Maps è disattivato per impostazione predefinita. Devi abilitarlo esplicitamente nelle richieste API.

Prezzi e limiti di frequenza

I prezzi di Grounding con Google Maps si basano sulle query. La tariffa attuale è di 25$per 1000 prompt con grounding. Il livello senza costi prevede anche fino a 500 richieste al giorno. Una richiesta viene conteggiata ai fini della quota solo quando un prompt restituisce correttamente almeno un risultato basato su Google Maps (ovvero risultati contenenti almeno una fonte di Google Maps). Se vengono inviate più query a Google Maps da una singola richiesta, viene conteggiata come una richiesta ai fini del limite di frequenza.

Per informazioni dettagliate sui prezzi, consulta la pagina dei prezzi dell'API Gemini.

Modelli supportati

I seguenti modelli supportano Grounding con Google Maps:

Modello Grounding con Google Maps
Gemini 3.1 Pro (anteprima) ✔️
Gemini 3.1 Flash-Lite ✔️
Gemini 3.1 Flash-Lite (anteprima) ✔️
Gemini 3 Flash (anteprima) ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️

Combinazioni di strumenti supportate

I modelli Gemini 3 supportano la combinazione di strumenti integrati (come Grounding con Google Maps) con strumenti personalizzati (chiamata di funzioni). Scopri di più nella pagina delle combinazioni di strumenti.

Passaggi successivi