‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

Maps Grounding Lite

‫Google Maps Platform Grounding Lite הוא שירות עם תמיכה ב-Model Context Protocol ‏(MCP) שמאפשר לבסס בקלות את אפליקציות ה-AI על נתונים גיאו-מרחביים מהימנים ממפות Google. שרת ה-MCP מספק כלים שמאפשרים למודלים גדולים של שפה (LLM) לגשת ליכולות שקשורות למקומות, למזג האוויר ולמסלולים, ולפתור שמות של מיקומים וכתובות URL של מפות Google למזהי מקומות. כדי לנסות את Maps Grounding Lite, אתם יכולים להפעיל אותו בכל כלי שתומך בשרתי MCP.

כלים

‫Maps Grounding Lite מספק כלים שמאפשרים למודלי LLM לגשת ליכולות הבאות של מפות Google:

חיפוש מקומות: בקשת מידע על מקומות וקבלת סיכומים של נתוני מקומות שנוצרו על ידי AI, וגם מזהי מקומות, קואורדינטות של קווי רוחב ואורך וקישורים למפות Google לכל אחד מהמקומות שנכללים בסיכום. אתם יכולים להשתמש במזהי המקומות ובקואורדינטות של קווי האורך והרוחב שמוחזרים עם ממשקי API אחרים של הפלטפורמה של מפות Google כדי להציג מקומות במפה.
חיפוש מזג אוויר: בקשת מידע על מזג האוויר והחזרת התנאים הנוכחיים, תחזיות לפי שעה ותחזיות יומיות.
חישוב מסלולים: בקשת מידע על מסלולי נסיעה או הליכה בין שני מיקומים, וקבלת מידע על המרחק ומשך הזמן של המסלול.

הערה: Maps Grounding Lite לא מספקת מסלולים מפורטים, הוראות הגעה, מידע על מצב התנועה בזמן אמת או מידע על ניווט.
זיהוי שמות וזיהוי כתובות URL במפות Google: זיהוי שמות של מיקומים, כתובות וכתובות URL במפות Google והמרתם למזהי מקומות. מידע נוסף מופיע במאמר בנושא Resolution API.

הפעלת שרת Maps Grounding Lite MCP מאפשרת למודלים גדולים של שפה (LLM) להפעיל את הכלים החדשים שהשרת חושף, כדי להחזיר מידע נוסף על עיגון לסוגי הנתונים שמפורטים למעלה. ה-LLM יכול להשתמש במידע הנוסף הזה כהקשר, אבל התשובה שהוא ייצור בסופו של דבר לא בהכרח תכלול את המידע המדויק שהוחזר משרת ה-MCP. חשוב לבדוק את התשובה שנוצרה כדי לוודא שהיא מדויקת.

Resolution API

ב-Maps Grounding Lite יש את Resolution API, שמאפשר לכם להמיר טקסט חופשי של מיקום וכתובות URL למזהי מקומות מובְנים במפות Google. ‫Resolution API זמין כשיטות REST וככלים בשרת Maps Grounding Lite MCP:

זיהוי שמות (REST,‏ MCP): זיהוי קבוצה של שמות או כתובות של מיקומים כישויות של מקומות ספציפיים במפות Google. התכונה הזו שימושית כדי לבסס שאילתות לא מובנות של משתמשים על מזהי מקומות יציבים.
Resolve Maps URLs (REST, MCP): פתרון של קבוצת כתובות URL של מפות Google לישויות ספציפיות של מקומות. הפורמטים הנתמכים כוללים כתובות URL רגילות של מקומות וכתובות URL מקוצרות.

אתם יכולים להשתמש במזהי המקומות שמוחזרים עם ממשקי API אחרים של Google Maps Platform. כל תשובה כוללת גם קישור ששומר את המקומות שנמצאו כרשימה במפות Google.

מידע נוסף זמין במאמר Maps Tools Resolution API.

אפליקציה לדוגמה: התנסות ב-Maps Grounding Lite (פתיחה בכרטיסייה חדשה)

חיוב ומכסות

איך מתבצע החיוב

