API نسخه ۴ ژئوکدینگ چندین نقطه پایانی جدید را معرفی میکند که جایگزین قابلیتهای نسخه ۳ این API میشوند. این راهنما به شما نشان میدهد که چگونه برنامه خود را برای استفاده از نقاط پایانی جدید نسخه ۴ منتقل کنید.
شما میتوانید از کلیدهای API موجود خود با نقاط پایانی جدید نسخه ۴ استفاده کنید. با این حال، اگر درخواست افزایش سهمیه در نسخه ۳ API را دادهاید، باید درخواست افزایش سهمیه در APIهای جدید نسخه ۴ را نیز ارائه دهید. هیچ مسیر مهاجرتی برای کاربران جاوا اسکریپت وجود ندارد.
مهاجرت از نسخه ۳ به جلو
اگر از Geocoding برای geocode کردن آدرسها استفاده میکنید، باید به یک نقطه پایانی آدرس در 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 ساختاریافته. |
مهاجرت از ژئوکدینگ معکوس نسخه ۳
اگر از ژئوکدینگ معکوس برای تبدیل مختصات به آدرس استفاده میکنید، باید به یک نقطه پایانی مکان در ژئوکدینگ معکوس نسخه ۴ مهاجرت کنید که درخواست 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 میتوان این ویژگیها را پیدا کرد و تفاوتهای نحوه نمایش این ویژگیها در پاسخهای 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/v4alpha/geocode/destinations