مهاجرت از Geocoding نسخه ۳ به نسخه ۴

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

API نسخه ۴ ژئوکدینگ چندین متد جدید معرفی می‌کند که جایگزین قابلیت‌های نسخه ۳ این API می‌شوند. این راهنما به شما نشان می‌دهد که چگونه برنامه خود را برای استفاده از متدهای جدید نسخه ۴ مهاجرت دهید.

شما می‌توانید از کلیدهای API موجود خود با روش‌های جدید نسخه ۴ استفاده کنید. با این حال، اگر درخواست افزایش سهمیه در نسخه ۳ API را داده‌اید، باید برای APIهای جدید نسخه ۴ نیز درخواست افزایش سهمیه دهید.

مهاجرت از نسخه ۳ به جلو

اگر از Geocoding برای geocode کردن آدرس‌ها استفاده می‌کنید، باید به متد address نسخه ۴ Geocode مهاجرت کنید که درخواست GET را می‌پذیرد.

API نسخه ۴ نام‌ها، ساختار و پشتیبانی از چندین پارامتر را تغییر می‌دهد. اکیداً توصیه می‌کنیم از یک ماسک فیلد برای مشخص کردن فیلدهایی که می‌خواهید در پاسخ برگردانده شوند، استفاده کنید .

درخواست تغییر پارامترها

پارامتر v3 پارامتر v4 یادداشت‌ها
address ، components address آدرس بدون ساختار ( address نسخه ۳) اکنون در مسیر URL ارسال می‌شود. فیلترهای کامپوننت ( components نسخه ۳) اکنون به عنوان پارامترهای پرس و جوی address.*
bounds locationBias.rectangle تغییر نام داد؛ ساختار به شیء تغییر یافت.
language languageCode تغییر نام داده شده.
region regionCode تغییر نام داده شده.
extra_computations حذف شد

تغییرات فیلد پاسخ

فیلد v3 فیلد v4 یادداشت‌ها
status ، error_message حذف شد نسخه ۴ از کدهای وضعیت 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 ساختاریافته.

مهاجرت از ژئوکدینگ معکوس نسخه ۳

اگر از Reverse Geocoding برای تبدیل مختصات به آدرس استفاده می‌کنید، باید به متد مکان‌یابی Reverse geocode نسخه ۴ مهاجرت کنید که درخواست GET را می‌پذیرد.

API نسخه ۴ نام‌ها، ساختار و پشتیبانی از چندین پارامتر را تغییر می‌دهد. اکیداً توصیه می‌کنیم از یک ماسک فیلد برای مشخص کردن فیلدهایی که می‌خواهید در پاسخ برگردانده شوند، استفاده کنید .

درخواست تغییر پارامترها

پارامتر v3 پارامتر v4 یادداشت‌ها
language languageCode تغییر نام داده شده.
region regionCode تغییر نام داده شده.
result_type types تغییر نام داده شده؛ از پارامترهای پرس و جوی تکراری استفاده می‌کند.
location_type granularity تغییر نام داده شده؛ از پارامترهای پرس و جوی تکراری استفاده می‌کند.
extra_computations حذف شد

تغییرات فیلد پاسخ

فیلد v3 فیلد v4 یادداشت‌ها
status ، error_message حذف شد نسخه ۴ از کدهای وضعیت 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 ساختاریافته.

مهاجرت از نسخه ۳ مکان‌یابی جغرافیایی

اگر place_id برای دریافت آدرس یک Place ID خاص با Geocoding نسخه ۳ استفاده می‌کنید، باید به متد Place Geocoding نسخه ۴ مهاجرت کنید که درخواست GET را می‌پذیرد.

API نسخه ۴ نام‌ها، ساختار و پشتیبانی از چندین پارامتر را تغییر می‌دهد. اکیداً توصیه می‌کنیم از یک ماسک فیلد برای مشخص کردن فیلدهایی که می‌خواهید در پاسخ برگردانده شوند، استفاده کنید .

درخواست تغییر پارامترها

پارامتر v3 پارامتر v4 یادداشت‌ها
place_id فیلد را در درخواست اولیه place شناسه مکان اکنون به عنوان پارامتر مسیر places/{place} ارائه می‌شود، برای مثال: https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw . این به فیلد مکان در درخواست اصلی نگاشت می‌شود.
language languageCode تغییر نام داده شده.
region regionCode تغییر نام داده شده.

تغییرات فیلد پاسخ

