Maps Tools Resolution API

Maps Tools Resolution API হল Maps Experience agent tools (আগে Maps Grounding Lite নামে পরিচিত ছিল)-এর অংশ। এটি ব্যাচ এন্ডপয়েন্ট প্রদান করে যা লোকেশনের নাম এবং Google Maps URL-কে Google Maps-এর স্থান আইডিতে সমাধান করে। আপনি অন্যান্য Google Maps Platform API-এর সাথে ফেরত পাওয়া জায়গার আইডি ব্যবহার করতে পারবেন। প্রতিটি উত্তরে একটি লিঙ্কও অন্তর্ভুক্ত থাকে যা সমাধান করা জায়গাগুলিকে Google Maps-এ একটি তালিকা হিসেবে সেভ করে।

Resolution API, REST পদ্ধতি এবং Maps Experience agent tools MCP সার্ভারে টুল হিসেবে উপলভ্য:

ক্ষমতা REST পদ্ধতি MCP টুল
লোকেশন নাম বা ঠিকানা থেকে জায়গা খুঁজে বের করুন resolveNames resolve_names
Google Maps URL-কে জায়গায় রিজলভ করুন resolveMapsUrls resolve_maps_urls

শুরু করার আগে

Resolution API ব্যবহার করতে, আপনার একটি Google Cloud প্রোজেক্ট থাকতে হবে যেখানে বিলিং চালু আছে এবং Maps Experience agent tools API পরিষেবা চালু আছে। নির্দেশাবলীর জন্য, আপনার Google Cloud প্রোজেক্টে Maps Experience agent tools চালু করুন দেখুন।

API অ্যাক্সেস ও যাচাইকরণ

Resolution API, API কী এবং OAuth 2.0 ক্রেডেনশিয়াল, দুটির সাথেই কাজ করে।

API key

আপনি X-Goog-Api-Key হেডারে সঠিক Google Maps Platform API কী পাস করে অথবা অনুরোধের URL-এ এটি যোগ করে অনুরোধ যাচাই করতে পারবেন:

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

এই পৃষ্ঠার উদাহরণে, API_KEY-এর জায়গায় আপনার API key লিখুন।

OAuth 2.0 স্কোপ

আপনি OAuth অনুমোদন ব্যবহার করলে, নিম্নলিখিত স্কোপ কাজ করে:

  • https://www.googleapis.com/auth/maps-platform.mapstools

ব্যবহারের সীমা

Resolution API-এর ক্ষেত্রে নিম্নলিখিত ডিফল্ট কোটা প্রযোজ্য:

  • ResolveNames: প্রতিটি প্রোজেক্টের জন্য প্রতি মিনিটে ৬০০টি কোয়েরি।
  • ResolveMapsUrls: প্রতিটি প্রোজেক্টের জন্য প্রতি মিনিটে ৬০০টি কোয়েরি।
  • ব্যাচের সাইজ: প্রতিটি অনুরোধে সর্বাধিক ২০টি কোয়েরি বা URL।

প্রতিটি অনুরোধে কতগুলি আইটেম আছে তা নির্বিশেষে একটি কোয়েরি হিসেবে গণনা করা হয়।

দাম

ResolveNames এবং ResolveMapsUrls-এর জন্য করা অনুরোধের ক্ষেত্রে কোনও চার্জ ($0) নেওয়া হয় না। Places API Text Search Essentials (IDs Only) SKU-এর অধীনে এই সুবিধা পাওয়া যায়। Maps Experience এজেন্ট টুলের বাকি অংশের মতো, আপনার প্রোজেক্টে একটি বিলিং অ্যাকাউন্ট থাকতে হবে।

অনুরোধ যাচাইকরণ ও সীমাবদ্ধতা

অতিরিক্ত লোড প্রতিরোধ করতে এবং দ্রুত প্রতিক্রিয়া নিশ্চিত করতে, ব্যাচ অনুরোধগুলি নিম্নলিখিত নিয়মগুলির সাথে যাচাই করা হয়:

  • ব্যাচ সাইজের সীমা: দুটি পদ্ধতিতেই প্রতিটি অনুরোধে সর্বাধিক ২০টি আইটেম অনুমোদিত।
  • ResolveNames সংক্রান্ত প্রয়োজনীয়তা:
    • queries-এর প্রতিটি আইটেমে অবশ্যই একটি খালি নয় এমন text প্যারামিটার উল্লেখ করতে হবে।
    • কোয়েরিতে অবশ্যই কোনও নির্দিষ্ট জায়গার নাম বা ঠিকানা থাকতে হবে, যেমন "Googleplex, Mountain View, CA" বা "Eiffel Tower, Paris"।
    • "restaurants in New York"-এর মতো সাধারণ বিভাগীয় সার্চ অথবা "Starbucks"-এর মতো লোকেশন ছাড়া সাধারণ চেনের নাম কাজ করে না এবং সমাধান নাও হতে পারে।
  • ResolveMapsUrls সংক্রান্ত প্রয়োজনীয়তা:
    • প্রতিটি URL-এর স্ট্রাকচার Google Maps URL-এর মতো হতে হবে।
    • যেসব ফর্ম্যাট কাজ করে:
      • স্ট্যান্ডার্ড জায়গার URL: https://www.google.com/maps/place/...
      • সংক্ষিপ্ত URL: https://maps.app.goo.gl/...
    • সাধারণ কোয়েরি-ভিত্তিক Maps URL, যেমন https://maps.google.com/?q=restaurant এবং কোনও নির্দিষ্ট অনন্য জায়গার দিকে নির্দেশ করে না এমন URL কাজ করে না।

Google Maps-এ সমাধান করা জায়গা সেভ করুন

ব্যাচের অন্তত একটি আইটেম সমাধান হয়ে গেলে, উত্তরে একটি saveToMapsUrl ফিল্ড অন্তর্ভুক্ত থাকে। এটি হল একটি Google Maps লিঙ্ক যাতে ব্যাচের মধ্যে সফলভাবে সমাধান করা সব জায়গা রয়েছে। এই লিঙ্কটি সেইসব ব্যবহারকারীদের দেখান যারা Google Maps-এ তালিকা হিসেবে সমাধান করা জায়গাগুলি সেভ, শেয়ার বা খুলতে চান।

API-এর মাধ্যমে পাওয়া লিঙ্ক সবসময় ব্যবহার করুন। নিজে থেকে লিঙ্ক তৈরি করবেন না। ব্যাচের কোনও আইটেম সমাধান না হলে, উত্তরে saveToMapsUrl অন্তর্ভুক্ত থাকে না।

আংশিক ত্রুটি ম্যানেজ করা

দুটি পদ্ধতিই ব্যাচ প্রসেসর। কোনও ব্যাচের কিছু আইটেম সমাধান করতে না পারলে, সামগ্রিক অনুরোধ টপ-লেভেল সমস্যার কারণে ব্যর্থ হয় না। পরিবর্তে, API আংশিক সাফল্যের উত্তর দেয় এবং আপনাকে প্রতিটি আইটেমের ব্যর্থতার জন্য উত্তর চেক করতে হবে।

উত্তর ব্যাখ্যা করুন

  1. গ্যারেন্টিযুক্ত ১:১ অ্যালাইনমেন্ট: ফেরত আসা results তালিকা ( ResolveNames-এর জন্য) বা entities তালিকা (ResolveMapsUrls-এর জন্য) ইনপুট তালিকার সাথে ১:১ ম্যাপ করে, ইনডেক্স অনুযায়ী।
  2. ব্যর্থতার জন্য খালি এলিমেন্ট: i ইন্ডেক্সে থাকা আইটেম সমাধান করতে ব্যর্থ হলে, ফলাফলের তালিকায় i ইন্ডেক্সে একটি খালি অবজেক্ট {} থাকে।
  3. failedRequests ম্যাপ: উত্তরে একটি failedRequests ম্যাপ আছে।
    • কী হল ব্যর্থ আইটেমের ০-ভিত্তিক ইন্ডেক্স (JSON-এ স্ট্রিং হিসেবে দেখানো হয়)।
    • এই ভ্যালু হল একটি google.rpc.Status অবজেক্ট যাতে ত্রুটি কোড এবং আইটেমটি কেন ব্যর্থ হয়েছে তা ব্যাখ্যা করে একটি মেসেজ থাকে।
  4. saveToMapsUrl-এ শুধু সফলভাবে সমাধান করা আইটেমগুলিই অন্তর্ভুক্ত থাকে: saveToMapsUrl লিঙ্কে শুধু সমাধান করা আইটেমগুলিই অন্তর্ভুক্ত থাকে। ব্যর্থ হওয়া আইটেম অন্তর্ভুক্ত করা হয়নি।

একটি আইটেম ব্যর্থ হয়েছে বলে পুরো ব্যাচটি ব্যর্থ হয়েছে বলে ধরে নেবেন না। কোন আইটেম, যদি থাকে, সমাধান করা যায়নি তা খুঁজে বের করতে সর্বদা failedRequests চেক করুন।

আইটেম প্রতি সমস্যা

নিম্নলিখিত সারণীতে আইটেম-প্রতি সমস্যার তালিকা দেওয়া হল যা আপনি failedRequests-এ দেখতে পেতে পারেন:

পদ্ধতি কারণ কোড মেসেজ
ResolveNames নাম বা ঠিকানা দিয়ে কোনও জায়গা খুঁজে পাওয়া যায়নি। 5 (NOT_FOUND) Place not found.
ResolveMapsUrls URL-টি কোনও জায়গার সাথে লিঙ্ক করা যাচ্ছে না। 3 (INVALID_ARGUMENT) Failed to resolve Maps URL to a place.
দুটি পদ্ধতিই আইটেম সংক্রান্ত সমস্যার সমাধান করার সময় কোনও ইন্টার্নাল সমস্যা হয়েছে। 13 (INTERNAL) Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support

শুধুমাত্র সেইসব আইটেম আবার চেষ্টা করুন যেগুলি INTERNAL-এর সাথে ব্যর্থ হয়েছে।

টপ-লেভেল ব্যর্থতা

নিম্নলিখিত ক্ষেত্রে API আংশিক উত্তরের পরিবর্তে টপ-লেভেল সমস্যা দেখায়:

  • অনুরোধ ভুল (400 INVALID_ARGUMENT): অনুরোধে ২০টির বেশি আইটেম আছে, ResolveNames অনুরোধে কোনও কোয়েরি নেই বা খালি text ভ্যালু সহ কোয়েরি আছে অথবা ResolveMapsUrls অনুরোধে এমন URL আছে যা খালি বা সিনট্যাক্স অনুযায়ী সঠিক URL নয়। একটি ভুল আইটেমের কারণে পুরো অনুরোধটি বাতিল হয়ে যায়।
  • যাচাইকরণ, অনুমতি বা কোটা সংক্রান্ত সমস্যা: যেমন, API কী নেই বা ভুল অথবা অনুরোধ ব্যবহারের সীমা ছাড়িয়ে গেছে।
  • সার্ভারের সমস্যা (500 INTERNAL): অনুরোধ আবার করুন।

MCP-এর সাথে রেজোলিউশন API ব্যবহার করা

https://mapstools.googleapis.com/mcp-এ Maps Experience agent tools MCP সার্ভার দুটি টুল হিসেবে রেজোলিউশন API প্রকাশ করে:

  • resolve_names: প্লেস আইডিতে লোকেশনের নাম বা ঠিকানার ব্যাচ সমাধান করে।
  • resolve_maps_urls: Google Maps URL-এর একটি ব্যাচকে প্লেস আইডিতে সমাধান করে।

আপনি MCP সার্ভার ব্যবহার করার জন্য LLM কনফিগার করলে, এইসব টুল অন্যান্য Maps Experience এজেন্ট টুলের পাশাপাশি উপলভ্য হয়। এই টুলগুলি REST পদ্ধতির মতোই একই ইনপুট গ্রহণ করে, একই সীমাবদ্ধতা প্রয়োগ করে এবং একই আংশিক-ব্যর্থতার প্রতিক্রিয়া প্রদান করে।

টুলের উত্তরে save_to_maps_url ফিল্ড অন্তর্ভুক্ত আছে। টুলের বিবরণ LLM-কে নির্দেশ দেয় যে ব্যবহারকারী যখন Google Maps-এ সমাধান করা জায়গাগুলি তালিকা হিসেবে সেভ, শেয়ার বা খুলতে চান, তখন যেন এই লিঙ্কটি দেখানো হয়, নিজেই লিঙ্ক তৈরি করার পরিবর্তে।

নিম্নলিখিত উদাহরণে সরাসরি resolve_names টুল কল করার জন্য curl ব্যবহার করা হয়েছে:

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

resolve_maps_urls কল করতে, name-কে resolve_maps_urls-এ সেট করুন এবং arguments-এ urls অ্যারে পাস করুন।

REST API স্পেসিফিকেশন ও curl-এর উদাহরণ

ResolveNames

পদ্ধতি: POST

https://mapstools.googleapis.com/v1:resolveNames

অনুরোধের প্রধান অংশের ফর্ম্যাট

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}
  • queries (প্রয়োজনীয়): সমাধান করার জন্য কোয়েরির পুনরাবৃত্ত তালিকা (সর্বাধিক ২০টি)।
  • locationBias (ঐচ্ছিক): স্থানীয় অঞ্চলের দিকে ফলাফল বায়াস করার জন্য ভিউপোর্ট বাউন্ডিং বক্স।
  • regionCode (ঐচ্ছিক): CLDR দেশের কোড (যেমন, "US" বা "FR") যাতে ফলাফল পক্ষপাতদুষ্ট হয়।

Curl-এর উদাহরণ: সফলভাবে সমাধান করা হয়েছে

এই কোয়েরি "Googleplex" এবং "আইফেল টাওয়ার" সমাধান করে।

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"
JSON রেসপন্স
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

Curl-এর উদাহরণ: মিশ্র ফলাফল (আংশিক ব্যর্থতা)

এই উদাহরণে, প্রথম আইটেমটি হল টেক্সট যা সমাধান করা যায় না এবং দ্বিতীয় আইটেমটি একটি সঠিক জায়গা।

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "This is not a real place name at all 123456789" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"
JSON রেসপন্স
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

পদ্ধতি: POST

https://mapstools.googleapis.com/v1:resolveMapsUrls

অনুরোধের প্রধান অংশের ফর্ম্যাট

{
  "urls": [
    "string"
  ]
}
  • urls (প্রয়োজনীয়): সমাধান করার জন্য Google Maps URL স্ট্রিংয়ের পুনরাবৃত্ত তালিকা (সর্বাধিক ২০টি)।

Curl-এর উদাহরণ: সফলভাবে সমাধান করা হয়েছে

নিম্নলিখিত উদাহরণটি একটি স্ট্যান্ডার্ড Google Maps জায়গার URL সমাধান করে:

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
JSON রেসপন্স
{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Curl-এর উদাহরণ: মিশ্র ফলাফল (আংশিক ব্যর্থতা)

নিম্নলিখিত উদাহরণটি একটি সঠিক জায়গার URL এবং একটি URL যা কোনও জায়গায় সমাধান করা যায় না, সেটি সমাধান করে:

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "urls": [
    "https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
JSON রেসপন্স
{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Curl-এর উদাহরণ: যাচাইকরণে ব্যর্থতা

নিম্নলিখিত উদাহরণে একটি অনুরোধে ২০টির বেশি URL পাস করা হয়েছে:

python3 -c 'import json; print(json.dumps({"urls": ["https://www.google.com/maps/place/Googleplex"] * 21}))' | \
curl -X POST \
-H "Content-Type: application/json" \
-d @- \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
JSON রেসপন্স
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}

মতামত জানান

Resolution API সম্পর্কে কোনও সমস্যার বিষয়ে অভিযোগ জানাতে বা মতামত শেয়ার করতে, Maps Experience agent tools পাবলিক ইস্যু ট্র্যাকার কম্পোনেন্ট ব্যবহার করুন: