Grounding z użyciem Map Google

Powiązanie ze źródłami informacji przy użyciu Map Google łączy funkcje generatywne Gemini z bogatymi, prawdziwymi i aktualnymi danymi Map Google. Dzięki tej funkcji deweloperzy mogą łatwo wprowadzać w swoich aplikacjach funkcje oparte na lokalizacji. Gdy zapytanie użytkownika ma kontekst związany z danymi z Map, model Gemini korzysta z Map Google, aby udzielać aktualnych i rzetelnych odpowiedzi, które są istotne dla określonej przez użytkownika lokalizacji lub ogólnego obszaru.

  • Dokładne odpowiedzi uwzględniające lokalizację: wykorzystuj obszerne i aktualne dane z Map Google w przypadku zapytań dotyczących konkretnych lokalizacji geograficznych.
  • Ulepszona personalizacja: dostosowywanie rekomendacji i informacji na podstawie lokalizacji podanych przez użytkowników.
  • Informacje kontekstowe i widżety: tokeny kontekstowe do renderowania interaktywnych widżetów Map Google obok wygenerowanych treści.

Rozpocznij

Ten przykład pokazuje, jak zintegrować powiązanie ze źródłami informacji przy użyciu Map Google w aplikacji, aby przekazywać użytkownikom dokładne odpowiedzi oparte na lokalizacji. Prompt prosi o lokalne rekomendacje z opcjonalną lokalizacją użytkownika, co umożliwia modelowi Gemini korzystanie z danych Map Google.

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.5-flash",
    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.5-flash",
    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.5-flash",
    "input": "What are the best Italian restaurants within a 15-minute walk from here?",
    "tools": [{
      "type": "google_maps",
      "latitude": 34.050481,
      "longitude": -118.248526
    }]
  }'

Jak działa powiązanie ze źródłami informacji przy użyciu Map Google

Powiązanie ze źródłami informacji przy użyciu Map Google integruje interfejs Gemini API z ekosystemem Google Geo, wykorzystując interfejs API Map Google jako źródło powiązania ze źródłami informacji. Gdy zapytanie użytkownika zawiera kontekst geograficzny, model Gemini może wywołać narzędzie Grounding w Mapach Google. Model może wtedy generować odpowiedzi oparte na danych z Map Google, które są istotne dla podanej lokalizacji.

Proces ten zwykle obejmuje:

  1. Zapytanie użytkownika: użytkownik przesyła zapytanie do Twojej aplikacji, które może zawierać kontekst geograficzny (np. „kawiarnie w pobliżu”, „muzea w San Francisco”).
  2. Wywołanie narzędzia: model Gemini, rozpoznając intencję geograficzną, wywołuje narzędzie Powiązanie ze źródłem informacji przy użyciu Map Google. To narzędzie może opcjonalnie zawierać latitude i longitude użytkownika. To narzędzie do wyszukiwania tekstowego działa podobnie do wyszukiwania w Mapach. Zapytania lokalne („w pobliżu”) będą korzystać ze współrzędnych, a zapytania konkretne lub nielokalne prawdopodobnie nie będą zależeć od wyraźnej lokalizacji.
  3. Pobieranie danych: usługa powiązanie ze źródłami informacji przy użyciu Map Google wysyła zapytania do Map Google o odpowiednie informacje (np. Miejsca, opinie, zdjęcia, adresy, godziny otwarcia).
  4. Generowanie na podstawie danych: pobrane dane z Map są wykorzystywane do tworzenia odpowiedzi modelu Gemini, co zapewnia dokładność i trafność informacji.
  5. Odpowiedź i adnotacje: model zwraca odpowiedź tekstową z adnotacjami w tekście, które prowadzą do źródeł w Mapach Google. Dzięki temu deweloperzy mogą wyświetlać cytaty i opcjonalnie renderować kontekstowy widżet Map Google.

Dlaczego i kiedy warto korzystać z powiązania ze źródłami informacji przy użyciu Map Google

Powiązanie ze źródłami informacji przy użyciu Map Google to idealne rozwiązanie dla aplikacji, które wymagają dokładnych, aktualnych i specyficznych dla lokalizacji informacji. Ulepsza ona komfort korzystania z usługi, ponieważ wyświetla trafne i spersonalizowane treści, które są oparte na obszernej bazie danych Map Google zawierającej ponad 250 milionów miejsc na całym świecie.

Korzystaj z powiązania ze źródłami informacji przy użyciu Map Google, gdy aplikacja musi:

  • Udzielaj wyczerpujących i dokładnych odpowiedzi na pytania dotyczące konkretnych lokalizacji geograficznych.
  • Twórz konwersacyjne plannery podróży i lokalne przewodniki.
  • Polecaj ciekawe miejsca na podstawie lokalizacji i preferencji użytkownika, np. restauracje lub sklepy.
  • Tworzenie usług społecznościowych, handlowych lub dostawy jedzenia, które uwzględniają lokalizację.

Powiązanie ze źródłami informacji przy użyciu Map Google sprawdza się w przypadkach użycia, w których kluczowe są bliskość i aktualne dane zgodne z prawdą, np. podczas wyszukiwania „najlepszej kawiarni w pobliżu” lub uzyskiwania wskazówek dojazdu.

Przypadki użycia

Powiązanie ze źródłami informacji przy użyciu Map Google obsługuje różne przypadki użycia związane z lokalizacją.

Obsługa pytań dotyczących konkretnego miejsca

Zadawaj szczegółowe pytania o konkretne miejsce, aby uzyskać odpowiedzi na podstawie opinii użytkowników Google i innych danych z Map.

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.5-flash",
    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.5-flash",
    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();

personalizowanie treści na podstawie lokalizacji,

Otrzymywanie rekomendacji dostosowanych do preferencji użytkownika i określonego obszaru geograficznego.

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.5-flash",
    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.5-flash",
    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();

pomoc w planowaniu trasy,

Generuj plany wielodniowe ze wskazówkami dojazdu i informacjami o różnych lokalizacjach, które idealnie nadają się do aplikacji podróżniczych.

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.5-flash",
    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.5-flash",
    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.5-flash",
    "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
    }]
  }'

Wymagania dotyczące korzystania z usługi

W tej sekcji opisano wymagania dotyczące korzystania z usługi Grounding with Google Maps.

Informowanie użytkownika o korzystaniu ze źródeł Map Google

W przypadku każdego wyniku w Mapach Google otrzymasz adnotacje o źródłach w blokach treści kroku model_output, które obsługują każdą odpowiedź. Zwracane są te metadane:

  • adres URL źródła,
  • nazwa

Prezentując wyniki powiązania ze źródłami informacji przy użyciu Map Google, musisz podać powiązane źródła w Mapach Google i poinformować użytkowników o tych kwestiach:

  • Źródła Map Google muszą znajdować się bezpośrednio po wygenerowanych treściach, które obsługują. Wygenerowane treści są też nazywane wynikiem podstawowym w Mapach Google.
  • Źródła w Mapach Google muszą być widoczne w ramach jednej interakcji użytkownika.

Wyświetlanie źródeł Map Google z linkami do Map Google

W przypadku każdej adnotacji źródła musi zostać wygenerowany podgląd linku, który spełnia te wymagania:

  • Podaj atrybucję każdego źródła w Mapach Google zgodnie z wytycznymi dotyczącymi atrybucji.
  • Wyświetlaj nazwę źródła podaną w odpowiedzi.
  • Połącz się ze źródłem za pomocą url z adnotacji.

Wytyczne dotyczące atrybucji tekstowej w Mapach Google

Gdy przypisujesz źródła do Map Google w tekście, postępuj zgodnie z tymi wskazówkami:

  • Nie modyfikuj w żaden sposób tekstu Mapy Google:
    • Nie zmieniaj wielkości liter w nazwie Mapy Google.
    • Nie dziel Map Google na kilka wierszy.
    • Nie lokalizuj Map Google na inny język.
    • Uniemożliwiaj przeglądarkom tłumaczenie Map Google, używając atrybutu HTML translate="no".

Więcej informacji o niektórych dostawcach danych do Map Google i ich warunkach licencji znajdziesz w informacjach prawnych dotyczących Map Google i Google Earth.

Sprawdzone metody

  • Podaj lokalizację użytkownika: aby uzyskać najbardziej trafne i spersonalizowane odpowiedzi, zawsze uwzględniaj parametry latitude i longitude w konfiguracji narzędzia google_maps, gdy znana jest lokalizacja użytkownika.
  • Renderowanie widżetu kontekstowego Map Google: widżet kontekstowy jest renderowany przy użyciu tokena kontekstu google_maps_widget_context_token, który jest zwracany w odpowiedzi interfejsu Gemini API i może służyć do renderowania treści wizualnych z Map Google.
  • Informowanie użytkowników: wyraźnie informuj użytkowników, że dane z Map Google są używane do odpowiadania na ich zapytania, zwłaszcza gdy narzędzie jest włączone.
  • Wyłączanie, gdy nie jest potrzebne: powiązanie ze źródłem informacji przy użyciu Map Google jest domyślnie wyłączone. Włączaj tę opcję ("tools": [{"type": "google_maps"}]) tylko wtedy, gdy zapytanie ma wyraźny kontekst geograficzny, aby zoptymalizować wydajność i koszty.

Ograniczenia

  • Powiązanie ze źródłami informacji przy użyciu Map Google obsługuje obecnie tylko prompty i odpowiedzi w języku angielskim.
  • Narzędzie może być niedostępne w niektórych regionach.
  • Wyniki mogą się różnić w zależności od dokładności lokalizacji i dostępnych danych w Mapach.
  • Zakres geograficzny: powiązanie ze źródłami informacji przy użyciu Map Google jest dostępne na całym świecie.
  • Stan domyślny: narzędzie Powiązanie ze źródłami informacji przy użyciu Map Google jest domyślnie wyłączone. Musisz wyraźnie włączyć go w żądaniach do interfejsu API.

Ceny i limity

Ceny powiązania ze źródłami informacji przy użyciu Map Google zależą od liczby zapytań. Obecna stawka to 25 USD za 1000 promptów opartych na faktach. W ramach bezpłatnej wersji możesz też wysyłać do 500 zapytań dziennie. Żądanie jest wliczane do limitu tylko wtedy, gdy prompt zwróci co najmniej 1 wynik z Map Google (czyli wynik zawierający co najmniej 1 źródło z Map Google). Jeśli w ramach jednego żądania do Map Google zostanie wysłanych kilka zapytań, będzie ono liczone jako 1 żądanie w ramach limitu szybkości.

Szczegółowe informacje o cenach znajdziesz na stronie z cennikiem Gemini API.

Obsługiwane modele

Powiązanie ze źródłami informacji przy użyciu Map Google jest obsługiwane na tych modelach:

Model Grounding z użyciem Map Google
Gemini 3.5 Flash ✔️
Gemini 3.1 Pro (wersja testowa) ✔️
Gemini 3.1 Flash-Lite ✔️
Gemini 3.1 Flash-Lite (wersja testowa) ✔️
Gemini 3 Flash (wersja testowa) ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️

Obsługiwane kombinacje narzędzi

Modele Gemini 3 obsługują łączenie wbudowanych narzędzi (takich jak Grounding z Mapami Google) z narzędziami niestandardowymi (wywołanie funkcji). Więcej informacji znajdziesz na stronie kombinacje narzędzi.

Co dalej?