মানচিত্র সরঞ্জাম রেজোলিউশন এপিআই (পরীক্ষামূলক)

ম্যাপস টুলস রেজোলিউশন এপিআই লোকেশনের নাম এবং ইউআরএল-কে গুগল ম্যাপস প্লেস আইডি-তে রূপান্তর করার জন্য ব্যাচ প্রসেসিং এন্ডপয়েন্ট সরবরাহ করে।

এপিআই অ্যাক্সেস এবং প্রমাণীকরণ

পরীক্ষামূলক: ResolveNames এবং ResolveMapsUrls এপিআইগুলো পরীক্ষামূলক (প্রি-জিএ) পর্যায়ে রয়েছে। প্রি-জিএ পণ্য এবং ফিচারগুলোর সাপোর্ট সীমিত হতে পারে, এবং প্রি-জিএ পণ্য ও ফিচারগুলোতে করা পরিবর্তনগুলো অন্যান্য প্রি-জিএ ভার্সনের সাথে সামঞ্জস্যপূর্ণ নাও হতে পারে। প্রি-জিএ অফারিংগুলো Google Maps Platform Service Specific Terms- এর আওতাভুক্ত। আরও তথ্যের জন্য, লঞ্চ স্টেজের বিবরণ দেখুন। পরীক্ষামূলক পর্যায়ে থাকাকালীন ResolveNames এবং ResolveMapsUrls ব্যবহার করার জন্য কোনো চার্জ নেই।

প্রমাণীকরণ পদ্ধতি

এপিআইগুলো এপিআই কী এবং ওঅথ ২.০ উভয় প্রকার ক্রেডেনশিয়াল সমর্থন করে:

১. এপিআই কী

আপনি অনুরোধের URL-এর শেষে অথবা X-Goog-Api-Key হেডারে একটি বৈধ Google Maps Platform API Key যুক্ত করে অনুরোধগুলি প্রমাণীকরণ করতে পারেন:

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

২. OAuth 2.0 স্কোপ

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

• https://www.googleapis.com/auth/maps-platform.mapstools (প্রস্তাবিত)

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

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

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

আংশিক ত্রুটি পরিচালনা করা

উভয় এপিআই-ই ব্যাচ প্রসেসর হিসেবে ডিজাইন করা হয়েছে। যদি কোনো ব্যাচের কিছু আইটেম সমাধান হতে ব্যর্থ হয়, তবে সামগ্রিক অনুরোধটি কোনো শীর্ষ-স্তরের ত্রুটির কারণে ব্যর্থ হয় না । পরিবর্তে, এপিআইটি একটি 'আংশিক সফল' (Partial Success) প্রতিক্রিয়া ফেরত দেয়।

প্রতিক্রিয়াটি কীভাবে ব্যাখ্যা করবেন

1. নিশ্চিত ১:১ অ্যালাইনমেন্ট : ফেরত আসা ফলাফলের ( ResolveNames জন্য) বা এনটিটিগুলোর ( ResolveMapsUrls এর জন্য) তালিকাগুলো ইনপুট তালিকার সাথে ১:১ অনুপাতে ম্যাপ করে।
2. ব্যর্থতার জন্য খালি উপাদান : যদি i সূচকের কোনো আইটেম সমাধান করতে ব্যর্থ হয়, তাহলে ফলাফল তালিকায় i সূচকে একটি খালি অবজেক্ট {} থাকবে।
3. failedRequests Map : রেসপন্সটিতে একটি failedRequests ম্যাপ থাকে।
   • মূল বিষয়টি হলো ব্যর্থ আইটেমটির ০-ভিত্তিক সূচক (যা JSON-এ একটি স্ট্রিং হিসাবে উপস্থাপিত হয়)।
   • এর মান হলো একটি google.rpc.Status অবজেক্ট, যাতে নির্দিষ্ট এরর কোড (স্ট্যান্ডার্ড gRPC/HTTP স্ট্যাটাস থেকে নেওয়া) এবং ব্যর্থতার কারণ ব্যাখ্যা করে একটি বিস্তারিত বার্তা থাকে।

শীর্ষ-স্তরের ব্যর্থতা

একটি শীর্ষ-স্তরের HTTP ত্রুটি (যেমন, 400 Bad Request ) শুধুমাত্র তখনই ফেরত দেওয়া হয়, যখন অনুরোধটি বৈধতা যাচাইয়ে ব্যর্থ হয় (যেমন, ২০টির বেশি আইটেম দিলে বা প্রয়োজনীয় ফিল্ড অনুপস্থিত থাকলে)।

এপিআই স্পেসিফিকেশন এবং কার্ল উদাহরণ

১. ResolveNames API

পদ্ধতি: পোস্ট

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

অনুরোধের মূল অংশের বিন্যাস

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}

• queries (আবশ্যক): সমাধান করার জন্য পুনরাবৃত্ত কোয়েরির তালিকা (সর্বোচ্চ ২০টি)।
• locationBias (ঐচ্ছিক): ফলাফলকে একটি স্থানীয় অঞ্চলের দিকে পক্ষপাতদুষ্ট করার জন্য ভিউপোর্ট বাউন্ডিং বক্স।
• regionCode (ঐচ্ছিক): ফলাফলকে প্রভাবিত করার জন্য CLDR দেশের কোড (যেমন "US", "FR")।

কার্ল উদাহরণ: সফল সমাধান

এই কোয়েরিটি 'Googleplex' এবং 'Eiffel Tower' সনাক্ত করে।

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveNames?key=KEY"

JSON প্রতিক্রিয়া

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

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

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

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/v1alpha:resolveNames?key=KEY"

JSON প্রতিক্রিয়া

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

২. ResolveMapsUrls API

পদ্ধতি: পোস্ট

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

অনুরোধের মূল অংশের বিন্যাস

{
  "urls": [
    "string"
  ]
}

• urls (আবশ্যক): সমাধান করার জন্য গুগল ম্যাপস ইউআরএল স্ট্রিং-এর পুনরাবৃত্ত তালিকা (সর্বোচ্চ ২০টি)।

কার্ল উদাহরণ: সফল সমাধান

একটি সাধারণ গুগল ম্যাপস প্লেস লিঙ্ক সমাধান করা।

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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

JSON প্রতিক্রিয়া

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

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

একটি বৈধ স্থানের ইউআরএল এবং একটি ত্রুটিপূর্ণ/অসমর্থিত ইউআরএল সমাধান করা হচ্ছে।

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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

JSON প্রতিক্রিয়া

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid 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/v1alpha:resolveMapsUrls?key=KEY"

JSON প্রতিক্রিয়া

{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}