Maps Tools Resolution API

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

Maps Grounding Lite MCP সার্ভারে রেজোলিউশন API, REST পদ্ধতি ও টুল হিসেবে উপলভ্য:

ক্ষমতা	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 হেডার অথবা অনুরোধের URL-এ একটি সঠিক Google Maps Platform API কী যোগ করে অনুরোধ যাচাই করতে পারেন:

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-এর অধীনে কোনও চার্জ লাগে না ($০)। 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 তালিকা (for ResolveNames) বা entities তালিকা (for 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-এর সাথে Resolution API ব্যবহার করা

https://mapstools.googleapis.com/mcp-এ Maps Grounding Lite MCP সার্ভার দুটি টুল হিসেবে রেজোলিউশন 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-এ তালিকা হিসেবে সেভ, শেয়ার বা খুলতে চান, তখন যেন এই লিঙ্কটি দেখানো হয়। এর পরিবর্তে, LLM যেন নিজে থেকে কোনও লিঙ্ক তৈরি না করে।

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

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

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