Maps Grounding Lite

Google Maps Platform Grounding Lite, मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) के साथ काम करने वाली एक सेवा है. इससे, Google Maps के भरोसेमंद जियोस्पेशल डेटा की मदद से, अपने एआई ऐप्लिकेशन को आसानी से ग्राउंड किया जा सकता है. एमसीपी सर्वर ऐसे टूल उपलब्ध कराता है जिनकी मदद से एलएलएम, जगहों, मौसम, और रास्तों की जानकारी ऐक्सेस कर सकते हैं. एमसीपी सर्वर के साथ काम करने वाले किसी भी टूल में Maps Grounding Lite को चालू करके, इसे आज़माया जा सकता है.

टूल

Maps Grounding Lite में ऐसे टूल उपलब्ध होते हैं जिनकी मदद से एलएलएम, Google Maps की इन सुविधाओं को ऐक्सेस कर सकते हैं:

जगहों के बारे में खोजना: जगहों के बारे में जानकारी का अनुरोध करें और एआई से जनरेट की गई जगहों की जानकारी की खास बातें पाएं. साथ ही, खास बातों में शामिल हर जगह के लिए, जगह के आईडी, अक्षांश और देशांतर के निर्देशांक, और Google Maps के लिंक पाएं. जगहों को मैप पर दिखाने के लिए, Google Maps Platform के अन्य एपीआई के साथ, लौटाए गए जगह के आईडी और अक्षांश और देशांतर के निर्देशांकों का इस्तेमाल किया जा सकता है.
मौसम की जानकारी पाना: मौसम की जानकारी पाने का अनुरोध करें. साथ ही, मौजूदा मौसम की स्थिति, हर घंटे के हिसाब से मौसम का पूर्वानुमान, और रोज़ के हिसाब से मौसम का पूर्वानुमान पाएं.
रास्ते की जानकारी पाना: दो जगहों के बीच कार या पैदल जाने के रास्तों के बारे में जानकारी पाने का अनुरोध करना और रास्ते की दूरी और अवधि की जानकारी पाना.

ध्यान दें: Maps Grounding Lite में, रास्ते की पूरी जानकारी, दिशा-निर्देश, रीयल-टाइम ट्रैफ़िक या नेविगेशन की जानकारी नहीं मिलती.

Maps Grounding Lite MCP सर्वर को चालू करने पर, एलएलएम, सर्वर से उपलब्ध कराए गए नए टूल को कॉल कर सकते हैं. इससे, ऊपर दिए गए डेटा टाइप के लिए, ज़्यादा जानकारी मिल सकती है. एलएलएम, इस अतिरिक्त जानकारी का इस्तेमाल कॉन्टेक्स्ट के लिए कर सकता है. हालांकि, एलएलएम से मिले जवाब में, एमसीपी सर्वर से मिली सटीक जानकारी शामिल नहीं हो सकती. आपको जनरेट किए गए जवाब की पुष्टि करनी चाहिए.

Maps Grounding Lite का सैंपल ऐप्लिकेशन आज़माएं (नए टैब में खोलें)

बिलिंग और कोटा

आपको बिल कैसे भेजा जाता है

Google Maps Platform के 'इस्तेमाल के हिसाब से पेमेंट करें' वाले मॉडल में, Maps Grounding Lite के इस्तेमाल का हिसाब हर अनुरोध के लिए लगाया जाता है. हर अनुरोध, एक बिलिंग इवेंट को दिखाता है. हर प्रॉडक्ट SKU के लिए, इस्तेमाल को ट्रैक किया जाता है. आपके बिल में, कुल शुल्क के अलावा हर एसकेयू के लिए एक लाइन आइटम दिखता है. ज़्यादा जानकारी के लिए, रिपोर्टिंग की खास जानकारी देखें.

कीमत की जानकारी के लिए, कीमत की मुख्य टेबल और भारत के लिए कीमत की टेबल देखें.

Maps Grounding Lite की सुविधा, Essentials और Pro सदस्यता लेकर पैसे बचाएं पैकेज के ज़रिए भी उपलब्ध कराई जाती है.

कोटा

Maps Grounding Lite की ओर से उपलब्ध कराए गए टूल पर ये कोटा लागू होते हैं:

जगहें खोजना: हर प्रोजेक्ट के लिए, हर मिनट में 300 क्वेरी.
मौसम की जानकारी पाना: हर प्रोजेक्ट के लिए, हर मिनट में 300 क्वेरी.
रास्ते का हिसाब लगाएं: हर प्रोजेक्ट के लिए, हर मिनट में 300 क्वेरी.

नीतियां और सेवा की शर्तें

Maps Grounding Lite पर, Google Maps Platform की सेवा की शर्तें लागू होती हैं. इनमें इस सेवा के लिए सेवा से जुड़ी खास शर्तें भी शामिल हैं. इस सेक्शन में, Maps Grounding Lite के इस्तेमाल से जुड़ी अन्य ज़रूरी शर्तों के बारे में बताया गया है. इनमें, काम करने वाले एलएलएम और सोर्स एट्रिब्यूशन से जुड़ी ज़रूरी शर्तें शामिल हैं.

साथ काम करने वाले एलएलएम के लिए ज़रूरी शर्तें

Maps Grounding Lite का इस्तेमाल सिर्फ़ ऐसे एलएलएम के साथ किया जा सकता है जो Google Maps Platform की सेवा की शर्तों का पालन करता हो.

उदाहरण के लिए, यह पक्का करना आपकी ज़िम्मेदारी है कि Google Maps के कॉन्टेंट को, आपके चुने गए एलएलएम के ज़रिए कैश न किया जाए, सेव न किया जाए या उसका इस्तेमाल एलएलएम को बेहतर बनाने के लिए न किया जाए. Maps Grounding Lite का इस्तेमाल करने से पहले, आपको सेवा की शर्तें पढ़नी होंगी. ये शर्तें, उस मॉडल के लिए होंगी जिसका इस्तेमाल आपको Maps Grounding Lite के साथ करना है. Maps Grounding Lite का इस्तेमाल ऐसे मॉडल के साथ नहीं किया जाना चाहिए जो मॉडल को ट्रेनिंग देने या उसे बेहतर बनाने के लिए, मॉडल में डाले गए डेटा का इस्तेमाल करते हैं. यह पक्का करना आपकी ज़िम्मेदारी है कि मॉडल का इस्तेमाल करते समय, Google Maps Platform की सेवा की शर्तों में बताई गई Google Maps के कॉन्टेंट से जुड़ी पाबंदियों का पूरी तरह से पालन किया गया हो. इसमें सेवा से जुड़ी खास शर्तें भी शामिल हैं.

Google Maps के सोर्स के लिए एट्रिब्यूशन से जुड़ी ज़रूरी शर्तें

Maps Grounding Lite से मिलने वाले हर जवाब में सोर्स शामिल होते हैं. Maps Grounding Lite की ओर से उपलब्ध कराए गए टूल का इस्तेमाल करके नतीजे दिखाते समय, आपको Google Maps के उन सोर्स को शामिल करना होगा जो इन टूल से जुड़े हैं. ऐसा इस तरह से करना होगा कि ये शर्तें पूरी हों:

Google Maps के सोर्स, जनरेट किए गए कॉन्टेंट के ठीक बाद होने चाहिए. साथ ही, सोर्स में मौजूद कॉन्टेंट, जनरेट किए गए कॉन्टेंट से मिलता-जुलता होना चाहिए. जनरेट किए गए इस कॉन्टेंट को भरोसेमंद सोर्स से मिला जवाब भी कहा जाता है.
Google Maps के सोर्स, उपयोगकर्ता के एक इंटरैक्शन में दिखने चाहिए.

'जगहें खोजें' टूल के लिए सोर्स

search_places टूल के places फ़ील्ड में, ऐसे सोर्स दिए जाते हैं जिनसे summary की पुष्टि होती है. places के लिए, यह मेटाडेटा दिखता है:

place (संसाधन का नाम)
id
location
googleMapsLinks

हर जगह के लिए, आपको लिंक की झलक जनरेट करनी होगी. इसके लिए, इन ज़रूरी शर्तों को पूरा करना होगा:

Maps Grounding Lite में टेक्स्ट एट्रिब्यूशन के दिशा-निर्देशों का पालन करते हुए, हर सोर्स को Google Maps से एट्रिब्यूट करें.
जवाब में मौजूद places.googleMapsLinks.placeUrl का इस्तेमाल करके, सोर्स से लिंक करें.

एमसीपी सर्वर का इस्तेमाल करने के लिए, एलएलएम कॉन्फ़िगर करना

Maps Grounding Lite का इस्तेमाल करने के लिए, आपके पास ऐसा Google Cloud प्रोजेक्ट होना चाहिए जिसमें Maps Grounding Lite API सेवा चालू हो. साथ ही, आपके पास एपीआई कुंजी या OAuth क्लाइंट आईडी होना चाहिए. इसके बाद, एमसीपी सर्वर को ऐक्सेस करने के लिए, एलएलएम को कॉन्फ़िगर किया जा सकता है. Grounding Lite MCP सर्वर, स्ट्रीम किए जा सकने वाले एचटीटीपी ट्रांसपोर्ट का इस्तेमाल करता है.

अपने Google Cloud प्रोजेक्ट पर Maps Grounding Lite सेवा चालू करें

अपने प्रोजेक्ट में एपीआई चालू करने के लिए:

Google Cloud Console में जाकर, वह प्रोजेक्ट चुनें जिसका इस्तेमाल Maps Grounding Lite के लिए करना है.
Google Cloud Console में जाकर, प्रोजेक्ट के लिए बिलिंग की सुविधा चालू करें.
Google Cloud Console API लाइब्रेरी में जाकर, Maps Grounding Lite को चालू करें.

एपीआई पासकोड का इस्तेमाल करके पुष्टि करना

Maps Grounding Lite के साथ किसी मौजूदा एपीआई पासकोड का इस्तेमाल किया जा सकता है. इसके अलावा, नया पासकोड भी बनाया जा सकता है. हालांकि, इसके लिए आपको Google Cloud प्रोजेक्ट और पासकोड, दोनों पर Maps Grounding Lite API सेवा चालू करनी होगी.

एपीआई कुंजी का इस्तेमाल करके पुष्टि करने के लिए:

Google Maps Platform का इस्तेमाल शुरू करना में दिए गए चरणों को पूरा करके, एपीआई पासकोड बनाएं या उसे कॉन्फ़िगर करें.
X-Goog-Api-Key हेडर का इस्तेमाल करके, कुंजी को एमसीपी सर्वर पर पास करें. आपको इसे एलएलएम के एमसीपी टूल कॉन्फ़िगरेशन में, कस्टम एचटीटीपी हेडर के तौर पर सेट करना होगा.

OAuth का इस्तेमाल करके पुष्टि करना

OAuth क्रेडेंशियल बनाकर और उन्हें एमसीपी होस्ट या एमसीपी सर्वर ऐप्लिकेशन को पास करके, OAuth का इस्तेमाल करके पुष्टि की जा सकती है.

OAuth का इस्तेमाल करके पुष्टि करने के लिए:

Google Cloud Console में जाकर, वह प्रोजेक्ट चुनें जिसका इस्तेमाल Maps Grounding Lite के लिए करना है.
एपीआई और सेवाएं मेन्यू में जाकर, क्रेडेंशियल को चुनें.
सबसे ऊपर मौजूद मेन्यू में, क्रेडेंशियल बनाएं > OAuth क्लाइंट आईडी को चुनें.
अगर प्रोजेक्ट में कॉन्फ़िगर की गई सहमति स्क्रीन नहीं है, तो सहमति स्क्रीन कॉन्फ़िगर करें पर क्लिक करें. इसके बाद, स्क्रीन पर दिए गए निर्देशों का पालन करें.
मेट्रिक सेक्शन में, OAuth क्लाइंट बनाएं पर क्लिक करें.
OAuth क्लाइंट आईडी बनाएं स्क्रीन पर, ऐप्लिकेशन का टाइप चुनें और क्लाइंट आईडी के लिए कोई नाम डालें.
अपने आवेदन के टाइप के हिसाब से, ज़्यादा जानकारी दें. उदाहरण के लिए, अगर कोई वेब ऐप्लिकेशन बनाया जा रहा है, तो ब्राउज़र और सर्वर के अनुरोधों के लिए, अनुमति वाले यूआरआई जोड़ें.
क्लाइंट बन जाने के बाद, क्लाइंट आईडी और सीक्रेट सेव करें.
Maps Grounding Lite को ऐक्सेस करने के लिए, अपने एमसीपी होस्ट या एमसीपी सर्वर ऐप्लिकेशन को कॉन्फ़िगर करते समय, अपना OAuth क्लाइंट आईडी और सीक्रेट पास करें. आपको इस स्कोप का अनुरोध भी करना होगा: https://www.googleapis.com/auth/maps-platform.mapstools.

ज़्यादा जानकारी के लिए, OAuth 2.0 का इस्तेमाल करके Google API ऐक्सेस करना लेख पढ़ें.

Maps Grounding Lite एमसीपी सर्वर को ऐक्सेस करने के लिए, एलएलएम कॉन्फ़िगर करना

अगर आपके पास Maps Grounding Lite API सेवा चालू किया गया Google Cloud प्रोजेक्ट और मान्य क्रेडेंशियल हैं, जैसे कि एपीआई पासकोड या OAuth क्लाइंट आईडी और सीक्रेट, तो एलएलएम को MCP सर्वर ऐक्सेस करने के लिए कॉन्फ़िगर किया जा सकता है. इसके लिए, MCP कॉन्फ़िगरेशन से जुड़े दस्तावेज़ में दिए गए निर्देशों का पालन करें. साथ ही, Maps Grounding Lite MCP सर्वर का यह यूआरएल इस्तेमाल करें: https://mapstools.googleapis.com/mcp

ज़्यादा जानकारी के लिए, एआई ऐप्लिकेशन में एमसीपी कॉन्फ़िगर करना लेख पढ़ें.

Gemini CLI की मदद से, Maps Grounding Lite को कॉन्फ़िगर करना

इस सेक्शन में, Gemini CLI का इस्तेमाल करके, Maps Grounding Lite एमसीपी सर्वर को कॉन्फ़िगर करने का उदाहरण दिया गया है. ज़्यादा जानकारी के लिए, Gemini CLI के साथ एमसीपी सर्वर देखें.

Gemini CLI इंस्टॉल करने के बाद, Maps Grounding Lite MCP सर्वर को कॉन्फ़िगर करने के लिए, add कमांड का इस्तेमाल किया जा सकता है:
```
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 (3 tools)
Tools:
-   compute_routes
-   lookup_weather
-   search_places
```
CLI की मदद से, Maps से जुड़े सवाल पूछना शुरू करें. उदाहरण के लिए, "मुझे माउंटेन व्यू के कुछ रेस्टोरेंट सुझाओ" आज़माएं. इससे आपकी ओर से search_places टूल को कॉल किया जाएगा.

Agent Development Kit (ADK) की मदद से, Grounding Lite को कॉन्फ़िगर करना

इस सेक्शन में ऐसे उदाहरण दिए गए हैं जिनसे पता चलता है कि Agent Development Kit (ADK) और Python, Java या TypeScript में से किसी एक का इस्तेमाल करके, Grounding Lite MCP सर्वर को कैसे कॉन्फ़िगर किया जाता है.

Python

पहला चरण: Google Maps Grounding Lite के लिए, `McpToolset` की मदद से अपने एजेंट को तय करना

अपनी 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` मौजूद हो

पक्का करें कि आपके पास agent.py के साथ-साथ उसी डायरेक्ट्री में __init__.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 तक जाने का रास्ता बताओ."

Java

ऐसा एजेंट तय करें जो Java में McpToolset को शुरू करता हो. अगर एनवायरमेंट वैरिएबल का इस्तेमाल नहीं किया जाता है, तो YOUR_GOOGLE_MAPS_API_KEY_HERE को उस एपीआई कुंजी से बदलें जो आपको मिली है.

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

TypeScript में MCPToolset को शुरू करने वाले एजेंट को इस तरह से तय करें:

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 के बारे में सुझाव/राय देने या शिकायत करने के लिए, इन फ़ॉर्म का इस्तेमाल करें: