Grounding dengan Google Maps

Penyiapan dengan Google Maps menghubungkan kemampuan generatif Gemini dengan data Google Maps yang kaya, faktual, dan terbaru. Fitur ini memungkinkan developer dengan mudah menyertakan fungsi yang mengetahui lokasi ke dalam aplikasi mereka. Jika kueri pengguna memiliki konteks yang terkait dengan data Maps, model Gemini akan memanfaatkan Google Maps untuk memberikan jawaban yang akurat secara faktual dan terbaru yang relevan dengan lokasi atau area umum yang ditentukan pengguna.

  • Respons yang akurat dan mengetahui lokasi: Memanfaatkan data Google Maps yang ekstensif dan terbaru untuk kueri yang spesifik secara geografis.
  • Personalisasi yang ditingkatkan: Menyesuaikan rekomendasi dan informasi berdasarkan lokasi yang disediakan pengguna.
  • Informasi dan widget kontekstual: Token konteks untuk merender widget Google Maps interaktif bersama dengan konten yang dihasilkan.

Mulai

Contoh ini menunjukkan cara mengintegrasikan Perujukan dengan Google Maps ke dalam aplikasi Anda untuk memberikan respons yang akurat dan mengetahui lokasi terhadap kueri pengguna. Perintah meminta rekomendasi lokal dengan lokasi pengguna opsional, sehingga model Gemini dapat menggunakan data 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
    }]
  }'

Cara kerja fitur Grounding dengan Google Maps

Perujukan dengan Google Maps mengintegrasikan Gemini API dengan ekosistem Geo Google menggunakan Maps API sebagai sumber perujukan. Jika kueri pengguna berisi konteks geografis, model Gemini dapat memanggil alat Perujukan dengan Google Maps. Kemudian, model dapat menghasilkan respons yang didasarkan pada data Google Maps yang relevan dengan lokasi yang diberikan.

Proses ini biasanya melibatkan:

  1. Kueri pengguna: Pengguna mengirimkan kueri ke aplikasi Anda, yang berpotensi mencakup konteks geografis (misalnya, "kafe di dekat saya", "museum di San Francisco").
  2. Pemanggilan alat: Model Gemini, yang mengenali maksud geografis, memanggil alat Perujukan dengan Google Maps. Alat ini dapat secara opsional diberikan bersama dengan latitude dan longitude pengguna. Alat ini adalah alat penelusuran berbasis teks dan berperilaku serupa dengan penelusuran di Maps, di mana kueri lokal ("di sekitar sini") akan menggunakan koordinat, sementara kueri spesifik atau non-lokal cenderung tidak dipengaruhi oleh lokasi eksplisit.
  3. Pengambilan data: Layanan Perujukan dengan Google Maps mengkueri Google Maps untuk mendapatkan informasi yang relevan (misalnya, tempat, ulasan, foto, alamat, jam buka).
  4. Pembuatan dengan perujukan: Data Maps yang diambil digunakan untuk menginformasikan respons model Gemini, sehingga memastikan akurasi dan relevansi faktual.
  5. Respons & anotasi: Model menampilkan respons teks dengan anotasi inline yang ditautkan ke sumber Google Maps, sehingga developer dapat menampilkan kutipan dan secara opsional merender widget Google Maps kontekstual.

Alasan dan waktu penggunaan Perujukan dengan Google Maps

Penyesuaian dengan Google Maps sangat ideal untuk aplikasi yang memerlukan informasi yang akurat, terbaru, dan spesifik per lokasi. Fitur ini meningkatkan pengalaman pengguna dengan menyediakan konten yang relevan dan dipersonalisasi yang didukung oleh database ekstensif Google Maps yang berisi lebih dari 250 juta tempat di seluruh dunia.

Anda harus menggunakan Grounding dengan Google Maps jika aplikasi Anda perlu:

  • Memberikan respons yang lengkap dan akurat terhadap pertanyaan khusus geografis.
  • Buat perencana perjalanan percakapan dan panduan lokal.
  • Merekomendasikan lokasi menarik berdasarkan lokasi dan preferensi pengguna seperti restoran atau toko.
  • Buat pengalaman yang mengetahui lokasi untuk layanan pengiriman makanan, retail, atau media sosial.

Perujukan dengan Google Maps unggul dalam kasus penggunaan yang memerlukan kedekatan dan data faktual saat ini, seperti menemukan "kedai kopi terbaik di dekat saya" atau mendapatkan rute.

Kasus penggunaan

Perujukan dengan Google Maps mendukung berbagai kasus penggunaan yang sadar lokasi.

Menangani pertanyaan khusus tempat

Ajukan pertanyaan mendetail tentang tempat tertentu untuk mendapatkan jawaban berdasarkan ulasan pengguna Google dan data Maps lainnya.

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

Menyediakan personalisasi berbasis lokasi

Mendapatkan rekomendasi yang disesuaikan dengan preferensi pengguna dan area geografis tertentu.

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

Membantu perencanaan itinerari

Buat rencana perjalanan multi-hari dengan rute dan informasi tentang berbagai lokasi, yang cocok untuk aplikasi perjalanan.

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

Persyaratan penggunaan layanan

Bagian ini menjelaskan persyaratan penggunaan layanan untuk Perujukan dengan Google Maps.

Memberi tahu pengguna tentang penggunaan sumber Google Maps

Dengan setiap hasil yang Didasarkan Google Maps, Anda akan menerima anotasi sumber pada blok konten langkah model_output yang mendukung setiap respons. Metadata berikut akan ditampilkan:

  • URL sumber
  • nama

Saat menyajikan hasil dari Grounding with Google Maps, Anda harus menentukan sumber Google Maps terkait, dan memberi tahu pengguna Anda tentang hal berikut:

  • Sumber Google Maps harus segera mengikuti konten yang dihasilkan yang didukung oleh sumber tersebut. Konten yang dihasilkan ini juga disebut sebagai Hasil yang Sesuai dengan Lokasi Google Maps.
  • Sumber Google Maps harus dapat dilihat dalam satu interaksi pengguna.

Menampilkan sumber Google Maps dengan link Google Maps

Untuk setiap anotasi sumber, pratinjau link harus dibuat dengan mengikuti persyaratan berikut:

  • Atribusikan setiap sumber ke Google Maps dengan mengikuti pedoman atribusi teks Google Maps.
  • Menampilkan nama sumber yang diberikan dalam respons.
  • Tautkan ke sumber menggunakan url dari anotasi.

Panduan atribusi teks Google Maps

Saat Anda mengatribusikan sumber ke Google Maps dalam teks, ikuti panduan berikut:

  • Jangan mengubah teks Google Maps dengan cara apa pun:
    • Jangan mengubah kapitalisasi Google Maps.
    • Jangan bungkus Google Maps ke dalam beberapa baris.
    • Jangan melokalkan Google Maps ke bahasa lain.
    • Mencegah browser menerjemahkan Google Maps dengan menggunakan atribut HTML translate="no".

Untuk mengetahui informasi selengkapnya tentang beberapa penyedia data Google Maps kami dan persyaratan lisensi mereka, lihat pemberitahuan hukum Google Maps dan Google Earth.

Praktik terbaik

  • Memberikan lokasi pengguna: Untuk mendapatkan respons yang paling relevan dan dipersonalisasi, selalu sertakan latitude dan longitude dalam konfigurasi alat google_maps Anda saat lokasi pengguna diketahui.
  • Merender widget kontekstual Google Maps: Widget kontekstual dirender menggunakan token konteks, google_maps_widget_context_token, yang ditampilkan dalam respons Gemini API dan dapat digunakan untuk merender konten visual dari Google Maps.
  • Memberi Tahu Pengguna Akhir: Beri tahu pengguna akhir Anda dengan jelas bahwa data Google Maps digunakan untuk menjawab kueri mereka, terutama saat alat ini diaktifkan.
  • Nonaktifkan Jika Tidak Diperlukan: Penentuan lokasi dengan Google Maps dinonaktifkan secara default. Aktifkan hanya ("tools": [{"type": "google_maps"}]) saat kueri memiliki konteks geografis yang jelas, untuk mengoptimalkan performa dan biaya.

Batasan

  • Saat ini, perujukan dengan Google Maps hanya mendukung perintah dan respons dalam bahasa Inggris.
  • Alat ini mungkin hanya tersedia di wilayah tertentu.
  • Hasil dapat bervariasi berdasarkan akurasi lokasi dan data Maps yang tersedia.
  • Cakupan Geografis: Grounding dengan Google Maps tersedia secara global.
  • Status Default: Alat Perujukan dengan Google Maps dinonaktifkan secara default. Anda harus mengaktifkannya secara eksplisit dalam permintaan API.

Harga dan batas kapasitas

Harga perujukan dengan Google Maps didasarkan pada kueri. Tarif saat ini adalah $25 / 1.000 perintah berbasis. Paket gratis juga memiliki hingga 500 permintaan per hari yang tersedia. Permintaan hanya dihitung dalam kuota jika perintah berhasil menampilkan setidaknya satu hasil yang dirujuk Google Maps (yaitu, hasil yang berisi setidaknya satu sumber Google Maps). Jika beberapa kueri dikirim ke Google Maps dari satu permintaan, kueri tersebut akan dihitung sebagai satu permintaan terhadap batas kecepatan.

Untuk mengetahui informasi harga mendetail, lihat halaman harga Gemini API.

Model yang didukung

Model berikut mendukung Perujukan dengan Google Maps:

Model Grounding dengan Google Maps
Pratinjau Gemini 3.1 Pro ✔️
Gemini 3.1 Flash-Lite ✔️
Pratinjau Gemini 3.1 Flash-Lite ✔️
Pratinjau Gemini 3 Flash ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️

Kombinasi alat yang didukung

Model Gemini 3 mendukung penggabungan alat bawaan (seperti Perujukan dengan Google Maps) dengan alat kustom (panggilan fungsi). Pelajari lebih lanjut di halaman kombinasi alat.

Langkah berikutnya