روش‌های Geocoding API v4 سهمیه پیش‌فرض ۲۵ پُرسمان در ثانیه (QPS) دارند. برای اطلاعات بیشتر درباره درخواست سهمیه بیشتر، به مشاهده و مدیریت سهمیه‌ها مراجعه کنید و Geocoding API را به‌عنوان سرویس انتخاب کنید.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

جستجوی مقصدها

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

Destination به مکان یا جای خاصی اشاره دارد که کاربر قصد دارد به آن برسد یا به‌سمت آن پیمایش کند. Destination همچنین شامل مجموعه‌ای از اطلاعات مربوط به مکان یا جا است، مثل نقاط ناوبری، نشانگرهای مکانی، ورودی‌ها، و طرح کلی ساختمان.

روش SearchDestinations در Geocoding API به شما امکان می‌دهد اطلاعات دقیقی درباره مقصدهای مختلف براساس معیارهای ورودی متفاوت، مانند نشانی، شناسه مکان، یا مختصات طول و عرض جغرافیایی، بازیابی کنید.

درخواست جستجوی مقصدها

درخواست جستجوی مقصدها یک درخواست HTTP POST به نشانی وب در فرم است:

https://geocode.googleapis.com/v4/geocode/destinations

همه پارامترها را در بدنه درخواست JSON یا در سرصفحه‌ها به‌عنوان بخشی از درخواست POST ارسال کنید. برای مثال:

curl -X POST -d '{
  "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

می‌توانید مکان را برای جستجوی مقصد به یکی از ۳ روش زیر مشخص کنید:

نشانی
شناسه مکان
مختصات طول و عرض جغرافیایی

جستجوی مقصد براساس نشانی

می‌توانید نشانی را به‌صورت رشته‌ای بدون ساختار مشخص کنید. زمین‌کدیابی نشانی مختصات عرض جغرافیایی و طول جغرافیایی یا دیگر رشته‌های بدون ساختار را که نشان‌دهنده نشانی نیستند حل نمی‌کند. درخواست‌هایی که از این رشته‌ها استفاده می‌کنند پشتیبانی نمی‌شوند و ممکن است منجر به پاسخ‌های خطا یا رفتار نامشخص شوند. نمونه‌هایی از پُرسمان‌های پشتیبانی‌نشده شامل موارد زیر است:

نوع پُرسمان	مثال
مختصات طول و عرض جغرافیایی. به‌جای آن از پرس‌وجوی مکان استفاده کنید.	"37.422131,-122.084801"
مفاهیم یا محدودیت‌های بسیار زیاد، مانند نام چندین مکان، جاده، یا شهر در یک پُرسمان	«Market Street San Francisco San Jose Airport»
عناصر نشانی پستی که در Google Maps نشان داده نمی‌شود	«C/O John Smith 123 Main Street» «P.O. Box 13 San Francisco»
نام کسب‌وکارها، زنجیره‌ها، یا دسته‌هایی که با مکان‌هایی ترکیب شده‌اند که این نهادها در آن‌ها دردسترس نیستند	«Tesco near Dallas, Texas» (تسکو نزدیک دالاس، تگزاس)
پرسمان‌های مبهم با چند تفسیر	«تحویل شارژر»
نام‌های تاریخی که دیگر استفاده نمی‌شوند	"Middlesex United Kingdom"
عناصر یا قصد غیرزمین‌مکانی	«چند قایق در بندر ونتورا وجود دارد؟»
نام‌های غیررسمی یا نام‌های سفارشی	«برج هیجان» «سرسره مارپیچ»
نهادهای سیاسی بزرگ (شهرها، ایالت‌ها، کشورها)	"New York City" "California" "USA"
مسیرهای بدون نشانی مشخص	"1st Ave., NYC, NY" "I-95"

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "601 S Bernardo Ave, Sunnyvale, CA 94087, USA"
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

یا به‌عنوان postalAddress:

curl -X POST -d '{
  "addressQuery": {
    "address": {
      "addressLines": ["601 S Bernardo Ave"],
      "locality": "Sunnyvale",
      "postalCode": "94087",
      "administrativeArea": "CA",
      "regionCode": "US"
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

معمولاً هنگام پردازش مؤلفه‌های نشانی که در فرم HTML ضبط شده‌اند، از قالب postalAddress استفاده می‌کنید.

جستجوی مقصد با شناسه مکان

می‌توانید با ارائه شناسه مکان، مقصد را بازیابی کنید:

curl -X POST -d '{
  "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

شناسه‌های مکان پشتیبانی‌شده

روش «جستجوی مقصدها» با «شناسه‌های مکان» که نشان‌دهنده مقصدهای خاص و قابل‌پیمایش هستند بهترین عملکرد را دارد. شناسه‌های مکان برای انواع مکان‌هایی مثل establishment، point_of_interest، premise، street_address، و subpremise معمولاً پشتیبانی می‌شوند. شناسه‌های مکانی که مکان‌های مجزا را نشان نمی‌دهند، مانند شناسه‌هایی که از محدوده‌های نشانی استنباط می‌شوند (برای مثال، «خیابان اصلی ۱۰-۲۰»)، بخش‌هایی از یک مسیر بدون شماره خاص، یا Plus Code پشتیبانی نمی‌شوند. شناسه‌های مکان برای نتایجی که مساحت بسیار بزرگی دارند (برای مثال، «اقیانوس آرام») نیز پشتیبانی نمی‌شوند.

استفاده از «تکمیل خودکار» (جدید) با «مقصد جستجو»

برای اطمینان از سازگاری، از تکمیل خودکار (جدید) برای پیدا کردن شناسه‌های مکان برای استفاده با «جستجوی مقصدها» استفاده کنید. هنگام استفاده از «تکمیل خودکار» (جدید)، باید نتایج را براساس نوع بااستفاده از پارامتر includedPrimaryTypes فیلتر کنید. «جستجوی مقصدها» از شناسه‌های مکانی که «تکمیل خودکار (جدید)» بااستفاده از فیلتر توصیه‌شده زیر برمی‌گرداند پشتیبانی می‌کند:

"includedPrimaryTypes": [ "establishment", "point_of_interest", "premise", "street_address", "subpremise" ]

علاوه‌براین، نباید پرچم include_pure_service_area_businesses را در درخواست «تکمیل خودکار (جدید)» روی true تنظیم کنید.

جستجوی مقصد براساس مکان

می‌توانید با ارائه مختصات طول و عرض جغرافیایی، مقصدی را جستجو کنید:

curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

استفاده از OAuth برای درخواست کردن

Geocoding API v4 از OAuth 2.0 برای اصالت‌سنجی پشتیبانی می‌کند. برای استفاده از OAuth با Geocoding API، باید دامنه صحیح به کد OAuth اختصاص داده شود. Geocoding API از دامنه‌های زیر برای استفاده با روش Destinations پشتیبانی می‌کند:

https://www.googleapis.com/auth/maps-platform.geocode — با همه روش‌های Geocoding API استفاده کنید.

همچنین، می‌توانید از گستره عمومی https://www.googleapis.com/auth/cloud-platform برای همه روش‌های Geocoding API استفاده کنید. این گستره درطول توسعه مفید است، اما نه در تولید، زیرا گستره‌ای عمومی است که اجازه دسترسی به همه روش‌ها را می‌دهد.

برای اطلاعات بیشتر و مثال‌ها، به استفاده از OAuth مراجعه کنید.

پاسخ جستجوی مقصدها

پاسخ Search Destinations بافت غنی و بسیار محلی درباره مکان ارائه می‌دهد.

اشیاء PlaceView در پاسخ «جستجوی مقصدها» (مانند primary، موارد در containingPlaces، و landmarks) از فیلدها برای نشان دادن نوع مکان استفاده می‌کنند:

types: آرایه‌ای از رشته‌ها که نوع(انواع) مکان را نشان می‌دهد.
primaryType: رشته‌ای که نوع اصلی مکان را نشان می‌دهد.

مقادیر رشته‌ای ممکن برای types و primaryType از جدول الف و جدول ب در صفحه «انواع مکان (جدید)» گرفته شده است.

این بخش فیلدهای پاسخ کلیدی را شرح می‌دهد. برای جزئیات کامل درباره همه فیلدهای پاسخ، به مرجع میانای برنامه‌سازی کاربردی مراجعه کنید.

`primary`

مکان اصلی شناسایی‌شده توسط پُرسمان در درخواست.

`addressComponents`

آرایه‌ای حاوی مؤلفه‌های جداگانه قابل‌اعمال به این نشانی.

هر مؤلفه نشانی معمولاً شامل فیلدهای زیر است:

types[] آرایه‌ای است که نوع مؤلفه نشانی را نشان می‌دهد. فهرست انواع پشتیبانی‌شده را ببینید.
longText شرح نوشتاری کامل یا نام مؤلفه نشانی است که توسط «زمین‌کدیاب» برگردانده شده است.
shortText نام متنی اختصاری برای مؤلفه نشانی است، درصورت وجود. برای مثال، مؤلفه نشانی برای ایالت آلاسکا ممکن است longText «آلاسکا» و shortText «AK» را بااستفاده از مخفف پستی دوحرفی داشته باشد.
‫languageCode زبانی است که برای قالب‌بندی این مؤلفه در نماد CLDR استفاده می‌شود.

`containingPlaces`

آرایه‌ای از اشیا PlaceView که نشان‌دهنده نهادهای فضایی بزرگتری است که مقصد اصلی را دربرمی‌گیرد یا شامل آن می‌شود. برای مثال:

اگر مقصد اصلی فروشگاه یا رستورانی در مرکز خرید باشد، containingPlaces مرکز خرید (structureType: GROUNDS) را دربرمی‌گیرد.
اگر مقصد اصلی یک واحد آپارتمان مجزا (subpremise) باشد، containingPlaces شامل ساختمان مسکونی دربرگیرنده (structureType: BUILDING) و، درصورت وجود، مجتمع آپارتمانی وسیع‌تر (structureType: GROUNDS) می‌شود.

هر PlaceView در containingPlaces شامل displayName، placeId، location، structureType، و displayPolygon (درصورت دردسترس بودن) خودش است که به شما امکان می‌دهد کل پردیس یا طرح کلی مجتمع را درکنار واحد خاص پرداز کنید.

`subDestinations`

آرایه‌ای از اشیا PlaceView که نشان‌دهنده مکان‌های دقیق‌تر موجود در مقصد اصلی است. برای مثال:

هنگام جستجوی مرکز خرید، فرودگاه، یا محوطه دانشگاه، subDestinations فروشگاه‌ها، پایانه‌ها، دروازه‌ها، یا ساختمان‌های محوطه دانشگاه را به‌صورت جداگانه فهرست می‌کند.
هنگام جستجوی ساختمان مسکونی یا تجاری چندواحدی، subDestinations سوئیت‌ها یا واحدهای آپارتمانی را به‌صورت جداگانه فهرست می‌کند.

می‌توانید از containingPlaces و subDestinations باهم استفاده کنید تا انتخاب‌کننده‌های سلسله‌مراتبی تعاملی بسازید که به کاربران کمک می‌کند مکان‌های ورود پیچیده را ابهام‌زدایی کنند.

سلسله‌مراتب مقصد و رفتار پاسخ

هنگام تفسیر پاسخ Destination، قوانین و روابط ساختاری زیر را در ذهن داشته باشید:

primary: نشان‌دهنده دقیق‌ترین نهاد حل‌شده برای پُرسمان شما است (مثل ساختمان یا زیرمجموعه). این مورد در اکثر موارد استفاده عادی پر می‌شود. بااین‌حال، در مناطق روستایی ممکن است مقصدی فاقد نهاد اصلی باشد اما همچنان نقاط ناوبری یا نشانگرهای مکانی داشته باشد.
containingPlaces نشان‌دهنده والدین دربرگیرنده (اجداد) است: containingPlaces زمانی پر می‌شود که مکان اصلی ازنظر فیزیکی در ساختارهای فضایی بزرگ‌تر قرار داشته باشد. برای مکان‌های دقیق‌تر مانند زیرمجموعه، می‌تواند همه سطوح بالاتر را در سلسله‌مراتب فهرست کند. این می‌تواند شامل بخش‌های محصور ساختمان، BUILDING، و محوطه دانشگاه یا مجتمع مسکونی GROUNDS باشد. اگر مقصد ساختمان مستقل یا سنجاق مجزایی باشد، containingPlaces ممکن است خالی باشد.
subDestinations نشان‌دهنده فرزندان (نوادگان) موجود است: subDestinations زمانی پر می‌شود که مقصد ازنظر فیزیکی حاوی مکان‌های دقیق‌تری باشد و می‌تواند شامل انواع مختلف ساختار نوادگان باشد—مانند BUILDINGهای فرزند در محوطه دانشگاه یا زمین‌ها، یا واحدهای داخلی، بخش‌ها، و فروشگاه‌های داخل ساختمان.

`entrances`

اشیاء موجود در آرایه entrances[] دارای فیلدهای زیر هستند:

displayName

شیء LocalizedText حاوی نامی قابل‌خواندن برای انسان برای ورودی (برای مثال، "South Bernardo Avenue" یا "5th Avenue")، درصورت دردسترس بودن.
location

یک جفت مختصات عرض جغرافیایی/طول جغرافیایی که مکان نقطه ورود و خروج به یک مکان را تعریف می‌کند.
entrance_tags[]

آرایه‌ای از برچسب‌های ورودی که ویژگی‌های ورودی را توصیف می‌کند. مقدار زیر پشتیبانی می‌شود:
- "PREFERRED"
نشان می‌دهد این ورودی احتمالاً دسترسی فیزیکی به مکان برگردانده‌شده فراهم می‌کند. یک مکان می‌تواند چندین ورودی ترجیحی داشته باشد. اگر ورودی‌ای این برچسب را نداشته باشد، یعنی ورودی ازنظر فیزیکی در همان ساختمان است اما لزوماً دسترسی به آن مکان را فراهم نمی‌کند.

برای مثال، اگر مکان برگردانده‌شده رستورانی در یک مرکز خرید نواری باشد، "PREFERRED" ورودی‌ها آن‌هایی خواهند بود که به خود رستوران منتهی می‌شوند، درحالی‌که سایر ورودی‌های برگردانده‌شده ورودی‌های دیگر ساختمان خواهند بود، مانند ورودی‌های رستوران‌های دیگر در مرکز خرید نواری.

اگر مکان برگردانده‌شده خودش ساختمان باشد، ورودی‌های "PREFERRED" ورودی‌هایی خواهند بود که به بخش «اصلی» ساختمان منتهی می‌شوند. برای مثال، در یک مرکز خرید، ورودی‌های "PREFERRED" ورودی‌هایی هستند که دسترسی به لابی اصلی را فراهم می‌کنند، اما اگر ورودی فقط دسترسی به فروشگاهی در کنار ساختمان را فراهم کند، ورودی "PREFERRED" نخواهد بود.
‫streetViewThumbnail و streetViewAnnotation

پارامترهای Street View Static API، که به شما امکان می‌دهد تصاویر مربوط به این مکان‌ها را نمایش دهید. درباره این فیلدها بیشتر بدانید.

`structureType`

نوع ساختاری که این مکان نشان می‌دهد.

POINT

مکان نقطه‌ای.
SECTION

زیربخش ساختمان.
BUILDING

ساختمان.
GROUNDS

منطقه‌ای بزرگ که معمولاً شامل چندین ساختمان است، مانند پردیس دانشگاه، مجتمع آپارتمانی، یا مرکز خرید.

`navigationPoints`

فیلد navigationPoints در پاسخ «زمین‌کدیابی» حاوی فهرستی از نقطه‌هایی است که برای پیمایش به مکان مفید هستند. به‌طور مشخص، این نقاط باید به‌عنوان نقطه شروع یا پایان هنگام مسیریابی در شبکه جاده‌ای از یا به آن مکان استفاده شوند.

هر نقطه پیمایش حاوی مقادیر زیر است:

navigationPointToken کدی است که حاوی اطلاعات زمینه‌ای در فیلد navigationPoints است. می‌توانید این کد را به میاناهای برنامه‌سازی کاربردی مسیریابی و ناوبری ارسال کنید تا مسیریابی و تجربه راننده را در برنامه‌تان بهبود دهید. برای اطلاعات بیشتر، به مسیریابی بااستفاده از کدهای نقطه ناوبری مراجعه کنید.
location حاوی مقدار عرض جغرافیایی و طول جغرافیایی نقطه پیمایش است. این مکان همیشه بسیار نزدیک به شبکه جاده‌ای خواهد بود و نقطه توقف یا شروع ایده‌آلی برای ناوبری به و از یک مکان را نشان می‌دهد. این نقطه به‌طور عمدی کمی از خط مرکزی جاده فاصله دارد تا طرفی از جاده را که مکان در آن قرار دارد به‌وضوح مشخص کند.
travelModes فهرستی از حالت‌های سفر است که نقطه ناوبری از آن‌ها قابل‌دسترسی است:
- "DRIVE" حالت سفر مربوط به مسیرهای رانندگی است.
- "WALK" حالت سفر مربوط به مسیرهای پیاده‌روی است.
usages فهرستی از کاربردهای پشتیبانی‌شده توسط نقطه پیمایش است. موارد استفاده می‌تواند این‌ها باشد:
- "DROPOFF"
- "PICKUP"
- "PARKING"

برای سوار کردن و پیاده کردن، از نقطه پیمایشی استفاده کنید که حالت سفر آن DRIVE و کاربرد آن PICKUP یا DROPOFF باشد. اگر نقاط سوار کردن یا پیاده کردن دردسترس نیست، از نقطه ناوبری رانندگی بالا استفاده کنید.

streetViewThumbnail و entranceAnnotation پارامترهایی برای Street View Static API ارائه می‌دهند که به شما امکان می‌دهد تصاویر مربوط به این مکان‌ها را نمایش دهید. درباره این فیلدها بیشتر بدانید.

altitude_meters حاوی ارتفاع نقطه پیمایش به متر نسبت به بیضوی WGS-84 است. در مواردی که بخش‌های جاده به‌صورت عمودی روی هم قرار گرفته‌اند، از فیلد altitude_meters استفاده کنید تا بهترین بخش جاده را برای سیستم خود انتخاب کنید تا به آن پیمایش کند.

`landmarks`

آرایه‌ای از اشیاء Landmark که نشان‌دهنده مکان‌های قابل‌توجه در اطراف است و به کاربران کمک می‌کند جهت‌یابی کنند و مقصد را هنگام رسیدن پیدا کنند. این قابلیت جایگزین ویژگی قدیمی «توصیف‌کننده‌های نشانی» نسخه ۳ می‌شود و آن را گسترش می‌دهد.

هر شیء Landmark حاوی موارد زیر است:

‫place: شیء PlaceView که مکان دیدنی را توصیف می‌کند، ازجمله displayName، placeId، location، types، و displayPolygon آن.
‫relationalDescription: رشته LocalizedText بومی‌سازی‌شده و قابل‌خواندن برای انسان که رابطه فضایی بین مقصد و مکان دیدنی را توصیف می‌کند (برای مثال، "Near Starbird Chicken"، "Across from Central Park"، یا "Around the corner from the Empire State Building").
‫straightLineDistanceMeters: فاصله خط مستقیم (فاصله هوایی) برحسب متر از مکان دیدنی تا مقصد.
travelDistanceMeters: مسافت تخمینی سفر برحسب متر درطول جاده یا شبکه عابر پیاده بین مکان دیدنی و مقصد.
tags: برچسب‌های زمینه‌ای که نقش فضایی مکان دیدنی را نسبت‌به مقصد نشان می‌دهد:
- "ARRIVAL": مکان دیدنی محله‌ای که بلافاصله در مجاورت یا روبه‌روی مقصد قرار دارد (معمولاً در فاصله ۵۰ تا ۱۰۰ متری)، بهترین گزینه برای راهنمایی در آخرین مایل رسیدن به مقصد.
- "ADDRESS": نشانگر مکانی برجسته محلی در محله اطراف (معمولاً در فاصله ۱۰۰ تا ۵۰۰ متری)، بهترین گزینه برای جهت‌یابی پیش‌از سفر و تأیید نشانی.
- نشان‌ها می‌توانند هر دو برچسب را داشته باشند اگر هم در محل برجسته باشند و هم در مجاورت فوری قرار داشته باشند.

هر نشانگر حاوی فیلدهای زیر است:

place PlaceView شیء است که این نشانگر مکانی را نشان می‌دهد.
relationalDescription شرحی قابل‌خواندن برای انسان است که نشان می‌دهد مقصد چه ارتباطی با نشانگر مکانی دارد، مثلاً «نزدیک ساختمان امپایر استیت» یا «روبه‌روی کاخ سفید».
tags[] آرایه‌ای از برچسب‌ها است که نحوه استفاده از نشانگر مکانی را در بافت مقصد شرح می‌دهد:
- ‫"ADDRESS": مکانی که در منطقه برجسته است و می‌توان از آن برای شناسایی مکان کلی مقصد استفاده کرد.
- "ARRIVAL": مکانی که می‌تواند برای کمک به رسیدن به مقصد استفاده شود، برای ناوبری در نزدیکی مقصد مفید است.
straightLineDistanceMeters فاصله مستقیم از این نشانگر مکانی تا مقصد به متر است.
travelDistanceMeters فاصله پیاده‌روی از این مکان دیدنی تا مقصد به متر است.

`arrivalSummary`

اطلاعات آماری با بهره‌گیری از هوش مصنوعی برای کمک به رسیدن به مقصد. خلاصه‌های با پشتیبانی هوش مصنوعی را ببینید.

`parkingOptions`

اطلاعات دقیق پارکینگ.

قالب پاسخ

SearchDestinations SearchDestinationsResponse را در قالب JSON زیر برمی‌گرداند:

{
  "destinations": [
    {
      "primary": {
        "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w",
        "displayName": {
          "text": "Arby's",
          "languageCode": "en"
        },
        "primaryType": "fast_food_restaurant",
        "types": [
          "fast_food_restaurant",
          "sandwich_shop",
          "deli",
          "meal_takeaway",
          "food_delivery",
          "american_restaurant",
          "restaurant",
          "food_store",
          "store",
          "food",
          "point_of_interest",
          "establishment"
        ],
        "formattedAddress": "Arby's, 601 S Bernardo Ave, Sunnyvale, CA 94087, USA",
        "postalAddress": {
          "regionCode": "US",
          "languageCode": "en",
          "postalCode": "94087",
          "administrativeArea": "CA",
          "locality": "Sunnyvale",
          "addressLines": [
            "601 S Bernardo Ave"
          ]
        },
        "structureType": "BUILDING",
        "location": {
          "latitude": 37.3734545,
          "longitude": -122.05693269999998
        },
        "displayPolygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -122.056930138027,
                37.3735253692531
              ],
              [
                -122.056960139391,
                37.3735372663597
              ],
              [
                -122.056994129366,
                37.3734828786847
              ],
              [
                -122.056969677395,
                37.3734731161089
              ],
              [
                -122.057061762447,
                37.3733261309656
              ],
              [
                -122.056979388817,
                37.3732935577128
              ],
              [
                -122.056798860285,
                37.3735818838642
              ],
              [
                -122.056875858081,
                37.3736121235316
              ],
              [
                -122.056930138027,
                37.3735253692531
              ]
            ]
          ]
        }
      },
      "containingPlaces": [
        {
          "place": "places/ChIJYfdAFum2j4ARIcL2tjME3Sw",
          "displayName": {
            "text": "Cherry Chase Shopping Center",
            "languageCode": "en"
          },
          "primaryType": "shopping_mall",
          "types": [
            "shopping_mall",
            "point_of_interest",
            "establishment"
          ],
          "formattedAddress": "Cherry Chase Shopping Center, 663 S Bernardo Ave, Sunnyvale, CA 94087, USA",
          "postalAddress": {
            "regionCode": "US",
            "languageCode": "en",
            "postalCode": "94087-1020",
            "administrativeArea": "CA",
            "locality": "Sunnyvale",
            "addressLines": [
              "663 S Bernardo Ave"
            ]
          },
          "structureType": "GROUNDS",
          "location": {
            "latitude": 37.3731231,
            "longitude": -122.0578211
          },
          "displayPolygon": {
            "type": "Polygon",
            "coordinates": [
              [
                [
                  -122.057112227103,
                  37.3714618008523
                ],
                [
                  -122.057076849821,
                  37.3715743611411
                ],
                [
                  -122.056963607756,
                  37.3719081793948
                ],
                [
                  -122.056865279559,
                  37.3722026053835
                ],
                [
                  -122.056687872374,
                  37.3727258358476
                ],
                [
                  -122.056580005889,
                  37.3730511370747
                ],
                [
                  -122.056498845827,
                  37.3732994782583
                ],
                [
                  -122.056338259713,
                  37.3737878663325
                ],
                [
                  -122.056618678291,
                  37.373887693582
                ],
                [
                  -122.056912102521,
                  37.3740010327191
                ],
                [
                  -122.057532418159,
                  37.3742476426462
                ],
                [
                  -122.057673926626,
                  37.3742441740031
                ],
                [
                  -122.057735663106,
                  37.3742328516943
                ],
                [
                  -122.057766531332,
                  37.3742220604378
                ],
                [
                  -122.057797572967,
                  37.37420520725
                ],
                [
                  -122.057828267759,
                  37.3741852342085
                ],
                [
                  -122.058060299297,
                  37.3740060842535
                ],
                [
                  -122.058199726081,
                  37.3737861673422
                ],
                [
                  -122.05836707267,
                  37.373524542556
                ],
                [
                  -122.058569622393,
                  37.3732018598683
                ],
                [
                  -122.0587638478,
                  37.3728890198039
                ],
                [
                  -122.058934661823,
                  37.3726036257774
                ],
                [
                  -122.059164956851,
                  37.3722498383629
                ],
                [
                  -122.058997784906,
                  37.3721804442035
                ],
                [
                  -122.057936479838,
                  37.3717605636234
                ],
                [
                  -122.057495827092,
                  37.3715860151634
                ],
                [
                  -122.057112227103,
                  37.3714618008523
                ]
              ]
            ]
          }
        }
      ],
      "landmarks": [
        {
          "place": {
            "place": "places/ChIJXXTe7Oi2j4ARoMTA-D6Hjpg",
            "displayName": {
              "text": "Chase Bank",
              "languageCode": "en"
            },
            "primaryType": "bank",
            "types": [
              "bank",
              "atm",
              "finance",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Chase Bank, 1234 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1234 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.373579,
              "longitude": -122.05752700000001
            }
          },
          "relationalDescription": {
            "text": "Near Chase Bank",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 61.182193756103516,
          "travelDistanceMeters": 63.075645446777344
        },
        {
          "place": {
            "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14",
            "displayName": {
              "text": "Safeway",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "butcher_shop",
              "florist",
              "deli",
              "supermarket",
              "bakery",
              "food_delivery",
              "market",
              "manufacturer",
              "food_store",
              "store",
              "food",
              "service",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Safeway, 639 S Bernardo Ave, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "639 S Bernardo Ave"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3727912,
              "longitude": -122.0581172
            }
          },
          "relationalDescription": {
            "text": "Around the corner from Safeway",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 158.65606689453125,
          "travelDistanceMeters": 131.1669921875
        },
        {
          "place": {
            "place": "places/ChIJu-PSYui2j4ARNiwOwBApGqk",
            "displayName": {
              "text": "Oil Changers",
              "languageCode": "en"
            },
            "types": [
              "car_repair",
              "service",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Oil Changers, 1240 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1240 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3743054,
              "longitude": -122.0584272
            }
          },
          "relationalDescription": {
            "text": "Down the road from Oil Changers",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL"
          ],
          "straightLineDistanceMeters": 140.52459716796875,
          "travelDistanceMeters": 143.24220275878906
        },
        {
          "place": {
            "place": "places/ChIJKRbl5oG3j4ARwuvPGUmtCj0",
            "displayName": {
              "text": "Apni Mandi Farmers Market Sunnyvale",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "cake_shop",
              "supermarket",
              "asian_grocery_store",
              "indian_restaurant",
              "meal_takeaway",
              "bakery",
              "manufacturer",
              "wholesaler",
              "restaurant",
              "food_store",
              "store",
              "food",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Apni Mandi Farmers Market Sunnyvale, 1111 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1056",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1111 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3737199,
              "longitude": -122.0522958
            }
          },
          "relationalDescription": {
            "text": "Near Apni Mandi Farmers Market Sunnyvale",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 410.37435913085938,
          "travelDistanceMeters": 479.49893188476562
        },
        {
          "place": {
            "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs",
            "displayName": {
              "text": "Starbird Chicken",
              "languageCode": "en"
            },
            "primaryType": "chicken_restaurant",
            "types": [
              "chicken_restaurant",
              "fast_food_restaurant",
              "restaurant",
              "food",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Starbird Chicken, 1241 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1028",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1241 W El Camino Real"
              ]
            },
            "structureType": "BUILDING",
            "location": {
              "latitude": 37.3746764,
              "longitude": -122.05708860000001
            },
            "displayPolygon": {
              "coordinates": [
                [
                  [
                    -122.057003840785,
                    37.3747648209809
                  ],
                  [
                    -122.057136852459,
                    37.3747919153144
                  ],
                  [
                    -122.057205005705,
                    37.3745815131859
                  ],
                  [
                    -122.057071994114,
                    37.3745544186944
                  ],
                  [
                    -122.057003840785,
                    37.3747648209809
                  ]
                ]
              ],
              "type": "Polygon"
            }
          },
          "relationalDescription": {
            "text": "Near Starbird Chicken",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 87.348007202148438,
          "travelDistanceMeters": 214.08084106445312
        }
      ],
      "entrances": [
        {
          "displayName": {
            "text": "South Bernardo Avenue",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.3735328,
            "longitude": -122.05694879999999
          },
          "tags": [
            "PREFERRED"
          ],
          "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
        }
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJeMt61tqvQkARWT2716SDXsASEgljyy_n6LaPgBH9LoGUMNHjbBoSCWPLL-foto-AEf0ugZQw0eNsIhIJhf5y6ei2j4ARz7yBW5KAPI4",
          "location": {
            "latitude": 37.3738659,
            "longitude": -122.05693620000001
          },
          "travelModes": [
            "DRIVE",
            "WALK"
          ],
          "usages": [
            "PARKING"
          ]
        }
      ]
    }
  ]
}

پارامترهای الزامی

یکی از ۳ پارامتر زیر باید در درخواست API باشد، که نشانی، مکان، یا موقعیت مکانی را برای جستجوی مقصد مشخص می‌کند:
- addressQuery - نشانی موردنظر برای جستجو.
- place - شناسه مکان موردنظر برای جستجو.
- locationQuery - مختصات طول و عرض جغرافیایی مکان موردنظر برای جستجو.
FieldMask

با ایجاد کردن ماسک فیلد پاسخ، فهرست فیلدهایی را که باید در پاسخ برگردانده شود مشخص کنید. ماسک فیلد پاسخ را بااستفاده از پارامتر نشانی وب $fields یا fields، یا بااستفاده از سرایند HTTP X-Goog-FieldMask به روش ارسال کنید. برای مثال، درخواست زیر فقط ورودی‌ها، نقاط پیمایش، و شناسه مکان مقصد اصلی را برمی‌گرداند.
```
  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.place" \
    https://geocode.googleapis.com/v4/geocode/destinations
  
```
هیچ فهرست پیش‌فرضی از فیلدهای برگردانده‌شده در پاسخ وجود ندارد. اگر ماسک فیلد را حذف کنید، روش خطا برمی‌گرداند. ماسک فیلد را روی * تنظیم کنید تا همه فیلدها برگردانده شود. برای جزئیات بیشتر، انتخاب فیلدها برای برگرداندن را ببینید.

پارامترهای اختیاری

travelModes

مشخص می‌کند کدام نوع navigationPoints برگردانده شود. نقاط ناوبری برای دیگر حالت‌های سفر فیلتر خواهد شد. اگر travelModes تنظیم نشده باشد، نقاط ناوبری همه حالت‌های سفر می‌تواند برگردانده شود.
languageCode

زبانی که نتایج به آن برگردانده می‌شود.
- فهرست زبان‌های پشتیبانی‌شده را ببینید. Google اغلب زبان‌های پشتیبانی‌شده را به‌روز می‌کند، بنابراین ممکن است این فهرست کامل نباشد.
- اگر languageCode ارائه نشده باشد، API به‌طور پیش‌فرض از زبان محلی و نویسه‌های مکان استفاده می‌کند. اگر کد زبان نامعتبری را مشخص کنید، میانای برنامه‌سازی کاربردی خطای INVALID_ARGUMENT را برمی‌گرداند.
- این API تمام تلاش خود را می‌کند تا نشانی خیابانی ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل‌خواندن باشد. برای دستیابی به این هدف، نشانی‌های خیابان را به زبان محلی برمی‌گرداند و درصورت لزوم، با رعایت زبان ترجیحی، آن‌ها را به نویسه‌ای که برای کاربر خوانا باشد نویسه‌گردانی می‌کند. همه نشانی‌های دیگر به زبان ترجیحی برگردانده می‌شوند. همه مؤلفه‌های نشانی به همان زبانی برگردانده می‌شوند که از مؤلفه اول انتخاب شده است.
- اگر نامی به زبان ترجیحی دردسترس نباشد، API از نزدیک‌ترین مطابقت استفاده می‌کند.
- زبان ترجیحی تأثیر کمی بر مجموعه نتایجی دارد که میانای برنامه‌سازی کاربردی برای برگرداندن انتخاب می‌کند و ترتیبی که در آن برگردانده می‌شوند. زمین‌کدیاب اختصارات را بسته به زبان به‌طور متفاوتی تفسیر می‌کند، مانند اختصارات برای انواع خیابان‌ها، یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند.
regionCode

کد منطقه به‌عنوان مقدار کد CLDR دو نویسه‌ای. مقدار پیش‌فرضی وجود ندارد. بیشتر کدهای CLDR با کدهای ISO 3166-1 یکسان هستند.
هنگام زمین‌کدیابی نشانی، زمین‌کدیابی پیش‌رو، این پارامتر می‌تواند بر نتایج سرویس در منطقه مشخص‌شده تأثیر بگذارد، اما نمی‌تواند آن‌ها را کاملاً محدود کند. هنگام زمین‌کدیابی مکان یا محل، زمین‌کدیابی معکوس یا زمین‌کدیابی محل، می‌توان از این پارامتر برای قالب‌بندی نشانی استفاده کرد. در همه موارد، این پارامتر می‌تواند براساس قانون ذی‌ربط بر نتایج تأثیر بگذارد.
placeFilter

به شما امکان می‌دهد نتایج جستجوی locationQuery را فیلتر کنید تا با الزامات شما مطابقت داشته باشد، مثلاً فقط مقصدهایی را برگرداند که ساختمان هستند یا فقط مقصدهایی را برگرداند که نشانی واضحی دارند.

فیلتر کردن براساس دانه‌بندی ساختاری

فیلتر structureType به شما امکان می‌دهد نوع ساختارهایی را که توسط پُرسمان برگردانده می‌شود مشخص کنید:
- جداسازی ساختمان‌ها: از "structureType": "BUILDING" برای نمایش طرح کلی ساختمان‌ها روی نقشه یا دریافت جزئیات برای یک سازه خاص استفاده کنید.
- درک مجتمع‌ها: از "structureType": "GROUNDS" استفاده کنید تا مطمئن شوید نتیجه اصلی کل محوطه است. این ویژگی هنگام جستجوی مناطق بزرگ‌تر مانند پردیس‌های دانشگاهی یا مراکز خرید مفید است.
- تمرکز بر واحدها/بخش‌ها: از "structureType": "SECTION" برای شناسایی بخش‌های داخل ساختمان استفاده کنید.
اطمینان از مفید بودن نشانی‌ها

همه مکان‌ها نشانی واضحی در سطح خیابان ندارند. فیلتر addressability به شما کمک می‌کند کیفیت نشانی‌ها را در نتایجتان کنترل کنید:
- الزامی کردن نشانی اصلی واضح: برای اطمینان از اینکه نتیجه مقصد اصلی همیشه نام یا نشانی در سطح خیابان داشته باشد، از "addressability": "PRIMARY" استفاده کنید. این ویژگی برای اهداف پیمایش یا نمایش مفید است، جایی که نشانی واضح بسیار مهم است.
- مجاز کردن نشانی‌ها در زیرمقصدها: در مواردی که مکان اصلی ممکن است نشانی نداشته باشد، اما واحدهای درون آن نشانی داشته باشند (مانند آپارتمان‌ها در یک ساختمان)، "addressability": "WEAK" اطمینان حاصل می‌کند که حداقل مکان اصلی یا یکی از زیرمقصدهای آن نشانی داشته باشد.
- هر نتیجه‌ای: اگر وجود نشانی با مورد استفاده شما مرتبط نیست، از "addressability": "ANY" استفاده کنید. این کار زمانی به‌شدت توصیه می‌شود که فقط به ویژگی‌های هندسی مانند طرح کلی ساختمان و نقاط پیمایش نیاز دارید، زیرا دقت این نتایج را بهبود می‌بخشد.
مثال: فیلتر کردن برای ساختمان‌های آدرس‌پذیر
```
curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "PRIMARY"
    }
  },
  "languageCode": "en"
}' \\
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \\
-H "X-Goog-FieldMask: place" \\
https://geocode.googleapis.com/v4/geocode/destinations
```

جستجوی مقصدها با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

درخواست جستجوی مقصدها

جستجوی مقصد براساس نشانی

جستجوی مقصد با شناسه مکان

شناسه‌های مکان پشتیبانی‌شده

استفاده از «تکمیل خودکار» (جدید) با «مقصد جستجو»

جستجوی مقصد براساس مکان

استفاده از OAuth برای درخواست کردن

پاسخ جستجوی مقصدها

primary

addressComponents

containingPlaces

subDestinations

سلسله‌مراتب مقصد و رفتار پاسخ

entrances

structureType

navigationPoints

landmarks

arrivalSummary

parkingOptions

قالب پاسخ

پارامترهای الزامی

FieldMask

پارامترهای اختیاری

travelModes

languageCode

regionCode

placeFilter

فیلتر کردن براساس دانه‌بندی ساختاری

اطمینان از مفید بودن نشانی‌ها