জিওকোডিং v3 থেকে v4 এ স্থানান্তর করুন

ইউরোপীয় অর্থনৈতিক অঞ্চল (EEA) ডেভেলপাররা

জিওকোডিং এপিআই v4 বেশ কিছু নতুন মেথড চালু করেছে যা এপিআই-এর v3-এর কার্যকারিতা প্রতিস্থাপন করে। এই নির্দেশিকাটি আপনাকে দেখাবে কীভাবে আপনার অ্যাপকে নতুন v4 মেথডগুলো ব্যবহার করার জন্য মাইগ্রেট করবেন।

আপনি আপনার বিদ্যমান এপিআই কীগুলো নতুন v4 পদ্ধতিগুলোর সাথে ব্যবহার করতে পারবেন। তবে, আপনি যদি এপিআই-এর v3 সংস্করণের জন্য কোটা বৃদ্ধির অনুরোধ করে থাকেন, তাহলে আপনাকে অবশ্যই নতুন v4 এপিআইগুলোর জন্যও অনুরোধ করতে হবে।

v3 ফরওয়ার্ড জিওকোডিং থেকে মাইগ্রেট করুন

আপনি যদি ঠিকানা জিওকোড করার জন্য v3 জিওকোডিং ব্যবহার করেন, তাহলে আপনার v4-এর ' Geocode an address' পদ্ধতিতে স্থানান্তরিত হওয়া উচিত, যা একটি GET অনুরোধ গ্রহণ করে।

v4 API-তে নাম, কাঠামো এবং বেশ কিছু প্যারামিটারের সাপোর্টে পরিবর্তন আনা হয়েছে। আমরা দৃঢ়ভাবে সুপারিশ করছি যে, রেসপন্সে আপনি যে ফিল্ডগুলো ফেরত পেতে চান, তা নির্দিষ্ট করার জন্য একটি ফিল্ড মাস্ক ব্যবহার করুন ।

অনুরোধ প্যারামিটার পরিবর্তন

v3 প্যারামিটার v4 প্যারামিটার নোট
address , components address অসংগঠিত ঠিকানা (v3 address ) এখন URL পাথে পাস করা হয়। কম্পোনেন্ট ফিল্টার (v3 components ) এখন address.* কোয়েরি প্যারামিটার হিসেবে পাস করা হয়।
bounds locationBias.rectangle নাম পরিবর্তন করা হয়েছে; কাঠামো পরিবর্তন করে অবজেক্ট করা হয়েছে।
language languageCode নাম পরিবর্তন করা হয়েছে।
region regionCode নাম পরিবর্তন করা হয়েছে।
extra_computations অপসারণ করা হয়েছে

প্রতিক্রিয়া ক্ষেত্রের পরিবর্তন

v3 ফিল্ড ভি৪ ফিল্ড নোট
status , error_message অপসারণ করা হয়েছে v4 HTTP স্ট্যাটাস কোড এবং এরর বডি ব্যবহার করে ।
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText নাম পরিবর্তন করা হয়েছে।
results.geometry.location_type results.granularity নাম পরিবর্তন করা হয়েছে।
results.geometry.location results.location ফিল্ডের নাম: lat / lng -> latitude / longitude ।
results.geometry.viewport results.viewport ক্ষেত্রের নাম: northeast / southwest -> high / low ।
results.postcode_localities results.postalCodeLocalities নাম পরিবর্তন করা হয়েছে। এখন এক বা একাধিক এলাকার জন্য ফেরত দেওয়া হয় (v3 আবশ্যক >1)।
results.partial_match অপসারণ করা হয়েছে
নতুন results.addressComponents.languageCode নির্দিষ্ট ঠিকানা উপাদানের ভাষা।
নতুন results.bounds high / low ব্যবহার করে সুস্পষ্ট সীমা নির্ধারণ করা হয়েছে।
নতুন results.place স্থানটির জন্য সম্পদের নাম।
নতুন results.postalAddress কাঠামোগত PostalAddress অবজেক্ট।

v3 রিভার্স জিওকোডিং থেকে মাইগ্রেট করুন

আপনি যদি স্থানাঙ্ককে ঠিকানায় রূপান্তর করতে v3 রিভার্স জিওকোডিং ব্যবহার করেন, তাহলে আপনার v4-এর 'রিভার্স জিওকোড এ লোকেশন' পদ্ধতিতে স্থানান্তরিত হওয়া উচিত, যা একটি GET অনুরোধ গ্রহণ করে।

v4 API-তে নাম, কাঠামো এবং বেশ কিছু প্যারামিটারের সাপোর্টে পরিবর্তন আনা হয়েছে। আমরা দৃঢ়ভাবে সুপারিশ করছি যে, রেসপন্সে আপনি যে ফিল্ডগুলো ফেরত পেতে চান, তা নির্দিষ্ট করার জন্য একটি ফিল্ড মাস্ক ব্যবহার করুন ।

অনুরোধ প্যারামিটার পরিবর্তন

v3 প্যারামিটার v4 প্যারামিটার নোট
language languageCode নাম পরিবর্তন করা হয়েছে।
region regionCode নাম পরিবর্তন করা হয়েছে।
result_type types নাম পরিবর্তন করা হয়েছে; এতে পুনরাবৃত্ত কোয়েরি প্যারামিটার ব্যবহার করা হয়েছে।
location_type granularity নাম পরিবর্তন করা হয়েছে; এতে পুনরাবৃত্ত কোয়েরি প্যারামিটার ব্যবহার করা হয়েছে।
extra_computations অপসারণ করা হয়েছে

প্রতিক্রিয়া ক্ষেত্রের পরিবর্তন

v3 ফিল্ড ভি৪ ফিল্ড নোট
status , error_message অপসারণ করা হয়েছে v4 HTTP স্ট্যাটাস কোড এবং এরর বডি ব্যবহার করে ।
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText নাম পরিবর্তন করা হয়েছে।
results.geometry.location_type results.granularity নাম পরিবর্তন করা হয়েছে।
results.geometry.location results.location ফিল্ডের নাম: lat / lng -> latitude / longitude ।
results.geometry.viewport results.viewport ক্ষেত্রের নাম: northeast / southwest -> high / low ।
নতুন results.addressComponents.languageCode নির্দিষ্ট ঠিকানা উপাদানের ভাষা।
নতুন results.bounds high / low ব্যবহার করে সুস্পষ্ট সীমা নির্ধারণ করা হয়েছে।
নতুন results.place স্থানটির জন্য সম্পদের নাম।
নতুন results.postalAddress কাঠামোগত PostalAddress অবজেক্ট।

v3 অ্যাড্রেস ডেসক্রিপ্টর থেকে মাইগ্রেট করুন

আপনি যদি Geocoding v3-এর মাধ্যমে কোনো অবস্থান সম্পর্কে অতিরিক্ত তথ্য পেতে address_descriptor ব্যবহার করেন, তাহলে আপনাকে অবশ্যই SearchDestinationsResponse এর landmarks ফিল্ডটি ব্যবহার শুরু করতে হবে।

v3 স্থান ভূ-কোডিং থেকে স্থানান্তরিত করুন

আপনি যদি জিওকোডিং v3-তে কোনো নির্দিষ্ট প্লেস আইডি-র ঠিকানা পেতে place_id ব্যবহার করেন, তাহলে আপনাকে অবশ্যই v4 প্লেস জিওকোডিং পদ্ধতিতে স্থানান্তরিত হতে হবে, যা একটি GET রিকোয়েস্ট গ্রহণ করে।

v4 API-তে নাম, কাঠামো এবং বেশ কিছু প্যারামিটারের সাপোর্টে পরিবর্তন আনা হয়েছে। আমরা দৃঢ়ভাবে সুপারিশ করছি যে, রেসপন্সে আপনি যে ফিল্ডগুলো ফেরত পেতে চান, তা নির্দিষ্ট করার জন্য একটি ফিল্ড মাস্ক ব্যবহার করুন ।

অনুরোধ প্যারামিটার পরিবর্তন

v3 প্যারামিটার v4 প্যারামিটার নোট
place_id অনুরোধ প্রোটোতে ক্ষেত্র place প্লেস আইডি এখন places/{place} পাথ প্যারামিটার হিসেবে প্রদান করা হয়, উদাহরণস্বরূপ: https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw । এটি মূল রিকোয়েস্টের প্লেস ফিল্ডের সাথে ম্যাপ করা থাকে।
language languageCode নাম পরিবর্তন করা হয়েছে।
region regionCode নাম পরিবর্তন করা হয়েছে।

প্রতিক্রিয়া ক্ষেত্রের পরিবর্তন

v3 ফিল্ড ভি৪ ফিল্ড নোট
status , error_message অপসারণ করা হয়েছে v4 HTTP স্ট্যাটাস কোড এবং এরর বডি ব্যবহার করে ।
results (মূল) v4 একটি একক ফলাফল অবজেক্ট ফেরত দেয়, কোনো results অ্যারে নয়।
results.address_components.long_name / results.address_components.short_name addressComponents.longText / addressComponents.shortText নাম পরিবর্তন করা হয়েছে।
results.geometry.location_type granularity নাম পরিবর্তন করা হয়েছে।
results.geometry.location location ফিল্ডের নাম: lat / lng -> latitude / longitude ।
results.geometry.viewport viewport ক্ষেত্রের নাম: northeast / southwest -> high / low ।
results.postcode_localities postalCodeLocalities নাম পরিবর্তন করা হয়েছে। এখন এক বা একাধিক এলাকার জন্য ফেরত দেওয়া হয় (v3 আবশ্যক >1)।
নতুন addressComponents.languageCode নির্দিষ্ট ঠিকানা উপাদানের ভাষা।
নতুন bounds high / low ব্যবহার করে সুস্পষ্ট সীমা নির্ধারণ করা হয়েছে।
নতুন place স্থানটির জন্য সম্পদের নাম।
নতুন postalAddress কাঠামোগত PostalAddress অবজেক্ট।

জিওকোডিং হাইপারলোকাল ডেটা থেকে গন্তব্যে স্থানান্তরিত করুন

জিওকোডিং এপিআই v3-এর নিম্নলিখিত বৈশিষ্ট্যগুলি জিওকোডিং এপিআই v4-এর SearchDestinations পদ্ধতি দ্বারা প্রতিস্থাপিত হচ্ছে:

  • প্রবেশপথ
  • নেভিগেশন পয়েন্ট
  • ভবনের রূপরেখা
  • মাঠ

আপনি যদি উপরের ফিচারগুলোর জন্য জিওকোডিং এপিআই ভি৩ ব্যবহার করে থাকেন, তবে এই ফিচারগুলো পাওয়ার জন্য এর পরিবর্তে SearchDestinations মেথডটি ব্যবহার করতে এই ডকুমেন্টটি আপনাকে সাহায্য করবে। এই ডকুমেন্টটিতে ব্যাখ্যা করা হয়েছে যে SearchDestinations রেসপন্সের কোথায় এই ফিচারগুলো খুঁজে পাওয়া যাবে, এবং জিওকোডিং এপিআই ভি৩ ও জিওকোডিং এপিআই ভি৪-এর SearchDestinations মেথডের মধ্যে এপিআই রেসপন্সে এই ফিচারগুলো কীভাবে উপস্থাপিত হয় তার পার্থক্যগুলো কী।

প্রবেশপথ

কোনো destination সাথে সম্পর্কিত প্রবেশপথগুলো পেতে, destination.entrances ফিল্ডটি ব্যবহার করুন।

উল্লেখ্য যে, একটি entrance ফরম্যাটটি Geocoding API v3-এর এন্ট্রান্স ফরম্যাট থেকে কিছুটা ভিন্ন। destination.entrances এর প্রতিটি এন্ট্রান্সে নিম্নলিখিত ফিল্ডগুলো রয়েছে:

  • displayName - এটি একটি নতুন ঐচ্ছিক ফিল্ড যেখানে প্রবেশপথের জন্য একটি সহজে পঠনযোগ্য নাম থাকবে, যেমন "গেট বি"।
  • location - এটি LatLng টাইপের একটি অবস্থান, যা Geocoding API v3-তে ব্যবহৃত ফরম্যাট থেকে ভিন্ন।
  • tags - এটি জিওকোডিং এপিআই v3-এর এন্ট্রান্সগুলোর tags ফিল্ডের মতোই।
  • place - এটি জিওকোডিং এপিআই v3-এর প্রবেশপথের buildingPlaceId ফিল্ডের অনুরূপ। তবে, এই ফিল্ডের প্লেস আইডি যেকোনো ধরনের স্থানের জন্য হতে পারে, এটি কেবল একটি ভবনের জন্যই হতে হবে এমন কোনো বাধ্যবাধকতা নেই।

কোনো destination সাথে যুক্ত নেভিগেশন পয়েন্টগুলো পেতে, destination.navigationPoints ফিল্ডটি ব্যবহার করুন।

উল্লেখ্য যে, একটি navigationPoint এর ফরম্যাটটি Geocoding API v3-এর নেভিগেশন পয়েন্ট ফরম্যাট থেকে কিছুটা ভিন্ন। destination.navigationPoints এর প্রতিটি নেভিগেশন পয়েন্টে নিম্নলিখিত ফিল্ডগুলো থাকে:

  • displayName - এটি একটি নতুন ঐচ্ছিক ফিল্ড, যেখানে নেভিগেশন পয়েন্টের জন্য একটি সহজে পঠনযোগ্য নাম থাকবে, যেমন "5th Ave"।
  • location - এটি LatLng টাইপের একটি অবস্থান, যা Geocoding API v3-তে ব্যবহৃত ফরম্যাট থেকে ভিন্ন।
  • travelModes - এটি Geocoding API v3-এর নেভিগেশন পয়েন্টের restrictedTravelModes ফিল্ডের অনুরূপ। সম্ভাব্য enum ভ্যালুগুলো একই, একমাত্র পার্থক্য হলো এই ফিল্ডটি এখন সীমাবদ্ধ ভ্রমণ মোডগুলোর পরিবর্তে নেভিগেশন পয়েন্টের জন্য গ্রহণযোগ্য ভ্রমণ মোডগুলোকে নির্দেশ করে।
  • usage - এটি একটি নতুন ফিল্ড যেখানে নেভিগেশন পয়েন্ট দ্বারা সমর্থিত ব্যবহারের ক্ষেত্রগুলো (use cases) থাকে। উল্লেখ্য যে, বেশিরভাগ নেভিগেশন পয়েন্টের ব্যবহার UNKNOWN থাকবে, কিন্তু এর মানে এই নয় যে নেভিগেশন পয়েন্টটির ব্যবহার কোনোভাবে সীমাবদ্ধ।

ভবনের রূপরেখা

কোনো destination সাথে যুক্ত বিল্ডিংয়ের রূপরেখা পেতে, সেই destination বিল্ডিং-প্রতিনিধিত্বকারী placeView অবজেক্টগুলোর displayPolygon ফিল্ড ব্যবহার করা উচিত। প্রতিটি placeView জন্য, আপনি placeView.structureType ফিল্ড ব্যবহার করে সেটি একটি বিল্ডিং কিনা তা যাচাই করতে পারেন। যদি কাঠামোর ধরন BUILDING হয়, তবে আপনি placeView.displayPolygon ফিল্ড থেকে রূপরেখাটি পেতে পারেন। placeView বিল্ডিংয়ের জন্য এমন কিছু অতিরিক্ত ফিল্ডও থাকবে যা Geocoding API v3-তে ছিল না।

একটি destination একটি placeView অবজেক্ট থাকতে পারে যা নিম্নলিখিত ক্ষেত্রগুলিতে একটি ভবনকে প্রতিনিধিত্ব করে:

  • destination.primary - এটি গন্তব্যের প্রধান স্থান।
  • destination.containingPlaces - এটি একটি পুনরাবৃত্ত ক্ষেত্র যা এমন বৃহত্তর স্থানগুলিকে ধারণ করতে পারে যেগুলি প্রাথমিক স্থানটিকে "ধারণ করে"। উদাহরণস্বরূপ, যদি প্রাথমিক স্থানটি একটি subpremise হয়, তাহলে containingPlaces সাধারণত বিল্ডিংটির প্রতিনিধিত্বকারী placeView ধারণ করবে।
  • destination.subDestinations - এটি একটি পুনরাবৃত্ত ক্ষেত্র যা মূল স্থানের উপ-গন্তব্যগুলো ধারণ করতে পারে। উদাহরণস্বরূপ, একটি ভবনের স্বতন্ত্র অ্যাপার্টমেন্ট ইউনিট। এই ক্ষেত্রটিতে সাধারণত কোনো ভবনের প্রতিনিধিত্বকারী placeView থাকবে না।

উল্লেখ্য যে, placeView.displayPolygon এর ফরম্যাটটি Geocoding API v3-এর বিল্ডিং আউটলাইন ফরম্যাটের সাথে মেলে, যা হলো GeoJSON ফরম্যাট এবং এটি RFC 7946 ফরম্যাট ব্যবহার করে।

মাঠ

বিল্ডিং আউটলাইনের মতোই, কোনো destination সাথে যুক্ত গ্রাউন্ডগুলো পেতে হলে, সেই destination গ্রাউন্ডগুলোকে প্রতিনিধিত্বকারী placeView অবজেক্টগুলোর displayPolygon ফিল্ড ব্যবহার করতে হবে। প্রতিটি placeView জন্য, আপনি placeView.structureType ফিল্ড ব্যবহার করে সেটি একটি গ্রাউন্ড কিনা তা যাচাই করতে পারেন। যদি স্ট্রাকচার টাইপটি GROUNDS হয়, তবে আপনি placeView.displayPolygon ফিল্ড থেকে আউটলাইনটি পেতে পারেন। গ্রাউন্ডগুলোর জন্য placeView এমন কিছু অতিরিক্ত ফিল্ডও থাকবে যা Geocoding API v3-তে ছিল না।

একটি destination একটি placeView অবজেক্ট থাকতে পারে যা নিম্নলিখিত ক্ষেত্রগুলিতে একটি মাঠকে প্রতিনিধিত্ব করে:

  • destination.primary
  • destination.containingPlaces
  • destination.subDestinations

উল্লেখ্য যে, placeView.displayPolygon এর ফরম্যাটটি Geocoding API v3-এর গ্রাউন্ডস আউটলাইন ফরম্যাটের সাথে মেলে, যা হলো GeoJSON ফরম্যাট এবং এটি RFC 7946 ফরম্যাট ব্যবহার করে।

এই বৈশিষ্ট্যগুলির অনুরোধ করতে একটি ফিল্ড মাস্ক ব্যবহার করুন।

“ফেরত দেওয়ার জন্য ফিল্ড নির্বাচন করুন” অংশে যেমন ব্যাখ্যা করা হয়েছে, SearchDestinations মেথডটির জন্য একটি ফিল্ড মাস্ক প্রয়োজন। সমস্ত ফিল্ড ফেরত পাওয়ার জন্য ফিল্ড মাস্কটি * এ সেট করা যেতে পারে, অথবা আপনি যে নির্দিষ্ট ফিল্ডগুলো পেতে চান সেগুলোতেও এটি সেট করতে পারেন। উদাহরণস্বরূপ, নিম্নলিখিত এপিআই অনুরোধটি একটি গন্তব্যের প্রবেশপথ, নেভিগেশন পয়েন্ট, ভবনের রূপরেখা এবং প্রাঙ্গণ পাওয়ার জন্য প্রয়োজনীয় সমস্ত ফিল্ড গ্রহণ করতে ফিল্ড মাস্কটি সেট করে:

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4/geocode/destinations

নিরাপত্তা সংক্রান্ত বিবেচনা

জিওকোডিং এপিআই ভি৪ একটি সার্ভার-টু-সার্ভার এপিআই হিসেবে ডিজাইন করা হয়েছে। জাভাস্ক্রিপ্ট ব্যবহারকারীদের জন্য ভি৩ থেকে ভি৪-এ সরাসরি মাইগ্রেশনের কোনো পথ নেই। এপিআই কী ব্যবহার করে ক্লায়েন্ট-সাইড জাভাস্ক্রিপ্ট থেকে (যেমন, ব্রাউজারে) সরাসরি ভি৪ মেথডগুলো কল করলে আপনার এপিআই কী চুরি এবং অপব্যবহারের উচ্চ ঝুঁকিতে পড়ে।

HTTP রেফারার বিধিনিষেধগুলো কার্যকর হলেও, ওয়েব সার্ভিস এন্ডপয়েন্টগুলোর জন্য তা যথেষ্ট সুরক্ষা নয়, কারণ আক্রমণকারীরা তাদের অনুরোধে Referer হেডার জাল করে খুব সহজেই এগুলোকে পাশ কাটিয়ে যেতে পারে।

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

ক্লায়েন্ট-সাইডের প্রয়োজনের জন্য বিকল্প

আপনার যদি ক্লায়েন্ট-সাইডে জিওকোডিংয়ের প্রয়োজন হয়, তাহলে বিদ্যমান ক্লায়েন্ট-সাইড সমাধানগুলোর মধ্যে একটি ব্যবহার করার কথা বিবেচনা করতে পারেন:

  • Maps JavaScript API-এর Geocoding Service: Geocoding Service- টি v3 ব্যাকএন্ড ব্যবহার করে চলেছে এবং এটি ব্রাউজার পরিবেশে ব্যবহারের জন্য ডিজাইন করা হয়েছে।
  • প্লেসেস UI কিট: ঠিকানা-সম্পর্কিত ইউজার ইন্টারফেস এলিমেন্টের জন্য প্লেসেস UI কিট ব্যবহার করুন, যার মধ্যে প্লেস অটোকমপ্লিট এলিমেন্টগুলোও অন্তর্ভুক্ত রয়েছে।