Messa a terra con Google Maps

Grounding con Google Maps collega le funzionalità generative di Gemini ai dati ricchi, reali 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 o all'area generale specificata dall'utente.

  • Risposte accurate e basate sulla posizione:sfrutta i dati estesi e aggiornati di Google Maps per le query geograficamente specifiche.
  • Personalizzazione avanzata: personalizza consigli e informazioni in base alle località fornite dagli utenti.
  • Informazioni e widget contestuali:token contestuali per visualizzare 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 posizione alle query degli utenti. Il prompt chiede consigli locali con una posizione utente facoltativa, consentendo al modello Gemini di utilizzare i dati di 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
    }]
  }'

Come funziona Grounding con Google Maps

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

La procedura in genere 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 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, 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 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 pianificatori di viaggi conversazionali e guide locali.
  • 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.

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

Casi d'uso

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

Gestione delle domande specifiche per un luogo

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

Fornire personalizzazione basata sulla posizione

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

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

Assistenza per la pianificazione dell'itinerario

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

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

Requisiti per l'utilizzo del servizio

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

Informare l'utente sull'utilizzo delle fonti di Google Maps

Per ogni risultato di Google Maps Grounded, 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 le fonti. Questi contenuti generati sono anche chiamati risultato basato su Google Maps.
  • Le fonti di Google Maps devono essere visualizzabili in una sola interazione dell'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 in base ai seguenti requisiti:

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

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.
    • 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 posizione dell'utente:per ottenere le risposte più pertinenti e personalizzate, includi sempre latitude e longitude nella configurazione dello strumento google_maps quando la posizione dell'utente è nota.
  • Esegui il rendering del widget contestuale di Google Maps: il widget contestuale viene eseguito il 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.
  • Disattivare quando non è necessario: il grounding con Google Maps è disattivato per impostazione predefinita. Attivala ("tools": [{"type": "google_maps"}]) solo quando una query ha un contesto geografico chiaro, per ottimizzare prestazioni e costi.

Limitazioni

  • Il grounding con Google Maps al momento 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 posizione e ai dati di Maps disponibili.
  • Ambito geografico: il grounding con Google Maps è disponibile a livello globale.
  • Stato predefinito:lo strumento Grounding con Google Maps è disattivato per impostazione predefinita. Devi abilitarla esplicitamente nelle richieste API.

Prezzi e limiti di frequenza

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

Per informazioni più 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
Anteprima di Gemini 3.1 Pro ✔️
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 Combinazioni di strumenti.

Passaggi successivi