فیلد v3 فیلد v4 یادداشت‌ها
status ، error_message حذف شد نسخه ۴ از کدهای وضعیت HTTP و بدنه‌های خطا استفاده می‌کند .
results (ریشه) نسخه ۴ یک شیء نتیجه واحد را برمی‌گرداند، نه یک آرایه 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 ساختاریافته.

مهاجرت از داده‌های فرامحلی ژئوکدینگ به مقاصد

ویژگی‌های زیر در Geocoding API نسخه ۳ با متد SearchDestinations از Geocoding API نسخه ۴ جایگزین می‌شوند:

  • ورودی‌ها
  • نقاط ناوبری
  • طرح کلی ساختمان
  • زمین‌ها

اگر برای ویژگی‌های فوق از Geocoding API نسخه ۳ استفاده می‌کردید، از این سند برای کمک به شما در استفاده از متد SearchDestinations به جای آن برای دریافت این ویژگی‌ها استفاده کنید. این سند توضیح می‌دهد که در کجای پاسخ SearchDestinations می‌توان این ویژگی‌ها را پیدا کرد و تفاوت‌های نحوه نمایش این ویژگی‌ها در پاسخ‌های API بین Geocoding API نسخه ۳ و متد SearchDestinations از Geocoding API نسخه ۴ را شرح می‌دهد.

ورودی‌ها

برای دریافت ورودی‌های مرتبط با یک destination ، از فیلد destination.entrances استفاده کنید.

توجه داشته باشید که قالب یک entrance کمی با قالب ورودی در Geocoding API نسخه ۳ متفاوت است. هر ورودی در destination.entrances دارای فیلدهای زیر است:

  • displayName - این یک فیلد اختیاری جدید است که یک نام خوانا برای ورودی خواهد داشت، برای مثال "دروازه B".
  • location - این یک مکان از نوع LatLng است که با فرمت مورد استفاده در Geocoding API نسخه ۳ متفاوت است.
  • tags - این همان فیلد tags برای ورودی‌ها از API Geocoding نسخه ۳ است.
  • place - مشابه فیلد buildingPlaceId ورودی‌ها از Geocoding API نسخه ۳. با این حال، شناسه مکان در این فیلد می‌تواند برای هر نوع مکانی باشد، نه لزوماً فقط یک ساختمان.

برای دریافت نقاط ناوبری مرتبط با یک destination ، از فیلد destination.navigationPoints استفاده کنید.

توجه داشته باشید که قالب یک navigationPoint کمی با قالب نقطه ناوبری در Geocoding API نسخه ۳ متفاوت است. هر نقطه ناوبری در destination.navigationPoints دارای فیلدهای زیر است:

  • displayName - این یک فیلد اختیاری جدید است که یک نام خوانا برای نقطه ناوبری خواهد داشت، برای مثال "خیابان پنجم".
  • location - این یک مکان از نوع LatLng است که با فرمت مورد استفاده در Geocoding API نسخه ۳ متفاوت است.
  • travelModes - این فیلد مشابه فیلد restrictedTravelModes مربوط به نقاط ناوبری از Geocoding API نسخه ۳ است. مقادیر شمارشی ممکن یکسان هستند، تنها تفاوت این است که این فیلد اکنون حالت‌های سفر قابل قبول برای نقطه ناوبری را نشان می‌دهد، نه حالت‌های سفر محدود شده.
  • usage - این یک فیلد جدید است که شامل موارد استفاده پشتیبانی شده توسط نقطه ناوبری است. توجه داشته باشید که اکثر نقاط ناوبری کاربرد UNKNOWN دارند، اما این لزوماً به این معنی نیست که کاربرد نقطه ناوبری به هیچ وجه محدود شده است.

طرح کلی ساختمان

برای دریافت خطوط کلی ساختمان مرتبط با یک destination ، باید از فیلد displayPolygon از اشیاء placeView در destination که نشان دهنده ساختمان‌ها هستند استفاده کنید. برای هر placeView ، می‌توانید با فیلد placeView.structureType بررسی کنید که آیا یک ساختمان است یا خیر. اگر نوع ساختار BUILDING باشد، می‌توانید خطوط کلی را از فیلد placeView.displayPolygon دریافت کنید. placeView همچنین فیلدهای اضافی برای ساختمان خواهد داشت که در Geocoding API نسخه ۳ وجود نداشتند.

یک destination می‌تواند یک شیء placeView داشته باشد که نشان‌دهنده‌ی یک ساختمان در فیلدهای زیر است:

  • destination.primary - این مکان اصلی برای مقصد است.
  • destination.containingPlaces - این یک فیلد تکراری است که می‌تواند مکان‌های بزرگ‌تری را که «شامل» مکان اصلی هستند، در خود جای دهد. برای مثال، اگر مکان اصلی یک subpremise باشد، containingPlaces معمولاً placeView را که نمایانگر ساختمان است، در خود جای می‌دهد.
  • destination.subDestinations - این یک فیلد تکراری است که می‌تواند زیرمقصدهای مکان اصلی را در خود نگه دارد. به عنوان مثال، واحدهای آپارتمانی مجزا از یک ساختمان. این فیلد معمولاً placeView که نشان‌دهنده یک ساختمان است را نخواهد داشت.

توجه داشته باشید که قالب placeView.displayPolygon با قالب طرح کلی ساختمان در Geocoding API نسخه ۳ ، که فرمت GeoJSON است و از فرمت RFC 7946 استفاده می‌کند، مطابقت دارد.

زمین‌ها

مشابه خطوط بیرونی ساختمان، برای دریافت زمین‌های مرتبط با یک destination ، باید از فیلد displayPolygon از اشیاء placeView در destination که نشان‌دهنده زمین‌ها هستند استفاده کنید. برای هر placeView ، می‌توانید با استفاده از فیلد placeView.structureType بررسی کنید که آیا زمین است یا خیر. اگر نوع ساختار GROUNDS باشد، می‌توانید خطوط بیرونی را از فیلد placeView.displayPolygon دریافت کنید. placeView همچنین فیلدهای اضافی برای زمین‌هایی که در Geocoding API نسخه ۳ وجود نداشتند، خواهد داشت.

یک destination می‌تواند یک شیء placeView داشته باشد که نشان‌دهنده‌ی یک زمینه (grounds) در فیلدهای زیر است:

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

توجه داشته باشید که قالب placeView.displayPolygon با قالب طرح کلی زمین در Geocoding API نسخه ۳ ، که همان قالب GeoJSON است و از قالب RFC 7946 استفاده می‌کند، مطابقت دارد.

برای درخواست این ویژگی‌ها از یک ماسک میدانی استفاده کنید

همانطور که در بخش «انتخاب فیلدها برای بازگشت» توضیح داده شده است، متد SearchDestinations به یک ماسک فیلد نیاز دارد. ماسک فیلد را می‌توان روی * تنظیم کرد تا همه فیلدها را برگرداند، یا می‌توانید آن را روی فیلدهای خاصی که می‌خواهید دریافت کنید تنظیم کنید. برای مثال، درخواست API زیر، ماسک فیلد را طوری تنظیم می‌کند که تمام فیلدهای مورد نیاز برای دریافت ورودی‌ها، نقاط ناوبری، خطوط بیرونی ساختمان‌ها و محوطه یک مقصد را دریافت کند:

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/v4beta/geocode/destinations

ملاحظات امنیتی

رابط برنامه‌نویسی کاربردی Geocoding نسخه ۴ به عنوان یک رابط برنامه‌نویسی کاربردی سرور به سرور طراحی شده است. هیچ مسیر مهاجرت مستقیمی برای کاربران جاوا اسکریپت از نسخه ۳ به نسخه ۴ وجود ندارد. فراخوانی متدهای نسخه ۴ به طور مستقیم از جاوا اسکریپت سمت کلاینت (به عنوان مثال، در یک مرورگر) با استفاده از یک کلید API، کلید API شما را در معرض خطر بالای سرقت و سوءاستفاده قرار می‌دهد.

محدودیت‌های ارجاع‌دهنده HTTP، اگرچه مفید هستند، اما برای محافظت از نقاط پایانی سرویس وب کافی نیستند، زیرا مهاجمانی که هدر Referer را در درخواست‌های خود جعل می‌کنند، می‌توانند به راحتی از آنها عبور کنند.

روش توصیه‌شده برای استفاده از Geocoding API نسخه ۴، استفاده از سرور بک‌اند خودتان است. برنامه کلاینت شما باید درخواست‌هایی را به این سرور واسطه ارسال کند، که سپس با استفاده از یک کلید API محافظت‌شده (مثلاً کلیدی که در یک متغیر محیطی یا یک مدیر مخفی ذخیره شده است) به طور ایمن Google API را فراخوانی می‌کند. این تضمین می‌کند که کلید API شما هرگز در کد فرانت‌اند فاش نمی‌شود.

جایگزین‌هایی برای نیازهای سمت کلاینت

اگر نیازهای سمت کلاینت دارید که نیاز به کدگذاری جغرافیایی دارد، استفاده از یکی از راه‌حل‌های سمت کلاینت موجود را در نظر بگیرید: