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 के एमसीपी सर्वर को चालू करने पर, एलएलएम, सर्वर से दिखाए गए नए टूल को कॉल कर सकते हैं. इससे ऊपर बताए गए डेटा टाइप के लिए, ग्राउंडिंग की अतिरिक्त जानकारी मिलती है. एलएलएम, इस अतिरिक्त जानकारी का इस्तेमाल कॉन्टेक्स्ट के लिए कर सकता है. हालांकि, यह ज़रूरी नहीं है कि एलएलएम से जनरेट किए गए जवाब में, एमसीपी सर्वर से मिली सटीक जानकारी शामिल हो. आपको जनरेट किए गए जवाब की सटीकता की पुष्टि करनी चाहिए.

Resolution API (एक्सपेरिमेंट के तौर पर उपलब्ध)

Maps Grounding Lite, Resolution API उपलब्ध कराता है. इसकी मदद से, जगह की जानकारी वाले टेक्स्ट और यूआरएल को, Google Maps पर मौजूद जगहों के स्ट्रक्चर्ड आइडेंटिफ़ायर में बदला जा सकता है. Resolution API में दो एंडपॉइंट होते हैं:

  • नामों को रिज़ॉल्व करना: Google Maps पर मौजूद जगहों के नाम या पतों के बैच को, खास जगहों की जानकारी में बदलना. यह, स्ट्रक्चर्ड न की गई उपयोगकर्ता की क्वेरी को, जगह के स्टेबल आईडी में बदलने के लिए काम का है.
  • Maps के यूआरएल को रिज़ॉल्व करना: Google Maps के यूआरएल के बैच को, खास जगहों की जानकारी में बदलना. इसमें, जगह के स्टैंडर्ड यूआरएल और छोटे किए गए यूआरएल के फ़ॉर्मैट इस्तेमाल किए जा सकते हैं.

इन एंडपॉइंट का इस्तेमाल, स्ट्रक्चर्ड न की गई उपयोगकर्ता की क्वेरी या लिंक को, जगह के स्टेबल आईडी में बदलने के लिए किया जा सकता है. इससे, इन्हें Google Maps Platform के अन्य एपीआई के साथ इंटिग्रेट किया जा सकता है.

ज़्यादा जानकारी के लिए, Maps के टूल के Resolution API (एक्सपेरिमेंट के तौर पर उपलब्ध) के बारे में पढ़ें.

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

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

बिलिंग का तरीका

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

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

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

कोटा

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

  • जगहें खोजना: हर प्रोजेक्ट के लिए, हर मिनट में 300 क्वेरी.
  • मौसम की जानकारी देखना: हर प्रोजेक्ट के लिए, हर मिनट में 300 क्वेरी.
  • रास्ते ढूंढना: हर प्रोजेक्ट के लिए, हर मिनट में 300 क्वेरी.
  • नामों को रिज़ॉल्व करना (एक्सपेरिमेंट के तौर पर उपलब्ध): हर प्रोजेक्ट के लिए, हर मिनट में 600 क्वेरी.
  • Maps के यूआरएल को रिज़ॉल्व करना (एक्सपेरिमेंट के तौर पर उपलब्ध): हर प्रोजेक्ट के लिए, हर मिनट में 600 क्वेरी.

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

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 का इस्तेमाल करने के लिए, सबसे पहले आपको Maps Grounding Lite API सेवा चालू करने वाला Google Cloud प्रोजेक्ट चाहिए. इसके अलावा, आपको एपीआई पासकोड या OAuth क्लाइंट आईडी में से कोई एक चीज़ चाहिए. इसके बाद, एलएलएम को एमसीपी सर्वर को ऐक्सेस करने के लिए कॉन्फ़िगर किया जा सकता है. Grounding Lite का एमसीपी सर्वर, स्ट्रीम किए जा सकने वाले एचटीटीपी ट्रांसपोर्ट का इस्तेमाल करता है.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. Gemini CLI इंस्टॉल करने के बाद, add कमांड का इस्तेमाल करके, 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

    अगर कॉन्फ़िगरेशन पूरा हो गया है, तो आपको पुष्टि करने वाला मैसेज दिखेगा. इससे पता चलेगा कि सर्वर को आपकी उपयोगकर्ता सेटिंग में जोड़ दिया गया है.

  2. यह पुष्टि करने के लिए कि सर्वर सही तरीके से काम कर रहा है, /mcp list कमांड चलाएं:

    > /mcp list

Configured MCP servers:

maps-grounding-lite-mcp - Ready (3 tools)
Tools:
-   compute_routes
-   lookup_weather
-   search_places

  3. सीएलआई का इस्तेमाल करके, Maps से जुड़े सवाल पूछना शुरू करें. उदाहरण के लिए, "मुझे माउंटेन व्यू में कुछ रेस्टोरेंट के सुझाव दो" बोलकर देखें. इससे आपकी ओर से, search_places टूल को कॉल किया जाएगा.

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

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

Python

इस उदाहरण को लागू करने का पूरा तरीका, GitHub पर adk-samples डेटा स्टोर करने की जगह में देखा जा सकता है.

पहला चरण: 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 मौजूद हो

पक्का करें कि वाली डायरेक्ट्री में, __init__.py मौजूद हो:agent.py

from . import agent
तीसरा चरण: adk web चलाएं और इंटरैक्ट करें
  1. एनवायरमेंट वैरिएबल सेट करें:
    अपने टर्मिनल में, Google Maps के एपीआई पासकोड को एनवायरमेंट वैरिएबल के तौर पर सेट करें: 
    export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
  2. adk web चलाएं:
    ADK के वेब इंटरफ़ेस को शुरू करने के लिए, यह कमांड चलाएं: 
    adk web
  3. यूज़र इंटरफ़ेस (यूआई) में इंटरैक्ट करें:
    • 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 के बारे में सुझाव/राय देने या शिकायत करने के लिए, इन फ़ॉर्म का इस्तेमाल करें: