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

Maps Grounding Lite

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

Инструменты

Maps Grounding Lite предоставляет LLM доступ к следующим функциям Google Карт:

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

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

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

Resolution API

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

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

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

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

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

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

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

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

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

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

Maps Grounding Lite также предлагается в пакетах Essentials и Pro Подписаться и сэкономить.

Квоты

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

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

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

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

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

Требования к совместимым БЯМ

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

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

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

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

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

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

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

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

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

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

Как настроить БЯМ для использования MCP-сервера

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

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

Чтобы включить API в проекте:

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

Как пройти аутентификацию с помощью ключа API

Вы можете использовать существующий ключ API с Maps Grounding Lite или создать новый, если включите сервис API Maps Grounding Lite как в облачном проекте 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 и сервисы выберите Учетные данные.
В верхнем меню выберите Создать учетные данные > Идентификатор клиента OAuth.
Если в проекте не настроено окно запроса доступа, нажмите Настроить окно запроса доступа и следуйте инструкциям на экране.
В разделе Показатели нажмите Создать клиент OAuth.
На экране Создать идентификатор клиента OAuth выберите тип приложения и введите название идентификатора клиента.
Укажите дополнительную информацию, относящуюся к типу вашего приложения. Например, если вы создаете веб-приложение, добавьте авторизованные URI для запросов браузера и сервера.
После создания клиента сохраните его идентификатор и секретный код.
При настройке хоста MCP или приложения MCP-сервера для доступа к Maps Grounding Lite передайте идентификатор и секретный код клиента OAuth. Также необходимо запросить следующую область действия: https://www.googleapis.com/auth/maps-platform.mapstools.

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

Как настроить доступ больших языковых моделей к MCP-серверу Maps Grounding Lite

После того как вы создадите проект Google Cloud с включенным сервисом Maps Grounding Lite API и получите действительные учетные данные, например ключ API или идентификатор и секрет клиента OAuth, вы сможете настроить LLM для доступа к серверу MCP, следуя документации по конфигурации MCP и используя URL сервера Maps Grounding Lite MCP: 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

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

Шаг 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` существует

Убедитесь, что в том же каталоге, где находится файл agent.py, есть файл __init__.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"
            }
        })
    ],
});

Как отправить отзыв

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