Maps Tools Resolution API

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

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

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

শুরু করার আগে

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

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-এর জন্য করা অনুরোধের ক্ষেত্রে Places API Text Search Essentials (IDs Only) SKU-এর অধীনে কোনও চার্জ ($0) নেওয়া হয় না। Maps Grounding Lite-এর বাকি অংশের মতো, আপনার প্রোজেক্টে একটি বিলিং অ্যাকাউন্ট থাকতে হবে।

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

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

• ব্যাচ সাইজের সীমা: দুটি পদ্ধতিতেই প্রতিটি অনুরোধে সর্বাধিক ২০টি আইটেম অনুমতি দেওয়া হয়।
• ResolveNames সংক্রান্ত প্রয়োজনীয়তা:
  • queries-এর প্রতিটি আইটেমে অবশ্যই একটি খালি নয় এমন text প্যারামিটার উল্লেখ করতে হবে।
  • কোয়েরিতে অবশ্যই কোনও নির্দিষ্ট জায়গার নাম বা ঠিকানা থাকতে হবে (যেমন, "Googleplex, Mountain View, CA" বা "Eiffel Tower, Paris")।
  • সাধারণ বিভাগীয় সার্চ (যেমন, "নিউ ইয়র্কের রেস্তোরাঁ") বা লোকেশন ছাড়া সাধারণ চেনের নাম (যেমন, "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 Grounding Lite MCP সার্ভার Resolution API-কে দুটি টুল হিসেবে দেখায়:

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

আপনি যখন Maps Grounding Lite MCP সার্ভার ব্যবহার করার জন্য আপনার LLM কনফিগার করেন, তখন এই টুলগুলি অন্যান্য Maps Grounding Lite টুলের পাশাপাশি উপলভ্য হয়। টুলগুলি একই ইনপুট গ্রহণ করে, একই সীমাবদ্ধতা প্রয়োগ করে এবং 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-এর উদাহরণ

মনে রাখবেন: আপনি যদি Resolution API-এর এক্সপেরিমেন্টাল পর্যায়ে এটি ব্যবহার করা শুরু করে থাকেন, তাহলে v1alpha এন্ডপয়েন্ট কাজ করা চালিয়ে যাবে। আমরা সাজেস্ট করি যে আপনি v1 এন্ডপয়েন্টে মাইগ্রেট করুন।

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 Grounding Lite পাবলিক ইস্যু ট্র্যাকার কম্পোনেন্ট ব্যবহার করুন:

• সমস্যা সম্পর্কে অভিযোগ করুন
• ফিচার রিকোয়েস্ট জমা দিন
• মতামত জানান