Grounding dengan Google Maps

Grounding with Google Maps menghubungkan kemampuan generatif Gemini dengan data Google Maps yang kaya, faktual, dan terbaru. Fitur ini memungkinkan developer dengan mudah menggabungkan fungsi yang mengetahui lokasi ke dalam aplikasi mereka. Saat kueri pengguna memiliki konteks yang terkait dengan data Maps, model Gemini 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: Manfaatkan data Google Maps yang luas dan terbaru untuk kueri yang spesifik secara geografis.
• Personalisasi yang ditingkatkan: Sesuaikan rekomendasi dan informasi berdasarkan lokasi yang diberikan pengguna.
• Informasi dan widget kontekstual: Token konteks untuk merender widget Google Maps interaktif bersama konten yang dihasilkan.

Mulai

Contoh ini menunjukkan cara mengintegrasikan Grounding with 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.

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}")

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

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

Cara kerja Grounding with Google Maps

Grounding with Google Maps mengintegrasikan Gemini API dengan ekosistem Google Geo menggunakan Maps API sebagai sumber grounding. Saat kueri pengguna berisi konteks geografis, model Gemini dapat memanggil alat Grounding with Google Maps. Model ini kemudian dapat menghasilkan respons yang didasarkan pada data Google Maps yang relevan dengan lokasi yang diberikan.

Proses ini biasanya mencakup:

1. Kueri pengguna: Pengguna mengirimkan kueri ke aplikasi Anda, yang berpotensi menyertakan konteks geografis (misalnya, "kafe terdekat", "museum di San Francisco").
2. Pemanggilan alat: Model Gemini, yang mengenali maksud geografis, memanggil alat Grounding with Google Maps. Alat ini dapat secara opsional diberikan latitude dan longitude pengguna. Alat ini adalah alat penelusuran teks dan berperilaku mirip dengan penelusuran di Maps, yang mana kueri lokal ("di dekat saya") akan menggunakan koordinat, sedangkan kueri spesifik atau non-lokal kemungkinan tidak akan terpengaruh oleh lokasi eksplisit.
3. Pengambilan data: Layanan Grounding with Google Maps mengkueri Google Maps untuk mendapatkan informasi yang relevan (misalnya, tempat, ulasan, foto, alamat, jam buka).
4. Generasi yang didasarkan pada data: 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 Grounding with Google Maps

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

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

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

Grounding with Google Maps unggul dalam kasus penggunaan yang mengutamakan kedekatan dan data faktual saat ini, seperti menemukan "kafe terbaik di dekat saya" atau mendapatkan rute.

Kasus penggunaan

Grounding with Google Maps mendukung berbagai kasus penggunaan yang mengetahui lokasi.

Menangani pertanyaan spesifik tempat

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

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}")

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

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

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}")

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

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

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

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

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

Persyaratan penggunaan layanan

Bagian ini menjelaskan persyaratan penggunaan layanan untuk Grounding with Google Maps.

Memberi tahu pengguna tentang penggunaan sumber Google Maps

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

• URL sumber
• nama

Saat menampilkan 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 Hasil yang Didasarkan pada Data 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 panduan atribusi teks Google Maps Google Maps.
• Tampilkan 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 ubah teks Google Maps dengan cara apa pun:
  • Jangan ubah kapitalisasi Google Maps.
  • Jangan gabungkan Google Maps ke beberapa baris.
  • Jangan lokalkan Google Maps ke bahasa lain.
  • Cegah browser menerjemahkan Google Maps dengan menggunakan atribut HTML translate="no".

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

Praktik terbaik

• Berikan lokasi pengguna: Untuk mendapatkan respons yang paling relevan dan dipersonalisasi, selalu sertakan latitude dan longitude dalam konfigurasi alat google_maps Anda jika lokasi pengguna diketahui.
• Render 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.
• Beri Tahu Pengguna Akhir: Beri tahu pengguna akhir Anda dengan jelas bahwa data Google Maps digunakan untuk menjawab kueri mereka, terutama saat alat diaktifkan.
• Nonaktifkan Jika Tidak Diperlukan: Grounding with Google Maps dinonaktifkan secara default. Hanya aktifkan ("tools": [{"type": "google_maps"}]) jika kueri memiliki konteks geografis yang jelas, untuk mengoptimalkan performa dan biaya.

Batasan

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

Harga dan batas kapasitas

Harga Grounding with Google Maps didasarkan pada kueri. Tarif saat ini adalah $25 / 1.000 perintah yang didasarkan pada data. Paket gratis juga memiliki hingga 500 permintaan per hari. Permintaan hanya dihitung terhadap kuota jika perintah berhasil menampilkan setidaknya satu hasil yang didasarkan pada data 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 kapasitas.

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

Model yang didukung

Model berikut mendukung Grounding with Google Maps:

Kombinasi alat yang didukung

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

Langkah berikutnya

• Pelajari alat lain yang tersedia.
• Untuk mempelajari praktik terbaik AI yang bertanggung jawab dan filter keamanan Gemini API lebih lanjut, lihat panduan Setelan keamanan.