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

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

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

Начать

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

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

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

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

Как работает функция определения местоположения с помощью Google Maps

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

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

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

Почему и когда использовать функцию Grounding в Google Maps

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

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

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

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

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

Функция определения местоположения с помощью Google Maps поддерживает множество сценариев использования, учитывающих местоположение.

Обработка вопросов, специфичных для конкретного места.

Ask detailed questions about a specific place to get answers based on Google user reviews and other Maps data.

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

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

Предоставление персонализации на основе местоположения.

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

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

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

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

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

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

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
    }],
});

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

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

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

Проинформируйте пользователя об использовании ресурсов Google Maps.

С каждым результатом поиска в Google Maps Grounded вы будете получать аннотации к исходному коду блоков содержимого шага model_output , которые поддерживают каждый ответ. Возвращаются следующие метаданные:

• исходный URL
• имя

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

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

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

Для каждой аннотации источника необходимо сгенерировать предварительный просмотр ссылки в соответствии со следующими требованиями:

• Укажите в качестве источника Google Maps, следуя рекомендациям Google Maps по указанию авторства текста.
• Отобразить имя источника, указанное в ответе.
• Ссылка на источник url в аннотации.

Рекомендации Google Maps по указанию авторства текста

При указании источников Google Maps в тексте следуйте этим рекомендациям:

• Не изменяйте текст Google Maps никаким образом:
  • Не меняйте регистр букв в названии Google Maps.
  • Не переносите Google Maps на несколько строк.
  • Не следует локализовать Google Maps на другой язык.
  • Предотвратите перевод Google Maps браузерами, используя HTML-атрибут translate="no".

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

Передовые методы

• Укажите местоположение пользователя: для получения наиболее релевантных и персонализированных ответов всегда указывайте latitude и longitude в настройках инструмента google_maps если местоположение пользователя известно.
• Отображение контекстного виджета Google Maps: Контекстный виджет отображается с использованием контекстного токена google_maps_widget_context_token , который возвращается в ответе API Gemini и может использоваться для отображения визуального контента из Google Maps.
• Проинформируйте конечных пользователей: Четко объясните конечным пользователям, что данные Google Maps используются для ответа на их запросы, особенно когда этот инструмент включен.
• Отключайте, когда не требуется: функция определения географического контекста с помощью Google Maps по умолчанию отключена. Включайте ее ( "tools": [{"type": "google_maps"}] только тогда, когда запрос имеет четкий географический контекст, чтобы оптимизировать производительность и снизить затраты.

Ограничения

• В настоящее время функция Grounding with Google Maps поддерживает только подсказки и ответы на английском языке.
• Данный инструмент может быть недоступен во всех регионах.
• Результаты могут различаться в зависимости от точности определения местоположения и доступных картографических данных.
• Географический охват: функция Grounding with Google Maps доступна по всему миру.
• Состояние по умолчанию: Инструмент «Приземление с помощью Google Maps» по умолчанию отключен. Вам необходимо явно включить его в своих запросах к API.

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

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

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

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

Следующие модели поддерживают функцию "Земля с Google Maps":

Поддерживаемые комбинации инструментов

В моделях Gemini 3 поддерживается комбинирование встроенных инструментов (например, определение местоположения с помощью Google Maps) с пользовательскими инструментами (вызов функций). Подробнее см. на странице с описанием комбинаций инструментов .

Что дальше?

• Узнайте о других доступных инструментах .
• Чтобы узнать больше о передовых методах ответственного использования ИИ и фильтрах безопасности API Gemini, см. руководство по настройкам безопасности .