Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Maps Grounding Lite

Google Maps Platform Grounding Lite – это сервис с поддержкой протокола контекста модели (MCP), который позволяет легко заземлять приложения ИИ с помощью надежных геопространственных данных из Google Карт. Сервер MCP предоставляет инструменты, которые позволяют LLM получать доступ к функциям, связанным с местами, погодой и маршрутами, а также преобразовывать названия мест и URL Google Карт в идентификаторы мест. Вы можете попробовать Maps Grounding Lite, включив его в любом инструменте, который поддерживает серверы MCP.

Инструменты

Maps Grounding Lite предоставляет инструменты, которые позволяют LLM получать доступ к следующим возможностям Google Карт:

Поиск мест. Запрашивайте информацию о местах и получайте созданные ИИ сводки данных о них, а также идентификаторы мест, координаты широты и долготы и ссылки на Google Карты для каждого места, включенного в сводку. Полученные идентификаторы мест и координаты можно использовать с другими API платформы Google Карт, чтобы показывать места на карте.
Погода. Запрашивает информацию о погоде и возвращает текущие условия, почасовые и ежедневные прогнозы.
Compute Routes. Запрашивайте информацию о пеших и автомобильных маршрутах между двумя точками и получайте данные о расстоянии и времени в пути.

Примечание. Maps Grounding Lite не предоставляет пошаговые маршруты, направления, информацию о дорожном движении в реальном времени или навигационные данные.
Разрешение названий и Разрешение URL Карт. Сопоставление названий мест, адресов и URL Google Карт с идентификаторами мест. Подробнее о Resolution API…

Включив сервер MCP Maps Grounding Lite, вы разрешите LLM вызывать новые инструменты, которые предоставляют дополнительную информацию для обоснования перечисленных выше типов данных. Хотя LLM может использовать эту дополнительную информацию для контекста, ответ, который в конечном итоге генерирует LLM, может не включать точную информацию, возвращенную сервером MCP. Проверяйте точность сгенерированных ответов.

Resolution API

В Maps Grounding Lite есть Resolution API, который позволяет преобразовывать текст и URL местоположений в свободной форме в структурированные идентификаторы мест Google Карт. Resolution API доступен в виде методов REST и инструментов на сервере MCP Maps Grounding Lite:

Resolve names (REST, MCP) – сопоставление пакета названий или адресов местоположений с конкретными объектами мест на Google Картах. Это полезно для привязки неструктурированных пользовательских запросов к стабильным идентификаторам мест.
Resolve Maps URLs (REST, MCP) – сопоставление группы URL Google Карт с определенными объектами мест. Поддерживаются стандартные и сокращенные URL мест.

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

Подробную информацию вы найдете в статье Maps Tools Resolution API.

Попробуйте пример приложения Maps Grounding Lite (откроется в новой вкладке)

Оплата и квоты

Как взимается оплата

При использовании модели оплаты по мере использования платформы Google Карт использование Maps Grounding Lite рассчитывается для каждого запроса, где каждый запрос представляет собой одно платежное событие. Использование отслеживается отдельно для каждого кода продукта. В счете будет указана строка для каждого SKU, а также общая сумма к оплате. Подробнее об отчетах…

Подробные сведения о ценах приведены в основной таблице цен и таблице цен для Индии.

Запросы к Resolution API (ResolveNames и ResolveMapsUrls) не оплачиваются. Они относятся к коду Places API Text Search Essentials (IDs Only).

Maps Grounding Lite также входит в пакеты Essentials и Pro. Оформите подписку, чтобы сэкономить.

Квоты

Для инструментов и API, предоставляемых Maps Grounding Lite, действуют следующие квоты:

Поиск мест: 300 запросов в минуту на проект.
Поиск погоды: 300 запросов в минуту на проект.
Расчет маршрутов: 300 запросов в минуту на проект.
Разрешение имен: 600 запросов в минуту на проект.
Resolve Maps URLs: 600 запросов в минуту на проект.

Каждый запрос к Resolution API считается за один запрос, независимо от того, сколько элементов он содержит.

Правила и условия использования

Использование Maps Grounding Lite регулируется Условиями использования платформы Google Карт, включая специальные условия для этого сервиса. В этом разделе описаны дополнительные требования к использованию сервиса Maps Grounding Lite, в том числе совместимые LLM и требования к указанию авторства.

Требования к совместимым LLM

Вы можете использовать Maps Grounding Lite только с LLM, которая соответствует Условиям использования платформы Google Карт.

Например, вы должны убедиться, что Контент Google Карт не кешируется, не хранится и не используется для улучшения выбранной вами LLM. Прежде чем использовать Maps Grounding Lite, ознакомьтесь с Условиями использования для каждой модели, которую вы планируете использовать с Maps Grounding Lite. Запрещено использовать Maps Grounding Lite с моделями, которые применяют входные данные для обучения или улучшения. Вы несете ответственность за то, чтобы использование модели полностью соответствовало ограничениям в отношении контента Google Карт, указанным в Условиях использования платформы Google Карт, включая условия для отдельных сервисов.

Требования к указанию авторства для источников Google Карт

Каждый ответ инструмента Maps Grounding Lite содержит источники. При показе результатов, полученных с помощью инструментов Maps Grounding Lite, вы должны указать связанные источники Google Карт в соответствии со следующими требованиями:

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

Источники для инструмента "Поиск мест"

Поле search_places tool places содержит источники, подтверждающие summary. Для places возвращаются следующие метаданные:

place (название ресурса)
id
location
googleMapsLinks

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

Укажите Google Карты в качестве источника, следуя рекомендациям по атрибуции текста в Maps Grounding Lite.
Укажите ссылку на источник, используя places.googleMapsLinks.placeUrl из ответа.

Настройте LLM для использования MCP-сервера

Чтобы использовать Maps Grounding Lite, вам нужен облачный проект Google Cloud с включенным API-сервисом Maps Grounding Lite, а также ключ API или идентификатор клиента OAuth. Затем вы можете настроить LLM для доступа к серверу MCP. MCP-сервер Grounding Lite использует потоковый транспорт HTTP.

Включите сервис Maps Grounding Lite в облачном проекте Google Cloud.

Чтобы включить API в проекте, выполните следующие действия:

В консоли Google Cloud выберите проект, который хотите использовать для Maps Grounding Lite.
Включите оплату для проекта в Google Cloud Console.
Включите Maps Grounding Lite в библиотеке API Google Cloud Console.

Аутентификация с помощью ключа API

Вы можете использовать существующий ключ API с Maps Grounding Lite или создать новый. Главное – включить сервис Maps Grounding Lite API как в облачном проекте Google Cloud, так и в ключе.

Чтобы выполнить аутентификацию с помощью ключа API, сделайте следующее:

Создайте или настройте ключ API, следуя инструкциям в статье Начало работы с платформой Google Карт.
Передайте ключ MCP-серверу, используя заголовок X-Goog-Api-Key. Его нужно указать в качестве специального HTTP-заголовка в конфигурации MCP-инструмента LLM.

Аутентификация с помощью OAuth

Чтобы выполнить аутентификацию с помощью OAuth, создайте учетные данные OAuth и передайте их хосту MCP или приложению сервера MCP.

Чтобы выполнить аутентификацию с помощью OAuth:

В консоли Google Cloud выберите проект, который хотите использовать для Maps Grounding Lite.
В меню API & Services (API и сервисы) выберите Credentials (Учетные данные).
В верхнем меню выберите Создать учетные данные > Идентификатор клиента OAuth.
Если в проекте не настроено окно запроса доступа, нажмите Настроить окно запроса доступа и следуйте инструкциям на экране.
В разделе Показатели нажмите Создать клиент OAuth.
На экране Create OAuth client ID (Создать идентификатор клиента OAuth) выберите тип приложения и введите название идентификатора клиента.
Укажите дополнительные сведения, относящиеся к типу вашего приложения. Например, если вы создаете веб-приложение, добавьте авторизованные URI для запросов браузера и сервера.
После создания клиента сохраните идентификатор клиента и секретный код.
При настройке хоста или сервера MCP для доступа к Maps Grounding Lite передайте идентификатор клиента OAuth и секретный код. Также необходимо запросить следующую область действия: https://www.googleapis.com/auth/maps-platform.mapstools.

Подробнее о том, как использовать протокол OAuth 2.0 для доступа к API Google…

Настройте LLM для доступа к MCP-серверу Maps Grounding Lite

Когда у вас будет проект Google Cloud с включенным сервисом Maps Grounding Lite API и действительными учетными данными, например ключом API или идентификатором клиента OAuth и секретным ключом, вы сможете настроить доступ LLM к серверу MCP. Для этого следуйте инструкциям в документации по настройке MCP и используйте URL сервера MCP Maps Grounding Lite: https://mapstools.googleapis.com/mcp.

Подробнее о том, как настроить MCP в ИИ-приложении…

Как настроить Maps Grounding Lite с помощью Gemini CLI

В этом разделе приведен пример настройки сервера MCP Maps Grounding Lite с помощью Gemini CLI. Подробнее о серверах MCP с Gemini CLI…

После установки Gemini CLI вы можете использовать команду add, чтобы настроить сервер MCP Maps Grounding Lite:
```
gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-grounding-lite-mcp https://mapstools.googleapis.com/mcp
```
Если настройка выполнена успешно, вы увидите подтверждение того, что сервер добавлен в ваши пользовательские настройки.

Чтобы убедиться, что сервер работает правильно, выполните команду /mcp list:

> /mcp list

Configured MCP servers:

maps-grounding-lite-mcp - Ready (5 tools)
Tools:
-   compute_routes
-   lookup_weather
-   resolve_maps_urls
-   resolve_names
-   search_places

Начните задавать вопросы о Картах с помощью CLI. Например, скажите "Порекомендуй мне рестораны в Маунтин-Вью". Модель должна вызвать инструмент search_places от вашего имени.

Настройка Grounding Lite с помощью Agent Development Kit (ADK)

В этом разделе приведены примеры настройки сервера Grounding Lite MCP с помощью Agent Development Kit (ADK) и Python, Java или TypeScript.

Python

Полную реализацию этого примера можно найти на GitHub в репозитории adk-samples.

Шаг 1. Определите агент с помощью `McpToolset` для Grounding Lite на платформе Google Карт

Измените файл agent.py. Замените YOUR_GOOGLE_MAPS_API_KEY своим ключом API.

# ./adk_agent_samples/mcp_agent/agent.py
import os
from google.adk.agents.llm_agent import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# Retrieve the API key from an environment variable or directly insert it.
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY")
if not GOOGLE_MAPS_API_KEY:
    GOOGLE_MAPS_API_KEY = "YOUR_GOOGLE_MAPS_API_KEY_HERE"

if GOOGLE_MAPS_API_KEY == "YOUR_GOOGLE_MAPS_API_KEY_HERE":
    print("WARNING: GOOGLE_MAPS_API_KEY is not set.")

root_agent = Agent(
    model='gemini-flash-latest',
    name='travel_planner_agent',
    description='A helpful assistant for planning travel routes.',
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url="https://mapstools.googleapis.com/mcp",
                headers={
                    "X-Goog-Api-Key": GOOGLE_MAPS_API_KEY,
                    "Content-Type": "application/json",
                    "Accept": "application/json, text/event-stream"
                }
            )
        )
    ]
)

Шаг 2. Убедитесь, что файл `init.py` существует

Убедитесь, что файл __init__.py находится в том же каталоге, что и agent.py:

from . import agent

Шаг 3. Запустите `adk web` и начните работу

Задайте переменную среды.
Задайте ключ Google Maps API в качестве переменной среды в терминале:
```
export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
        
```
Запустите adk web.
Чтобы запустить веб-интерфейс ADK, выполните следующую команду:
```
adk web
        
```
Взаимодействие с интерфейсом:
- Выберите сеть travel_planner_agent.
- Попробуйте запросы, например:
  - "Завтра я буду в Сан-Франциско. Какая сейчас погода?"
  - "Найди кофейни рядом с парком "Золотые ворота".
  - "Проложи маршрут от GooglePlex до аэропорта Сан-Франциско".

Java

Определите агент, который инициализирует McpToolset в Java. Если вы не используете переменную среды, замените YOUR_GOOGLE_MAPS_API_KEY_HERE на полученный ключ API.

package agents;

import com.google.adk.agents.LlmAgent;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.SessionKey;
import com.google.adk.tools.mcp.McpToolset;
import com.google.adk.tools.mcp.StreamableHttpServerParameters;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import java.util.HashMap;
import java.util.Map;

public class MapsAgentCreator {
    public static void main(String[] args) {
        String googleMapsApiKey = System.getenv("GOOGLE_MAPS_API_KEY");
        if (googleMapsApiKey == null || googleMapsApiKey.trim().isEmpty()) {
            googleMapsApiKey = "YOUR_GOOGLE_MAPS_API_KEY_HERE";
            if ("YOUR_GOOGLE_MAPS_API_KEY_HERE".equals(googleMapsApiKey)) {
                System.out.println("WARNING: GOOGLE_MAPS_API_KEY is not set.");
            }
        }

        Map<String, String> headers = new HashMap<>();
        headers.put("X-Goog-Api-Key", googleMapsApiKey);
        headers.put("Content-Type", "application/json");
        headers.put("Accept", "application/json, text/event-stream");

        StreamableHttpServerParameters serverParams =
                StreamableHttpServerParameters.builder("https://mapstools.googleapis.com/mcp")
                        .headers(headers)
                        .build();

        try (McpToolset toolset = new McpToolset(serverParams)) {
            LlmAgent agent = LlmAgent.builder()
                    .model("gemini-flash-latest")
                    .name("travel_planner_agent")
                    .description("A helpful assistant for planning travel routes.")
                    .tools(toolset)
                    .build();

            System.out.println("Agent created: " + agent.name());

            InMemoryRunner runner = new InMemoryRunner(agent);
            String userId = "maps-user-" + System.currentTimeMillis();
            String sessionId = "maps-session-" + System.currentTimeMillis();
            String promptText =
                    "Please give me directions to the nearest pharmacy to Madison Square Garden.";

            SessionKey sessionKey = runner.sessionService()
                    .createSession(runner.appName(), userId, null, sessionId)
                    .blockingGet()
                    .sessionKey();
            System.out.println("Session created: " + sessionId + " for user: " + userId);

            Content promptContent = Content.fromParts(Part.fromText(promptText));
            System.out.println("\nSending prompt: \"" + promptText + "\" to agent...\n");

            runner.runAsync(sessionKey, promptContent)
                    .blockingForEach(event -> {
                        System.out.println("Event received: " + event.toJson());
                    });
        } catch (Exception e) {
            System.err.println("An error occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

TypeScript

Определите агент, который инициализирует MCPToolset в TypeScript:

import 'dotenv/config';
import {LlmAgent, MCPToolset} from "@google/adk";

const googleMapsApiKey = process.env.GOOGLE_MAPS_API_KEY;
if (!googleMapsApiKey) {
    console.warn("WARNING: GOOGLE_MAPS_API_KEY is not set.");
    throw new Error(
        'GOOGLE_MAPS_API_KEY is not provided, please run "export GOOGLE_MAPS_API_KEY=YOUR_ACTUAL_KEY" to add that.'
    );
}

export const rootAgent = new LlmAgent({
    model: "gemini-flash-latest",
    name: "travel_planner_agent",
    description: "A helpful assistant for planning travel.",
    tools: [
        new MCPToolset({
            type: "SseConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            headers: {
                "X-Goog-Api-Key": googleMapsApiKey,
                "Content-Type": "application/json",
                "Accept": "application/json, text/event-stream"
            }
        })
    ],
});

Отправка отзыва

Чтобы поделиться отзывом о Maps Grounding Lite, используйте следующие формы: