‫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:

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

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

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

Resolution API

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

‫Resolve names (REST, MCP): Resolve a batch of location names or addresses to specific place entities on Google Maps. האפשרות הזו שימושית כדי להצמיד שאילתות משתמש לא מובנות למזהי מקומות יציבים.
‫Resolve Maps URLs (REST, MCP): פתרון של קבוצה של כתובות URL במפות Google לישויות מקום ספציפיות. הפורמטים הנתמכים כוללים כתובות URL רגילות של מקומות וכתובות URL מקוצרות.

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

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

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

חיוב ומכסות

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

במודל התמחור של Google Maps Platform בתשלום לפי שימוש, השימוש ב-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 שאילתות לדקה, לכל פרויקט.

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

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

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

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

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

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

דרישות השיוך למקורות במפות 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 מהתגובה.

הגדרת מודלים גדולים של שפה (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.
מפעילים את Maps Grounding Lite ב-API Library במסוף Google Cloud.

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

אתם יכולים להשתמש במפתח API קיים עם Maps Grounding Lite או ליצור מפתח חדש, בתנאי שתפעילו את שירות Maps Grounding Lite API בפרויקט 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 (יצירת פרטי כניסה > מזהה לקוח OAuth).
אם בפרויקט לא מוגדר מסך הסכמה, לוחצים על Configure consent screen ופועלים לפי ההוראות במסך.
בקטע מדדים, לוחצים על יצירת לקוח OAuth.
במסך Create OAuth client ID, בוחרים סוג אפליקציה ומזינים שם למזהה הלקוח.
מציינים את הפרטים הנוספים שרלוונטיים לסוג הבקשה. לדוגמה, אם אתם יוצרים אפליקציית אינטרנט, מוסיפים URI מורשים לבקשות של דפדפן ושרת.
אחרי שיוצרים את הלקוח, שומרים את מספר הלקוח ואת הסוד.
כשמגדירים את האפליקציה של שרת ה-MCP או המארח של ה-MCP כדי לגשת אל Maps Grounding Lite, צריך להעביר את מזהה הלקוח ואת הסוד של OAuth. צריך גם לבקש את ההיקף הבא: https://www.googleapis.com/auth/maps-platform.mapstools.

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

הגדרת מודלים של שפה גדולה (LLM) כדי לגשת לשרת MCP של Grounding Lite במפות

אחרי שיש לכם פרויקט בענן ב-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

בקטע הזה מובא לדוגמה איך להגדיר את שרת ה-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 באמצעות ערכה לפיתוח סוכנים (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.
- אפשר לנסות פרומפטים כמו:
  - "I will be in San Francisco tomorrow. מה מזג האוויר?"
  - ‫"Find coffee shops near Golden Gate Park" (חיפוש בתי קפה ליד פארק שער הזהב).
  - ‫"Get directions from GooglePlex to SFO" (קבלת מסלול מ-GooglePlex אל 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"
            }
        })
    ],
});

שיתוף משוב

כדי לשתף משוב על Grounding Lite במפות Google, אפשר להשתמש בטפסים הבאים: