Grounding z użyciem Map Google

Grounding z użyciem 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ć Grounding z Mapami Google w aplikacji, aby przekazywać użytkownikom dokładne odpowiedzi uwzględniające lokalizację. 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
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-2.5-flash-lite',
    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})')

JavaScript

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

const ai = new GoogleGenAI({});

async function generateContentWithMapsGrounding() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    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();

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite: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 grounding z użyciem Map Google

Uziemienie w Mapach Google integruje interfejs Gemini API z ekosystemem Google Geo, używając interfejsu Maps API jako źródła uziemienia. 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 dotyczących 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 Grounding z Mapami Google. To narzędzie może opcjonalnie otrzymywać latitude i longitude użytkownika, aby zwracać wyniki uwzględniające lokalizację.
  3. Pobieranie danych: usługa Grounding with Google Maps wysyła do Map Google zapytania o odpowiednie informacje (np. miejsca, opinie, zdjęcia, adresy, godziny otwarcia).
  4. Generowanie na podstawie danych: pobrane dane z Map Google są wykorzystywane do tworzenia odpowiedzi modelu Gemini, co zapewnia dokładność i trafność.
  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 groundingu z użyciem Map Google

Grounding z użyciem Map Google jest idealny w przypadku 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 oparte na obszernej bazie danych Map Google, która zawiera ponad 250 milionów miejsc na całym świecie.

Korzystaj z groundingu z użyciem 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ę.

Uziemianie za pomocą Map Google sprawdza się w przypadkach, w których kluczowe są bliskość i aktualne dane, np. podczas wyszukiwania „najlepszej kawiarni w pobliżu” lub uzyskiwania wskazówek dojazdu.

Metody i parametry interfejsu API

Uziemianie w Mapach Google jest udostępniane przez Gemini API jako narzędzie w ramach metody generateContent. Aby włączyć i skonfigurować ugruntowanie w Mapach Google, w parametrze tools żądania umieść obiekt googleMaps.

JSON

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

Narzędzie googleMaps może dodatkowo przyjmować 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.

JSON

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

Narzędzie obsługuje też przekazywanie lokalizacji kontekstowej jako toolConfig.

JSON

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

Interpretowanie odpowiedzi dotyczącej podstawy

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.

JSON

{
  "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 googleMapsWidgetContextToken, musisz wczytać interfejs Maps JavaScript API.

Przypadki użycia

Grounding z użyciem 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ć ugruntowanie w Mapach Google. Informacje w wynikach w Mapach Google mogą różnić się od rzeczywistych warunków.

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
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-2.5-flash-lite',
    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})')
  ```

JavaScript

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-2.5-flash',
    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();

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite: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.

Python

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-2.5-flash',
    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})')

JavaScript

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-2.5-flash',
    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();

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite: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

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

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

Python

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-2.5-flash',
    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>')

JavaScript

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-2.5-flash',
    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();

REST

curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite: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:

Przykład wyrenderowanego widżetu Map

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 źródłagroundingChunks potwierdzające każdą odpowiedź. Zwracane są też te metadane:

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

Prezentując wyniki groundingu z użyciem 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.

W przypadku każdego źródła w groundingChunks i 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.

Prompt z odpowiedzią zawierającą źródła

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

Prompt z odpowiedzią i zwiniętymi źródłami

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

Podając źródła w tekście w przypadku Map Google, postępuj zgodnie z tymi wytycznymi:

  • 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:
Właściwość Styl
Font family Roboto. Wczytywanie czcionki jest opcjonalne.
Fallback font family dowolną czcionkę bezszeryfową używaną już w Twojej usłudze lub „Sans-Serif”, aby wywołać domyślną czcionkę systemową.
Font style Normalny
Font weight 400
Font color biały, czarny (#1F1F1F) lub szary (#5E5E5E); Zachowaj kontrast względem tła na poziomie 4,5:1.
Font size
  • Minimalny rozmiar czcionki: 12 sp
  • Maksymalny rozmiar czcionki: 16 sp
  • Więcej informacji o jednostce sp znajdziesz na stronie Material Design w sekcji Font size units (Jednostki rozmiaru czcionki).
Spacing Normalny

Przykładowy kod CSS

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

CSS

@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 funkcji Grounding z użyciem Map Google nie mają zastosowania.

Niedozwolone działania i obszary

W przypadku funkcji Grounding w Mapach 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 określonych w Warunkach nie będziesz używać groundingu z użyciem Map Google do działań o wysokim ryzyku, w tym do usług reagowania w sytuacjach kryzysowych. Nie możesz rozpowszechniać ani sprzedawać aplikacji, która oferuje Grounding z Mapami 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 do odpowiadania na ich zapytania używane są dane z Map Google, 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 pozwoli utrzymać płynność działania aplikacji.
  • Wyłączanie, gdy nie jest potrzebne: grounding z Mapami Google jest domyślnie wyłączony. Włączaj ją ("tools": [{"googleMaps": {}}]) tylko wtedy, gdy zapytanie ma wyraźny kontekst geograficzny, aby zoptymalizować wydajność i koszty.

Ograniczenia

  • Zasięg geograficzny: obecnie funkcja Grounding w Mapach Google jest dostępna na całym świecie.
  • Obsługa modeli: funkcja Grounding with Google Maps jest obsługiwana tylko przez wybrane modele Gemini: Gemini 2.5 Flash-Lite, Gemini 2.5 Pro, Gemini 2.5 Flash i Gemini 2.0 Flash (ale nie 2.0 Flash Lite).
  • Dane wejściowe i wyjściowe w różnych formatach: grounding w Mapach 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 Grounding z użyciem Map Google jest domyślnie wyłączone. Musisz wyraźnie włączyć tę funkcję w żądaniach do interfejsu API.

Ceny i limity

Ceny groundingu z użyciem Map Google są oparte na zapytaniach. Obecna stawka to 25 USD za 1000 odpowiedzi. Żądanie jest wliczane do limitu tylko wtedy, gdy prompt zwróci co najmniej 1 wynik z Google Maps (czyli wynik zawierający co najmniej 1 źródło z Google Maps). 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

Ich możliwości znajdziesz na stronie przeglądu modelu.

Model Grounding z użyciem Map Google
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️

Co dalej?