Grounding z użyciem Map Google

Powiązanie ze źródłem 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łem 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

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

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

Powiązanie ze źródłem informacji przy użyciu Map Google integruje interfejs Gemini API z ekosystemem Google Geo, używając interfejsu API Map Google jako źródła powiązania ze źródłem informacji. Gdy zapytanie użytkownika zawiera kontekst geograficzny, model Gemini może wywołać narzędzie Grounding przy użyciu Map Google. Model może wtedy generować odpowiedzi na podstawie danych z Map Google związanych z podaną lokalizacją.

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. Narzędzie to służy do wyszukiwania tekstowego i działa podobnie jak wyszukiwanie 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łem 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 zawierają linki 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łem informacji przy użyciu Map Google

Powiązanie ze źródłem 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 na podstawie obszernej bazy danych Map Google, która zawiera ponad 250 milionów miejsc na całym świecie.

Korzystaj z powiązania ze źródłem 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łem 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łem 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

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

Personalizacja na podstawie lokalizacji

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

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

pomoc w planowaniu trasy,

Generowanie wielodniowych planów z wskazówkami dojazdu i informacjami o różnych lokalizacjach, idealnych do aplikacji podróżniczych.

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

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 na etapie 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łem 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ą. Te 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 zgodnie z tymi wymaganiami:

  • 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łem 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łem informacji przy użyciu Map Google jest dostępne na całym świecie.
  • Stan domyślny: narzędzie Powiązanie ze źródłem 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łem informacji przy użyciu Map Google są oparte na zapytaniach. 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łem informacji przy użyciu Map Google jest obsługiwane na tych modelach:

Model Grounding z użyciem Map Google
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?