במודל התמחור "תשלום לפי שימוש" של Google Maps Platform, השימוש ב-Grounding Lite מחושב לכל בקשה, וכל בקשה מייצגת אירוע חיוב אחד. השימוש נמדד לכל מק"ט של מוצר. בחשבונית מופיע פריט לכל מק"ט, בנוסף לחיובים הכוללים. מידע נוסף זמין בסקירה הכללית על דיווח.

פרטי התמחור מופיעים בטבלת התמחור הראשית ובטבלת התמחור בהודו.

בקשות ל-Resolution API (ResolveNames ו-ResolveMapsUrls) מחויבות ללא תשלום במסגרת המק"ט Places API חיפוש טקסט Essentials (IDs Only).

‫Maps Grounding Lite מוצע גם בחבילות Essentials ו-Pro. כדאי להירשם כדי לחסוך

מכסות

המכסות הבאות חלות על הכלים וממשקי ה-API שכלולים ב-Maps Grounding Lite:

חיפוש מקומות: 300 שאילתות לדקה, לכל פרויקט.
חיפוש מזג אוויר: 300 שאילתות לדקה, לכל פרויקט.
חישוב מסלולים: ‏300 שאילתות לדקה, לכל פרויקט.
‫Resolve names: ‏600 שאילתות לדקה, לכל פרויקט.
פתרון כתובות URL של מפות Google: ‏600 שאילתות לדקה, לכל פרויקט.

כל בקשת API ל-Resolution נספרת כשאילתה אחת, לא משנה כמה פריטים היא מכילה.

מדיניות ותנאים והגבלות

השימוש ב-Maps Grounding Lite כפוף לתנאים ולהגבלות של Google Maps Platform, כולל התנאים הספציפיים של השירות הזה. בקטע הזה מתוארות דרישות נוספות לשימוש בשירות Maps Grounding Lite, כולל דרישות לגבי מודלי LLM תואמים וייחוס מקור.

הדרישות לגבי מודלי LLM תואמים

מותר להשתמש ב-Maps Grounding Lite רק עם מודל LLM שעומד בתנאים ובהגבלות של Google Maps Platform.

לדוגמה, אתם אחראים לוודא שהתוכן של מפות Google לא נשמר במטמון, לא מאוחסן ולא משמש לשיפור ה-LLM שבו אתם בוחרים להשתמש. לפני שמשתמשים ב-Maps Grounding Lite, צריך לעיין בתנאים ובהגבלות של כל מודל שמתכוונים להשתמש בו עם Maps Grounding Lite. אסור להשתמש ב-Maps Grounding Lite עם מודלים שמשתמשים בנתונים שהוזנו למודל כדי לאמן או לשפר את המודל. באחריותך לוודא שהשימוש שלך במודל עומד באופן מלא בהגבלות על תוכן במפות Google, שמפורטות בתנאים ובהגבלות של Google Maps Platform, כולל התנאים הספציפיים לשירות.

דרישות הייחוס למקורות של מפות Google

כל תשובה של הכלי Maps Grounding Lite כוללת מקורות. כשמציגים תוצאות שמתבססות על כלים שסופקו על ידי Maps Grounding Lite, צריך לכלול את המקורות המשויכים של מפות Google באופן שעומד בדרישות הבאות:

המקורות ממפות Google חייבים להופיע מיד אחרי התוכן שנוצר שהמקורות תומכים בו. התוכן שנוצר נקרא גם פלט מבוסס-קרקע.
המקורות של מפות Google צריכים להיות גלויים באינטראקציה אחת של המשתמש.

מקורות לכלי "חיפוש מקומות"

השדה places של הכלי search_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. שרת Grounding Lite MCP משתמש בתעבורת HTTP שניתנת לסטרימינג.

מפעילים את השירות Maps Grounding Lite בפרויקט בענן ב-Google Cloud.

כדי להפעיל את ה-API בפרויקט:

במסוף Google Cloud, בוחרים את הפרויקט שרוצים להשתמש בו ל-Maps Grounding Lite.
מפעילים את החיוב בפרויקט במסוף Google Cloud.
מפעילים את Maps Grounding Lite בספריית ה-API במסוף Google Cloud.

אימות באמצעות מפתח API

אתם יכולים להשתמש במפתח API קיים עם Maps Grounding Lite או ליצור מפתח חדש, כל עוד אתם מפעילים את שירות ה-API של Maps Grounding Lite גם בפרויקט ב-Google Cloud וגם במפתח.

כדי לאמת באמצעות מפתח API:

כדי ליצור או להגדיר מפתח API, פועלים לפי השלבים שמפורטים במאמר תחילת השימוש ב-Google Maps Platform.
מעבירים את המפתח לשרת ה-MCP באמצעות הכותרת X-Goog-Api-Key. צריך לציין את זה ככותרת HTTP בהתאמה אישית בהגדרות של כלי ה-MCP ב-LLM.

אימות באמצעות OAuth

כדי לבצע אימות באמצעות OAuth, אתם יכולים ליצור פרטי כניסה ל-OAuth ולהעביר אותם לאפליקציית המארח או שרת ה-MCP.

כדי לבצע אימות באמצעות OAuth:

במסוף Google Cloud, בוחרים את הפרויקט שרוצים להשתמש בו ל-Maps Grounding Lite.
בתפריט API & Services, לוחצים על Credentials.
בתפריט העליון, לוחצים על Create credentials > OAuth client ID.
אם לפרויקט אין מסך הסכמה מוגדר, לוחצים על Configure consent screen ופועלים לפי ההוראות במסך.
בקטע Metrics, לוחצים על Create OAuth client.
במסך Create OAuth client ID, בוחרים את סוג האפליקציה ומזינים שם למזהה הלקוח.
מציינים את הפרטים הנוספים שרלוונטיים לסוג האפליקציה. לדוגמה, אם אתם יוצרים אפליקציית אינטרנט, הוסיפו מזהי URI מורשים לבקשות מהדפדפן ומהשרת.
אחרי שיוצרים את הלקוח, שומרים את מזהה הלקוח והסוד.
כשמגדירים את אפליקציית המארח או השרת של MCP כדי לגשת ל-Maps Grounding Lite, צריך להעביר את מזהה הלקוח וסוד הלקוח ב-OAuth. צריך גם לבקש את ההיקף הבא: https://www.googleapis.com/auth/maps-platform.mapstools.

למידע נוסף, קראו את המאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.

הגדרת מודלי LLM לגישה לשרת Maps Grounding Lite MCP

אחרי שיוצרים פרויקט ב-Google Cloud עם שירות Maps Grounding Lite API מופעל ופרטי כניסה תקינים, כמו מפתח API או מזהה לקוח וסוד של OAuth, אפשר להגדיר למודלי LLM גישה לשרת ה-MCP. כדי לעשות את זה, פועלים לפי מסמכי התיעוד הרלוונטיים להגדרת MCP ומשתמשים בכתובת ה-URL של שרת ה-MCP של Maps Grounding Lite: https://mapstools.googleapis.com/mcp

מידע נוסף זמין במאמר הגדרת MCP באפליקציית AI.

הגדרת Maps Grounding Lite באמצעות Gemini CLI

בקטע הזה מוסבר איך להגדיר את שרת Maps Grounding Lite MCP באמצעות 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

מתחילים לשאול שאלות שקשורות ל-Ask Maps באמצעות ה-CLI. לדוגמה, נסו את ההנחיה "תמליץ לי על מסעדות בתל אביב". היא אמורה להפעיל את הכלי search_places בשבילכם.

הגדרת Grounding Lite באמצעות ערכה לפיתוח סוכנים (ADK)

בקטע הזה מופיעות דוגמאות שמראות איך להגדיר את שרת Grounding Lite MCP באמצעות הערכה לפיתוח סוכנים (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.
- אפשר לנסות הנחיות כמו:
  - "אני אהיה בתל אביב מחר. מה מזג האוויר?"
  - "Find coffee shops near Golden Gate Park" (חפש בתי קפה ליד גולדן גייט פארק).
  - "Get directions from GooglePlex to SFO"

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, אתם יכולים להשתמש בטפסים הבאים: