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

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

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

Начать

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

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    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}")

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    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();

# Specifies the API revision to avoid breaking changes when they become default
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.5-flash",
    "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, что позволяет разработчикам отображать цитаты.

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

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

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

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

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

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

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

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

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

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    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}")

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    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();

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

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

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    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}")

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    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();

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

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

# This will only work for SDK newer than 2.0.0
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.5-flash",
    input=prompt,
    tools=[{
        "type": "google_maps",
        "latitude": 37.78193,
        "longitude": -122.40476
    }]
)
# ... code to process response

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    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
    }]
  });
}

main();

# Specifies the API revision to avoid breaking changes when they become default
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.5-flash",
    "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
    }]
  }'

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

В этом разделе описаны требования к использованию сервиса 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 по умолчанию отключена. Включайте ее ( "tools": [{"type": "google_maps"}] только тогда, когда запрос имеет четкий географический контекст, чтобы оптимизировать производительность и снизить затраты.

Ограничения

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

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

Стоимость услуги "Приземление с помощью Google Maps" различается в зависимости от поколения модели:

• Модели Gemini 3: Ваш проект оплачивается за каждый поисковый запрос , который модель решает выполнить. Один поисковый запрос (ваш API-запрос к модели) может привести к тому, что модель выполнит несколько поисковых запросов для поиска необходимой информации. Каждый из этих запросов считается оплачиваемым использованием инструмента.
• В моделях Gemini 2.5 и более старых версиях: оплата за каждый поисковый запрос взимается отдельно. Запрос оплачивается только в том случае, если запрос успешно возвращает хотя бы один результат, соответствующий карте Google Maps, независимо от того, сколько отдельных поисковых запросов модель выполнила внутри себя для получения этого результата.

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

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

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

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

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

Что дальше?

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