از ویژگی های نسخه 3 به نقطه پایانی SearchDestinations مهاجرت کنید

این محصول یا ویژگی آزمایشی (قبل از نسخه عمومی گوگل) است. محصولات و ویژگی‌های قبل از نسخه عمومی گوگل ممکن است پشتیبانی محدودی داشته باشند و تغییرات در محصولات و ویژگی‌های قبل از نسخه عمومی گوگل ممکن است با سایر نسخه‌های قبل از نسخه عمومی گوگل سازگار نباشد. پیشنهادات قبل از نسخه عمومی گوگل تحت پوشش شرایط خاص سرویس پلتفرم نقشه‌های گوگل هستند. برای اطلاعات بیشتر، به توضیحات مرحله راه‌اندازی مراجعه کنید.

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

اگر آدرس صورتحساب شما در منطقه اقتصادی اروپا باشد، که از ۸ ژوئیه ۲۰۲۵ لازم‌الاجرا است، شرایط خدمات پلتفرم نقشه‌های گوگل (EEA) برای استفاده شما از خدمات اعمال خواهد شد. عملکرد آن بر اساس منطقه متفاوت است. اطلاعات بیشتر .

ویژگی‌های زیر در 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