Заземление с помощью Google Maps

Технология Grounding with Google Maps объединяет генеративные возможности Gemini с обширными, фактологическими и актуальными данными Google Карт. Эта функция позволяет разработчикам легко интегрировать функции определения местоположения в свои приложения. Когда контекст запроса пользователя связан с данными Карт, модель Gemini использует Google Карты для предоставления фактически точных и актуальных ответов, соответствующих указанному пользователем местоположению или региону.

• Точные ответы с учетом местоположения: используйте обширные и актуальные данные Google Maps для географически специфичных запросов.
• Расширенная персонализация: индивидуальные рекомендации и информация на основе указанных пользователем местоположений.
• Контекстная информация и виджеты: Контекстные токены для отображения интерактивных виджетов Google Maps вместе с сгенерированным контентом.

Начать

В этом примере показано, как интегрировать Grounding с Google Maps в ваше приложение для предоставления точных ответов на запросы пользователей с учётом их местоположения. Запрос запрашивает локальные рекомендации с необязательным указанием местоположения пользователя, что позволяет модели Gemini использовать данные Google Maps.

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

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

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

Как работает заземление с помощью Google Maps

Grounding with Google Maps интегрирует API Gemini с экосистемой Google Geo, используя API Карт в качестве источника данных. Когда запрос пользователя содержит географический контекст, модель Gemini может активировать инструмент Grounding with Google Maps. Затем модель может генерировать ответы, основанные на данных Google Maps, соответствующих указанному местоположению.

Процесс обычно включает в себя:

1. Запрос пользователя: пользователь отправляет запрос в ваше приложение, потенциально включающий географический контекст (например, «кофейни рядом со мной», «музеи в Сан-Франциско»).
2. Вызов инструмента: Модель Gemini, распознавая географическое назначение, вызывает инструмент Grounding with Google Maps. Этот инструмент может быть дополнительно снабжен latitude и longitude пользователя для получения результатов с учётом его местоположения.
3. Извлечение данных: Служба Grounding with Google Maps запрашивает у Google Maps соответствующую информацию (например, места, отзывы, фотографии, адреса, часы работы).
4. Надежная генерация: полученные данные карт используются для формирования ответа модели Gemini, обеспечивая фактическую точность и релевантность.
5. Ответ и токен виджета: Модель возвращает текстовый ответ, включающий ссылки на источники Google Карт. При необходимости ответ API может также содержать токен google_maps_widget_context_token , позволяющий разработчикам отображать контекстный виджет Google Карт в своих приложениях для визуального взаимодействия.

Зачем и когда использовать Grounding с Google Maps

Сервис Grounding with Google Maps идеально подходит для приложений, которым требуется точная, актуальная и привязанная к местоположению информация. Он улучшает пользовательский опыт, предоставляя релевантный и персонализированный контент на основе обширной базы данных Google Maps, содержащей более 250 миллионов мест по всему миру.

Вам следует использовать Grounding with Google Maps, когда вашему приложению необходимо:

• Давайте полные и точные ответы на вопросы, касающиеся географии.
• Создавайте интерактивные планировщики поездок и местных гидов.
• Рекомендовать интересные места на основе местоположения и предпочтений пользователя, например рестораны или магазины.
• Создавайте решения с учетом местоположения для социальных сетей, магазинов или служб доставки еды.

Использование Google Maps особенно эффективно в случаях, когда решающее значение имеют близость и актуальные фактические данные, например, при поиске «лучшей кофейни рядом со мной» или при получении маршрута.

Методы и параметры API

Grounding with Google Maps доступен через API Gemini в качестве инструмента в методе generateContent . Вы можете включить и настроить Grounding with Google Maps, добавив объект googleMaps в параметр tools вашего запроса.

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

Инструмент googleMaps может дополнительно принимать логический параметр enableWidget , который управляет возвращением поля googleMapsWidgetContextToken в ответе. Это может использоваться для отображения контекстного виджета «Места» .

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

Кроме того, инструмент поддерживает передачу контекстного местоположения как toolConfig .

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

Понимание реакции заземления

Если ответ успешно подтверждён данными Google Карт, он включает поле groundingMetadata . Эти структурированные данные необходимы для проверки заявлений и создания полноценного цитирования в вашем приложении, а также для соответствия требованиям к использованию сервиса.

{
  "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/..."
      }
    }
  ]
}

API Gemini возвращает следующую информацию с помощью groundingMetadata :

• groundingChunks : Массив объектов, содержащих источники maps ( uri , placeId и title ).
• groundingSupports : Массив фрагментов для связи текста ответа модели с источниками в groundingChunks . Каждый фрагмент связывает текстовый фрагмент (определяемый startIndex и endIndex ) с одним или несколькими индексами groundingChunkIndices . Это ключ к созданию встроенных ссылок.
• googleMapsWidgetContextToken : текстовый токен, который можно использовать для отображения контекстного виджета «Места» .

Фрагмент кода, показывающий, как отображать встроенные ссылки в тексте, см. в примере в документации Grounding with Google Search.

Отобразить контекстный виджет Google Maps

Чтобы использовать возвращенный googleMapsWidgetContextToken , вам необходимо загрузить Google Maps JavaScript API .

Варианты использования

Grounding with Google Maps поддерживает различные варианты использования с учётом местоположения. В следующих примерах показано, как различные подсказки и параметры могут эффективно использовать Grounding with Google Maps. Информация в результатах поиска Grounding в Google Maps может отличаться от фактических условий.

Обработка вопросов, связанных с конкретным местом

Задавайте подробные вопросы о конкретном месте, чтобы получить ответы на основе отзывов пользователей Google и других данных Карт.

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})')
  ```

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

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

Обеспечение персонализации на основе местоположения

Получайте рекомендации, соответствующие предпочтениям пользователя и конкретному географическому региону.

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

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

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

Помощь в планировании маршрута

Создавайте многодневные планы с указаниями и информацией о различных местах, идеально подходящие для путешествий.

В этом примере googleMapsWidgetContextToken был запрошен при включении виджета в инструменте Google Карт. После включения возвращаемый токен можно использовать для отображения контекстного виджета «Места» с помощью <gmp-places-contextual> component из JavaScript API Google Карт.

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>')

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

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

После отображения виджет будет выглядеть примерно так:

Требования к использованию услуг

В этом разделе описываются требования к использованию сервиса Grounding with Google Maps.

Информировать пользователя об использовании источников Google Maps

С каждым результатом поиска Google Maps Grounded вы получаете источники в groundingChunks , которые поддерживают каждый ответ. Также возвращаются следующие метаданные:

• исходный URI
• заголовок
• ИДЕНТИФИКАТОР

При представлении результатов Grounding with Google Maps необходимо указать соответствующие источники Google Maps и сообщить пользователям следующее:

• Источники Google Карт должны располагаться непосредственно после сгенерированного контента, поддерживаемого этими источниками. Этот сгенерированный контент также называется «основанным результатом Google Карт».
• Источники Google Maps должны быть доступны для просмотра в течение одного взаимодействия пользователя.

Отображение источников Google Maps с помощью ссылок Google Maps

Для каждого источника в groundingChunks и в grounding_chunks.maps.placeAnswerSources.reviewSnippets необходимо создать предварительный просмотр ссылки в соответствии со следующими требованиями:

• Укажите источник для каждого источника в Картах Google, следуя правилам атрибуции текста в Картах Google.
• Отобразить название источника, указанное в ответе.
• Ссылка на источник с использованием uri или googleMapsUri из ответа.

На этих изображениях показаны минимальные требования для отображения источников и ссылок Google Maps.

Вы можете свернуть вид источников.

Дополнительно: дополните предварительный просмотр ссылки дополнительным контентом, например:

• Значок Google Maps вставляется перед текстом ссылки Google Maps.
• Фотография из исходного URL ( og:image ).

Дополнительную информацию о некоторых поставщиках данных Google Maps и условиях их лицензий см. в юридических уведомлениях Google Maps и Google Earth .

Правила атрибуции текста в Google Картах

При указании в тексте источников Google Maps следуйте следующим правилам:

• Не изменяйте текст Google Maps каким-либо образом:
  • Не меняйте заглавные буквы в Google Картах.
  • Не размещайте Google Maps на нескольких строках.
  • Не локализуйте Google Maps на другой язык.
  • Запретите браузерам переводить Google Maps с помощью HTML-атрибута translate="no".
• Оформите текст Google Maps, как описано в следующей таблице:

Пример CSS

Следующий CSS-код отображает Google Maps с соответствующим типографским стилем и цветом на белом или светлом фоне.

@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;
}

Контекстный токен, идентификатор места и идентификатор отзыва

Данные Google Карт включают контекстный токен, идентификатор места и идентификатор отзыва. Вы можете кэшировать, хранить и экспортировать следующие данные ответа:

• googleMapsWidgetContextToken
• placeId
• reviewId

Ограничения по кэшированию, предусмотренные Условиями использования Google Maps, не применяются.

Запрещенная деятельность и территория

В приложении «Grounding with Google Maps» действуют дополнительные ограничения на определённый контент и действия для обеспечения безопасности и надёжности платформы. Помимо ограничений использования, указанных в Условиях, вы не имеете права использовать приложение «Grounding with Google Maps» для мероприятий с высоким уровнем риска, включая экстренные службы. Вы не имеете права распространять или рекламировать своё приложение, предлагающее «Grounding with Google Maps», на запрещённой территории. В настоящее время запрещёнными территориями являются:

• Китай
• Крым
• Куба
• Донецкая Народная Республика
• Иран
• Луганская Народная Республика
• Северная Корея
• Сирия
• Вьетнам

Этот список может время от времени обновляться.

Лучшие практики

• Укажите местоположение пользователя: для получения наиболее релевантных и персонализированных ответов всегда включайте user_location (широту и долготу) в конфигурацию googleMapsGrounding , если местоположение пользователя известно.
• Отображение контекстного виджета Google Карт: Контекстный виджет отображается с помощью токена контекста googleMapsWidgetContextToken , который возвращается в ответе API Gemini и может использоваться для отображения визуального контента из Google Карт. Подробнее о контекстном виджете см. в разделе «Настройка с виджетом Google Карт» в руководстве разработчика Google.
• Информирование конечных пользователей: четко информируйте конечных пользователей о том, что данные Google Maps используются для ответа на их запросы, особенно если этот инструмент включен.
• Контроль задержки: для разговорных приложений убедитесь, что задержка P95 для заземленных ответов остается в пределах приемлемых пороговых значений, чтобы обеспечить бесперебойную работу пользователя.
• Отключайте, когда не требуется: привязка к Google Картам по умолчанию отключена. Включайте её ( "tools": [{"googleMaps": {}}] ) только тогда, когда запрос имеет чёткий географический контекст, для оптимизации производительности и затрат.

Ограничения

• Географический охват: в настоящее время Grounding with Google Maps доступен по всему миру.
• Поддержка моделей: Только определенные модели Gemini поддерживают функцию Grounding with Google Maps: Gemini 2.5 Flash-Lite, Gemini 2.5 Pro, Gemini 2.5 Flash и Gemini 2.0 Flash (но не 2.0 Flash Lite).
• Мультимодальные входы/выходы: Grounding with Google Maps в настоящее время не поддерживает мультимодальные входы и выходы, выходящие за рамки текста и контекстных виджетов карты.
• Состояние по умолчанию: инструмент «Grounding with Google Maps» по умолчанию отключен. Вам необходимо явно включить его в запросах API.

Ограничения по ценам и тарифам

Стоимость использования Google Карт рассчитывается на основе количества запросов. Текущая ставка составляет 25 долларов США за 1000 запросов с заземлением . Запрос учитывается в квоте только в том случае, если запрос успешно возвращает хотя бы один результат с заземлением Google Карт (т.е. результаты, содержащие хотя бы один источник Google Карт). Если в рамках одного запроса в Google Карты отправлено несколько запросов, это считается одним запросом при подсчёте лимита.

Подробную информацию о ценах смотрите на странице цен Gemini API .

Поддерживаемые модели

С их возможностями можно ознакомиться на странице обзора моделей .

Что дальше?

• Попробуйте раздел «Заземление с поиском Google» в кулинарной книге API Gemini .
• Узнайте о других доступных инструментах, таких как вызов функций .
• Дополнительную информацию о передовых методах ответственного ИИ и фильтрах безопасности API Gemini см. в руководстве по настройкам безопасности .