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 z 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 Google, model Gemini korzysta z Map Google, aby udzielać aktualnych i dokładnych odpowiedzi, które są istotne dla określonej przez użytkownika lokalizacji lub ogólnego obszaru.

• Dokładne odpowiedzi uwzględniające lokalizację: korzystaj z obszernych i aktualnych danych z Map Google w przypadku zapytań dotyczących konkretnych lokalizacji.
• 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 na zapytania uwzględniające lokalizację. Prompt prosi o lokalne rekomendacje z opcjonalną lokalizacją użytkownika, co umożliwia modelowi Gemini korzystanie z danych Map Google.

from google import genai
from google.genai import types

client = genai.Client()

prompt = "What are the best Italian restaurants within a 15-minute walk from here?"

response = client.models.generate_content(
    model='gemini-3-flash-preview',
    contents=prompt,
    config=types.GenerateContentConfig(
        # Turn on grounding with Google Maps
        tools=[types.Tool(google_maps=types.GoogleMaps())],
        # Optionally provide the relevant location context (this is in Los Angeles)
        tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
            lat_lng=types.LatLng(
                latitude=34.050481, longitude=-118.248526))),
    ),
)

print("Generated Response:")
print(response.text)

if grounding := response.candidates[0].grounding_metadata:
  if grounding.grounding_chunks:
    print('-' * 40)
    print("Sources:")
    for chunk in grounding.grounding_chunks:
      print(f'- [{chunk.maps.title}]({chunk.maps.uri})')

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function generateContentWithMapsGrounding() {
  const response = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    contents: "What are the best Italian restaurants within a 15-minute walk from here?",
    config: {
      // Turn on grounding with Google Maps
      tools: [{ googleMaps: {} }],
      toolConfig: {
        retrievalConfig: {
          // Optionally provide the relevant location context (this is in Los Angeles)
          latLng: {
            latitude: 34.050481,
            longitude: -118.248526,
          },
        },
      },
    },
  });

  console.log("Generated Response:");
  console.log(response.text);

  const grounding = response.candidates[0]?.groundingMetadata;
  if (grounding?.groundingChunks) {
    console.log("-".repeat(40));
    console.log("Sources:");
    for (const chunk of grounding.groundingChunks) {
      if (chunk.maps) {
        console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
      }
    }
  }
}

generateContentWithMapsGrounding();

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "What are the best Italian restaurants within a 15-minute walk from here?"
    }]
  }],
  "tools": [{"googleMaps": {}}],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {"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 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. 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 oparte na faktach: pobrane dane z Map są wykorzystywane do tworzenia odpowiedzi modelu Gemini, co zapewnia zgodność z prawdą i trafność informacji.
5. Odpowiedź i token widżetu: model zwraca odpowiedź tekstową, która zawiera cytaty ze źródeł w Mapach Google. Opcjonalnie odpowiedź interfejsu API może też zawierać google_maps_widget_context_token, co umożliwia deweloperom renderowanie w aplikacji kontekstowego widżetu Map Google do interakcji wizualnej.

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

Metody i parametry interfejsu API

Powiązanie ze źródłem informacji przy użyciu Map Google jest udostępniane przez Gemini API jako narzędzie w ramach metody generateContent. Aby włączyć i skonfigurować powiązanie ze źródłem informacji przy użyciu Map Google, w parametrze tools żądania umieść obiekt googleMaps.

{
  "contents": [{
    "parts": [
      {"text": "Restaurants near Times Square."}
    ]
  }],
  "tools":  { "googleMaps": {} }
}

Narzędzie googleMaps może dodatkowo akceptować parametr logiczny enableWidget, który służy do określania, czy pole googleMapsWidgetContextToken ma być zwracane w odpowiedzi. Możesz go użyć do wyświetlania widżetu Miejsca.

{
"contents": [{
    "parts": [
      {"text": "Restaurants near Times Square."}
    ]
  }],
  "tools":  { "googleMaps": { "enableWidget": true } }
}

Narzędzie umożliwia też przekazywanie lokalizacji kontekstowej jako toolConfig.

{
  "contents": [{
    "parts": [
      {"text": "Restaurants near here."}
    ]
  }],
  "tools":  { "googleMaps": {} },
  "toolConfig":  {
    "retrievalConfig": {
      "latLng": {
        "latitude": 40.758896,
        "longitude": -73.985130
      }
    }
  }
}

Informacje o odpowiedzi dotyczącej podstaw

Gdy odpowiedź zostanie prawidłowo oparta na danych z Map Google, będzie zawierać pole groundingMetadata. Te dane strukturalne są niezbędne do weryfikowania twierdzeń i tworzenia w aplikacji rozbudowanych cytatów, a także do spełniania wymagań dotyczących korzystania z usługi.

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "CanteenM is an American restaurant with..."
          }
        ],
        "role": "model"
      },
      "groundingMetadata": {
        "groundingChunks": [
          {
            "maps": {
              "uri": "https://maps.google.com/?cid=13100894621228039586",
              "title": "Heaven on 7th Marketplace",
              "placeId": "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
            },
            // repeated ...
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 0,
              "endIndex": 79,
              "text": "CanteenM is an American restaurant with a 4.6-star rating and is open 24 hours."
            },
            "groundingChunkIndices": [0]
          },
          // repeated ...
        ],
        "webSearchQueries": [
          "restaurants near me"
        ],
        "googleMapsWidgetContextToken": "widgetcontent/..."
      }
    }
  ]
}

Interfejs Gemini API zwraca te informacje z groundingMetadata:

• groundingChunks: tablica obiektów zawierająca źródła maps (uri, placeId i title).
• groundingSupports: tablica fragmentów, które łączą tekst odpowiedzi modelu ze źródłami w groundingChunks. Każdy fragment łączy zakres tekstu (zdefiniowany przez startIndex i endIndex) z co najmniej 1 groundingChunkIndices. To klucz do tworzenia cytatów w tekście.
• googleMapsWidgetContextToken: token tekstowy, którego można użyć do renderowania widżetu Miejsc kontekstowych.

Fragment kodu pokazujący, jak renderować cytaty w tekście, znajdziesz w przykładzie w dokumentacji dotyczącej ugruntowania za pomocą wyszukiwarki Google.

Wyświetlanie widżetu kontekstowego Map Google

Aby użyć zwróconego parametru googleMapsWidgetContextToken, musisz wczytać interfejs Maps JavaScript API.

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ą. Poniższe przykłady pokazują, jak różne prompty i parametry mogą wykorzystywać powiązanie ze źródłem informacji przy użyciu Map Google. Informacje w wynikach w Mapach Google mogą różnić się od rzeczywistych warunków.

Odpowiadanie na pytania dotyczące konkretnych miejsc

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

from google import genai
from google.genai import types

client = genai.Client()

prompt = "Is there a cafe near the corner of 1st and Main that has outdoor seating?"

response = client.models.generate_content(
    model='gemini-3-flash-preview',
    contents=prompt,
    config=types.GenerateContentConfig(
        # Turn on the Maps tool
        tools=[types.Tool(google_maps=types.GoogleMaps())],

        # Provide the relevant location context (this is in Los Angeles)
        tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
            lat_lng=types.LatLng(
                latitude=34.050481, longitude=-118.248526))),
    ),
)

print("Generated Response:")
print(response.text)

if grounding := response.candidates[0].grounding_metadata:
  if chunks := grounding.grounding_chunks:
    print('-' * 40)
    print("Sources:")
    for chunk in chunks:
      print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
  ```

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function run() {
  const prompt = "Is there a cafe near the corner of 1st and Main that has outdoor seating?";

  const response = await ai.models.generateContent({
    model: 'gemini-3-flash-preview',
    contents: prompt,
    config: {
      // Turn on the Maps tool
      tools: [{googleMaps: {}}],
      // Provide the relevant location context (this is in Los Angeles)
      toolConfig: {
        retrievalConfig: {
          latLng: {
            latitude: 34.050481,
            longitude: -118.248526
          }
        }
      }
    },
  });

  console.log("Generated Response:");
  console.log(response.text);

  const chunks = response.candidates[0].groundingMetadata?.groundingChunks;
  if (chunks) {
    console.log('-'.repeat(40));
    console.log("Sources:");
    for (const chunk of chunks) {
      if (chunk.maps) {
        console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
      }
    }
  }
}

run();

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "Is there a cafe near the corner of 1st and Main that has outdoor seating?"
    }]
  }],
  "tools": [{"googleMaps": {}}],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {"latitude": 34.050481, "longitude": -118.248526}
    }
  }
}'

Personalizacja na podstawie lokalizacji

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

from google import genai
from google.genai import types

client = genai.Client()

prompt = "Which family-friendly restaurants near here have the best playground reviews?"

response = client.models.generate_content(
    model='gemini-3-flash-preview',
    contents=prompt,
    config=types.GenerateContentConfig(
      tools=[types.Tool(google_maps=types.GoogleMaps())],
      tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
          # Provide the location as context; this is Austin, TX.
          lat_lng=types.LatLng(
              latitude=30.2672, longitude=-97.7431))),
    ),
)

print("Generated Response:")
print(response.text)

if grounding := response.candidates[0].grounding_metadata:
  if chunks := grounding.grounding_chunks:
    print('-' * 40)
    print("Sources:")
    for chunk in chunks:
      print(f'- [{chunk.maps.title}]({chunk.maps.uri})')

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function run() {
  const prompt = "Which family-friendly restaurants near here have the best playground reviews?";

  const response = await ai.models.generateContent({
    model: 'gemini-3-flash-preview',
    contents: prompt,
    config: {
      tools: [{googleMaps: {}}],
      toolConfig: {
        retrievalConfig: {
          // Provide the location as context; this is Austin, TX.
          latLng: {
            latitude: 30.2672,
            longitude: -97.7431
          }
        }
      }
    },
  });

  console.log("Generated Response:");
  console.log(response.text);

  const chunks = response.candidates[0].groundingMetadata?.groundingChunks;
  if (chunks) {
    console.log('-'.repeat(40));
    console.log("Sources:");
    for (const chunk of chunks) {
      if (chunk.maps) {
        console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
      }
    }
  }
}

run();

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "Which family-friendly restaurants near here have the best playground reviews?"
    }],
  }],
  "tools": [{"googleMaps": {}}],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {"latitude": 30.2672, "longitude": -97.7431}
    }
  }
}'

pomoc w planowaniu trasy,

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

W tym przykładzie o googleMapsWidgetContextToken poproszono przez włączenie widżetu w narzędziu Mapy Google. Gdy ta opcja jest włączona, zwrócony token może służyć do renderowania kontekstowego widżetu Miejsc za pomocą funkcji <gmp-places-contextual> component z interfejsu Maps JavaScript API.

from google import genai
from google.genai import types

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

response = client.models.generate_content(
    model='gemini-3-flash-preview',
    contents=prompt,
    config=types.GenerateContentConfig(
      tools=[types.Tool(google_maps=types.GoogleMaps(enable_widget=True))],
      tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
          # Provide the location as context, this is in San Francisco.
          lat_lng=types.LatLng(
              latitude=37.78193, longitude=-122.40476))),
    ),
)

print("Generated Response:")
print(response.text)

if grounding := response.candidates[0].grounding_metadata:
  if grounding.grounding_chunks:
    print('-' * 40)
    print("Sources:")
    for chunk in grounding.grounding_chunks:
      print(f'- [{chunk.maps.title}]({chunk.maps.uri})')

  if widget_token := grounding.google_maps_widget_context_token:
    print('-' * 40)
    print(f'<gmp-place-contextual context-token="{widget_token}"></gmp-place-contextual>')

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function run() {
  const 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.";

  const response = await ai.models.generateContent({
    model: 'gemini-3-flash-preview',
    contents: prompt,
    config: {
      tools: [{googleMaps: {enableWidget: true}}],
      toolConfig: {
        retrievalConfig: {
          // Provide the location as context, this is in San Francisco.
          latLng: {
            latitude: 37.78193,
            longitude: -122.40476
          }
        }
      }
    },
  });

  console.log("Generated Response:");
  console.log(response.text);

  const groundingMetadata = response.candidates[0]?.groundingMetadata;
  if (groundingMetadata) {
    if (groundingMetadata.groundingChunks) {
      console.log('-'.repeat(40));
      console.log("Sources:");
      for (const chunk of groundingMetadata.groundingChunks) {
        if (chunk.maps) {
          console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
        }
      }
    }

    if (groundingMetadata.googleMapsWidgetContextToken) {
      console.log('-'.repeat(40));
      document.body.insertAdjacentHTML('beforeend', `<gmp-place-contextual context-token="${groundingMetadata.googleMapsWidgetContextToken}`"></gmp-place-contextual>`);
    }
  }
}

run();

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent' \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "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": [{"googleMaps": {"enableWidget":"true"}}],
  "toolConfig": {
    "retrievalConfig": {
    "latLng": {"latitude": 37.78193, "longitude": -122.40476}
  }
  }
}'

Po wyrenderowaniu widżet będzie wyglądać mniej więcej tak:

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 opartego na zweryfikowanych informacjach otrzymasz źródłagroundingChunks, które potwierdzają każdą odpowiedź. Zwracane są też te metadane:

• Identyfikator URI źródła
• tytuł
• Identyfikator

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żdego źródła w groundingChunks i w grounding_chunks.maps.placeAnswerSources.reviewSnippets podgląd linku musi być generowany zgodnie z tymi wymaganiami:

• Podaj atrybucję każdego źródła w Mapach Google zgodnie z wytycznymi dotyczącymi atrybucji.
• Wyświetl tytuł źródła podany w odpowiedzi.
• Połącz się ze źródłem, używając symbolu uri lub googleMapsUri z odpowiedzi.

Te obrazy pokazują minimalne wymagania dotyczące wyświetlania źródeł i linków do Map Google.

Możesz zwinąć widok źródeł.

Opcjonalnie: wzbogać podgląd linku o dodatkowe treści, takie jak:

• Przed tekstem atrybucji Map Google wstawiana jest ikona Map Google.
• zdjęcie ze źródłowego adresu URL (og:image);

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.

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".
• Stylizuj tekst w Mapach Google zgodnie z opisem w tej tabeli:

Przykładowy kod CSS

Poniższy kod CSS renderuje Mapy Google z odpowiednim stylem typograficznym i kolorem na białym lub jasnym tle.

@import url('https://fonts.googleapis.com/css2?family=Roboto&display=swap');

.GMP-attribution {

font-family: Roboto, Sans-Serif;
font-style: normal;
font-weight: 400;
font-size: 1rem;
letter-spacing: normal;
white-space: nowrap;
color: #5e5e5e;
}

Token kontekstu, identyfikator miejsca i identyfikator opinii

Dane z Map Google obejmują token kontekstu, identyfikator miejsca i identyfikator opinii. Możesz buforować, przechowywać i eksportować te dane odpowiedzi:

• googleMapsWidgetContextToken
• placeId
• reviewId

Ograniczenia dotyczące buforowania w Warunkach korzystania z powiązania ze źródłem informacji przy użyciu Map Google nie mają zastosowania.

Zabronione działania i obszary

W przypadku powiązania ze źródłem informacji przy użyciu Map Google obowiązują dodatkowe ograniczenia dotyczące niektórych treści i aktywności, aby zapewnić bezpieczeństwo i niezawodność platformy. Oprócz ograniczeń użytkowania w Warunkach:

• Nie będziesz używać powiązania ze źródłem informacji przy użyciu Map Google do działań o wysokim ryzyku, w tym do usług reagowania w sytuacjach kryzysowych.

• Nie będziesz rozpowszechniać ani sprzedawać aplikacji, która oferuje funkcję Grounding w Mapach Google, w Zabronionych krajach. Obecnie zabronione regiony to:

  • Chiny
  • Krym
  • Kuba
  • Doniecka Republika Ludowa
  • Iran
  • Ługańska Republika Ludowa
  • Korea Północna
  • Syria
  • Wietnam

  Ta lista może być okresowo aktualizowana.

Sprawdzone metody

• Podaj lokalizację użytkownika: aby uzyskać najbardziej trafne i spersonalizowane odpowiedzi, zawsze uwzględniaj user_location (szerokość i długość geograficzną) w konfiguracji googleMapsGrounding, gdy znana jest lokalizacja użytkownika.
• Renderowanie widżetu kontekstowego Map Google: widżet kontekstowy jest renderowany przy użyciu tokena kontekstu googleMapsWidgetContextToken, który jest zwracany w odpowiedzi interfejsu Gemini API i może służyć do renderowania treści wizualnych z Map Google. Więcej informacji o widżecie kontekstowym znajdziesz w przewodniku Google dla programistów w sekcji Grounding with Google Maps widget.
• 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.
• Monitoruj opóźnienia: w przypadku aplikacji konwersacyjnych zadbaj o to, aby opóźnienie P95 w przypadku odpowiedzi opartych na wiedzy pozostawało w dopuszczalnych granicach, co zapewni płynne działanie aplikacji.
• 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": [{"googleMaps": {}}]) tylko wtedy, gdy zapytanie ma wyraźny kontekst geograficzny, aby zoptymalizować wydajność i koszty.

Ograniczenia

• Zasięg geograficzny: powiązanie ze źródłem informacji przy użyciu Map Google jest dostępne na całym świecie.
• Obsługiwane modele: zobacz sekcję Obsługiwane modele.
• Dane wejściowe i wyjściowe w różnych formatach: Powiązanie ze źródłem informacji przy użyciu Map Google nie obsługuje obecnie danych wejściowych ani wyjściowych w różnych formatach poza tekstem i kontekstowymi widżetami mapy.
• 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 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łem informacji przy użyciu Map Google jest obsługiwane na tych modelach:

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?

• Wypróbuj grounding z użyciem wyszukiwarki Google w zbiorze Cookbook interfejsu Gemini API.
• Dowiedz się więcej o innych dostępnych narzędziach.
• Więcej informacji o sprawdzonych metodach dotyczących odpowiedzialnej AI i filtrach bezpieczeństwa Gemini API znajdziesz w przewodniku po ustawieniach bezpieczeństwa.