‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

Maps Grounding Lite

Google Maps Platform Grounding Lite سرویسی با پشتیبانی از «پروتکل بافت مدل» (MCP) است که به‌راحتی برنامه‌های هوش مصنوعی شما را با داده‌های زمین‌مکانی قابل‌اعتماد از Google Maps مرتبط می‌کند. سرور MCP ابزارهایی را ارائه می‌دهد که به مدل‌های زبانی بزرگ اجازه می‌دهد به قابلیت‌های مربوط به مکان‌ها، آب‌وهوا، و مسیرها دسترسی داشته باشند و نام‌های مکان و نشانی‌های وب Google Maps را به «شناسه‌های مکان» تبدیل کنند. می‌توانید Maps Grounding Lite را با فعال کردن آن در هر ابزاری که از سرورهای MCP پشتیبانی می‌کند امتحان کنید.

ابزارها

‫Maps Grounding Lite ابزارهایی را ارائه می‌دهد که به مدل‌های زبانی بزرگ امکان می‌دهد به قابلیت‌های Google Maps زیر دسترسی داشته باشند:

جستجوی مکان‌ها: درخواست اطلاعات درباره مکان‌ها و دریافت خلاصه‌های داده‌های مکان تولیدشده با هوش مصنوعی، و همچنین شناسه‌های مکان، مختصات طول و عرض جغرافیایی، و پیوندهای Google Maps برای هریک از مکان‌های موجود در خلاصه. می‌توانید از «شناسه‌های مکان» و مختصات طول و عرض جغرافیایی برگردانده‌شده با دیگر میاناهای برنامه‌سازی کاربردی Google Maps Platform برای نمایش مکان‌ها روی نقشه استفاده کنید.
جستجوی آب‌وهوا: درخواست اطلاعات درباره آب‌وهوا و برگرداندن شرایط فعلی، پیش‌بینی‌های ساعتی، و پیش‌بینی‌های روزانه.
محاسبه مسیرها: درخواست اطلاعات درباره مسیرهای رانندگی یا پیاده‌روی بین دو مکان و برگرداندن اطلاعات مسافت و مدت مسیر.

توجه: Maps Grounding Lite مسیریابی گام‌به‌گام، مسیر، ترافیک هم‌زمان، یا اطلاعات ناوبری ارائه نمی‌دهد.
حل‌وفصل نام‌ها و حل‌وفصل نشانی‌های وب Maps: نام‌های مکان، نشانی‌ها، و نشانی‌های وب Google Maps را به «شناسه‌های مکان» حل‌وفصل کنید. برای اطلاعات بیشتر، Resolution API را ببینید.

فعال کردن سرور Maps Grounding Lite MCP به مدل‌های زبانی بزرگ امکان می‌دهد ابزارهای جدیدی را که سرور ارائه می‌دهد فراخوانی کنند تا اطلاعات زمینه‌ای بیشتری برای انواع داده‌های فهرست‌شده در بالا برگردانند. درحالی‌که مدل زبانی بزرگ می‌تواند از این اطلاعات اضافی برای بافتار استفاده کند، پاسخی که مدل زبانی بزرگ درنهایت تولید می‌کند ممکن است شامل اطلاعات دقیقی که سرور MCP برمی‌گرداند نباشد. باید صحت پاسخ تولیدشده را بررسی کنید.

Resolution API

‫Maps Grounding Lite میانای برنامه‌سازی کاربردی Resolution را ارائه می‌دهد که به شما امکان می‌دهد نوشتار مکان با قالب آزاد و نشانی‌های وب را به شناسه‌های مکان Google Maps ساختاریافته تبدیل کنید. Resolution API به‌صورت روش‌های REST و ابزارهایی در سرور Maps Grounding Lite MCP دردسترس است:

حل کردن نام‌ها (REST، MCP): حل کردن دسته‌ای از نام‌ها یا نشانی‌های مکان به نهادهای مکان خاص در Google Maps. این کار برای زمینه‌سازی پُرسمان‌های کاربر ساختارنیافته در «شناسه‌های مکان» پایدار مفید است.
حل کردن نشانی‌های وب Maps (REST، MCP): حل کردن دسته‌ای از نشانی‌های وب Google Maps برای نهادهای مکان خاص. قالب‌های پشتیبانی‌شده شامل نشانی‌های وب مکان استاندارد و نشانی‌های وب کوتاه می‌شود.

می‌توانید از «شناسه‌های جا» برگردانده‌شده با دیگر میاناهای برنامه‌سازی کاربردی Google Maps Platform استفاده کنید. هر پاسخ همچنین شامل پیوندی است که مکان‌های حل‌شده را به‌عنوان فهرستی در Google Maps ذخیره می‌کند.

برای اطلاعات بیشتر، Maps Tools Resolution API را ببینید.

برنامه نمونه Maps Grounding Lite را امتحان کنید (در برگه جدیدی باز می‌شود)

صورت‌حساب و سهمیه‌ها

نحوه صدور صورت‌حساب برای شما

با مدل قیمت‌گذاری پرداخت به اندازه استفاده «پلاتفرم Google Maps»، استفاده از Maps Grounding Lite برای هر درخواست محاسبه می‌شود، که هر درخواست نشان‌دهنده یک رویداد صورت‌حساب است. استفاده برای هر شناسه محصول ردیابی می‌شود. صورت‌حساب شما علاوه‌بر کل هزینه‌هایتان، یک مورد سطری برای هر SKU نشان می‌دهد. برای اطلاعات بیشتر، نمای کلی گزارش‌دهی را ببینید.

برای جزئیات قیمت‌گذاری، جدول قیمت‌گذاری اصلی و جدول قیمت‌گذاری هند را ببینید.

درخواست‌های ارسال‌شده به Resolution API (ResolveNames و ResolveMapsUrls) تحت شناسه محصول Places API Text Search Essentials (IDs Only) بدون هزینه صورت‌حساب می‌شوند.

Maps Grounding Lite ازطریق بسته‌های Essentials و Pro نیز ارائه می‌شود. برای صرفه‌جویی کردن، مشترک شوید.

سهمیه‌ها

سهمیه‌های زیر برای ابزارها و میاناهای برنامه‌سازی کاربردی ارائه‌شده توسط Maps Grounding Lite اعمال می‌شود:

جستجوی مکان‌ها: ۳۰۰ پُرسمان در دقیقه، برای هر پروژه.
جستجوی آب‌وهوا: ۳۰۰ پُرسمان در دقیقه، برای هر پروژه.
محاسبه کردن مسیرها: ۳۰۰ پُرسمان در دقیقه، برای هر پروژه.
حل کردن نام‌ها: ۶۰۰ پُرسمان در دقیقه، برای هر پروژه.
حل‌وفصل کردن نشانی‌های وب Maps: ۶۰۰ پرسمان در دقیقه، برای هر پروژه.

هر درخواست Resolution API، صرف‌نظر از تعداد موارد موجود در آن، به‌عنوان یک پُرسمان محسوب می‌شود.

خط‌مشی‌ها و شرایط خدمات

«مبانی‌مندی با Maps Lite» تابع شرایط خدمات پلاتفرم Google Maps است، ازجمله شرایط مختص سرویس برای این سرویس. این بخش الزامات اضافی استفاده از سرویس را برای Maps Grounding Lite، ازجمله مدل‌های زبانی بزرگ سازگار و الزامات ذکر منبع، شرح می‌دهد.

الزامات مدل‌های زبانی بزرگ سازگار

فقط می‌توانید از Maps Grounding Lite با مدل زبانی بزرگی استفاده کنید که با «شرایط خدمات پلاتفرم Google Maps» مطابقت داشته باشد.

برای مثال، شما مسئول هستید که مطمئن شوید «محتوای Google Maps» توسط مدل زبانی بزرگی که برای استفاده انتخاب می‌کنید ذخیره موقت، ذخیره، یا برای بهبود آن استفاده نمی‌شود. قبل‌از استفاده از Maps Grounding Lite، باید «شرایط خدمات» هر مدلی را که قصد دارید با Maps Grounding Lite استفاده کنید مرور کنید. نباید از Maps Grounding Lite با مدل‌هایی استفاده کنید که از داده‌های ورودی به مدل برای آموزش یا بهبود مدل استفاده می‌کنند. شما مسئول هستید که مطمئن شوید استفاده شما از مدل کاملاً با محدودیت‌های «محتوای Google Maps» در «شرایط خدمات Google Maps Platform»، ازجمله شرایط خاص سرویس، مطابقت دارد.

الزامات ذکر منبع برای منابع Google Maps

هر پاسخ ابزار از Maps Grounding Lite شامل منابع است. هنگام ارائه نتایجی که از ابزارهای ارائه‌شده توسط Maps Grounding Lite استفاده می‌کنند، باید منابع Google Maps مرتبط را به‌گونه‌ای درج کنید که الزامات زیر را برآورده کند:

منابع Google Maps باید بلافاصله پس‌از محتوای تولیدشده‌ای که منابع از آن پشتیبانی می‌کنند، آورده شود. به این محتوای تولیدشده برونداد مستند نیز گفته می‌شود.
منابع Google Maps باید در یک تعامل کاربر قابل‌مشاهده باشد.

منابع ابزار «جستجوی مکان‌ها»

فیلد places ابزار search_places منابعی را ارائه می‌دهد که از summary پشتیبانی می‌کنند. برای places، فراداده زیر برگردانده می‌شود:

place (نام منبع)
id
location
googleMapsLinks

برای هر مکان، باید پیش‌نمایش پیوندی تولید کنید که این الزامات را برآورده کند:

هر منبع را به Google Maps ارجاع دهید و رهنمودهای ارجاع نوشتاری Maps Grounding Lite را دنبال کنید.
بااستفاده از places.googleMapsLinks.placeUrl موجود در پاسخ، به منبع پیوند دهید.

پیکربندی کردن مدل‌های زبانی بزرگ برای استفاده از سرور MCP

برای استفاده از Maps Grounding Lite، ابتدا به یک پروژه Google Cloud نیاز دارید که سرویس API Maps Grounding Lite در آن فعال باشد، و همچنین به یک کلید API یا شناسه کارخواه OAuth نیاز دارید. سپس می‌توانید مدل‌های زبانی بزرگ را برای دسترسی به سرور MCP پیکربندی کنید. سرور Grounding Lite MCP از انتقال HTTP جاری‌سازی‌پذیر استفاده می‌کند.

سرویس Maps Grounding Lite را در پروژه Google Cloud خود فعال کنید

برای فعال کردن میانای برنامه‌سازی کاربردی در پروژه‌تان:

در کنسول Google Cloud، پروژه‌ای را که می‌خواهید برای Maps Grounding Lite استفاده کنید انتخاب کنید.
صورت‌حساب را برای پروژه در کنسول Google Cloud فعال کنید.
«مبانی‌مندی با Maps Lite» را در کتابخانه میانای برنامه‌سازی کاربردی کنسول Google Cloud فعال کنید.

اصالت‌سنجی بااستفاده از کلید میانای API

می‌توانید از کلید میانای برنامه‌سازی کاربردی موجود با Maps Grounding Lite استفاده کنید یا کلید جدیدی ایجاد کنید، به‌شرطی که سرویس میانای برنامه‌سازی کاربردی Maps Grounding Lite را هم در پروژه Google Cloud و هم در کلید فعال کنید.

برای اصالت‌سنجی بااستفاده از کلید میانای API:

با دنبال کردن مراحل شروع به کار با پلاتفرم Google Maps، کلید میانای برنامه‌سازی کاربردی ایجاد یا پیکربندی کنید.
کلید را بااستفاده از سرصفحه X-Goog-Api-Key به سرور MCP ارسال کنید. باید این را به‌عنوان سرصفحه HTTP سفارشی در پیکربندی ابزار MCP مدل زبانی بزرگ مشخص کنید.

اصالت‌سنجی بااستفاده از OAuth

می‌توانید با ایجاد اعتبارنامه‌های OAuth و ارسال آن‌ها به میزبان MCP یا برنامه سرور MCP، بااستفاده از OAuth اصالت‌سنجی کنید.

برای اصالت‌سنجی بااستفاده از OAuth:

در کنسول Google Cloud، پروژه‌ای را که می‌خواهید برای Maps Grounding Lite استفاده کنید انتخاب کنید.
در منو میانای برنامه‌سازی کاربردی و سرویس‌ها، اطلاعات کاربری را انتخاب کنید.
در منو بالایی، ایجاد اطلاعات کاربری > شناسه کارخواه OAuth را انتخاب کنید.
اگر پروژه صفحه رضایت پیکربندی‌شده ندارد، روی پیکربندی صفحه رضایت کلیک کنید و دستورالعمل‌های روی صفحه را دنبال کنید.
در بخش سنجه‌ها، روی ایجاد کارخواه OAuth کلیک کنید.
در صفحه ایجاد شناسه کارخواه OAuth، نوع برنامه را انتخاب کنید و نامی برای شناسه کارخواه وارد کنید.
جزئیات اضافی مربوط به نوع درخواستتان را مشخص کنید. برای مثال، اگر درحال ایجاد برنامه وب هستید، URIهای مجاز را برای درخواست‌های مرورگر و سرور اضافه کنید.
وقتی کارخواه ایجاد شد، شناسه و رمز کارخواه را ذخیره کنید.
هنگام پیکربندی میزبان MCP یا برنامه سرور MCP برای دسترسی به Maps Grounding Lite، شناسه کارخواه OAuth و رمز خود را ارسال کنید. همچنین باید حوزه زیر را درخواست کنید: https://www.googleapis.com/auth/maps-platform.mapstools.

برای اطلاعات بیشتر، استفاده از OAuth 2.0 برای دسترسی به Google APIs را ببینید.

پیکربندی مدل‌های زبانی بزرگ برای دسترسی به سرور MCP «مبانی‌مندی با Maps Lite»

وقتی پروژه Google Cloud با سرویس Maps Grounding Lite API فعال و اعتبارنامه معتبر، مثل کلید API یا شناسه کارخواه OAuth و رمز، داشته باشید، می‌توانید مدل‌های زبانی بزرگ را برای دسترسی به سرور MCP با دنبال کردن سند پیکربندی MCP مربوطه و استفاده از نشانی وب سرور MCP ‏Maps Grounding Lite پیکربندی کنید: https://mapstools.googleapis.com/mcp

برای اطلاعات بیشتر، پیکربندی MCP در برنامه هوش مصنوعی را ببینید.

پیکربندی کردن Maps Grounding Lite با Gemini CLI

این بخش نمونه‌ای از نحوه پیکربندی سرور Maps Grounding Lite MCP بااستفاده از Gemini CLI ارائه می‌دهد. برای جزئیات بیشتر، سرورهای MCP با Gemini CLI را ببینید.

پس‌از نصب Gemini CLI، می‌توانید از فرمان add برای پیکربندی سرور Maps Grounding Lite MCP استفاده کنید:
```
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 شروع به پرسیدن سؤالات مرتبط با Maps کنید. برای مثال، بگویید «چند رستوران در Mountain View به من توصیه کن» که باید ابزار search_places را ازطرف شما فراخوانی کند.

پیکربندی Grounding Lite با Agent Development Kit (ADK)

این بخش نمونه‌هایی را ارائه می‌دهد که نحوه پیکربندی سرور Grounding Lite MCP را بااستفاده از Agent Development Kit (ADK) و Python،‏ Java، یا TypeScript نشان می‌دهد.

Python

می‌توانید پیاده‌سازی کامل این نمونه را در GitHub در مخزن adk-samples پیدا کنید.

مرحله ۱: تعریف کردن «نماینده» با `McpToolset` برای Google Maps Grounding Lite

فایل agent.py را اصلاح کنید. YOUR_GOOGLE_MAPS_API_KEY را با کلید میانای برنامه‌سازی کاربردی واقعی خودتان جایگزین کنید.

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

مرحله ۲: مطمئن شوید `init.py` وجود دارد

مطمئن شوید که __init__.py در همان دایرکتوری agent.py شما قرار دارد:

from . import agent

مرحله ۳: اجرا کردن `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 به SFO را دریافت کن.»

جاوا

عاملی را تعریف کنید که 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، از فرم‌های زیر استفاده کنید: