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

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

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

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

درخواست جستجوی مقصد، یک درخواست HTTP POST به یک URL به شکل زیر است:

https://geocode.googleapis.com/v4beta/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/v4beta/geocode/destinations

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

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

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

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

نوع پرس و جو	مثال
مختصات طول و عرض جغرافیایی. به جای آن از یک پرس و جوی موقعیت مکانی استفاده کنید.	«۳۷.۴۲۲۱۳۱، -۱۲۲.۰۸۴۸۰۱»
مفاهیم یا محدودیت‌های بسیار زیاد، مانند نام چندین مکان، جاده یا شهر در یک پرس‌وجو	«خیابان مارکت، سانفرانسیسکو، فرودگاه سن خوزه»
عناصر آدرس پستی که در نقشه‌های گوگل نمایش داده نمی‌شوند	«دفتر مرکزی جان اسمیت، خیابان اصلی ۱۲۳» «صندوق پستی ۱۳ سانفرانسیسکو»
نام کسب‌وکارها، زنجیره‌ها یا دسته‌بندی‌ها به همراه مکان‌هایی که این نهادها در آنها در دسترس نیستند	«تسکو نزدیک دالاس، تگزاس»
پرسش‌های مبهم با تفاسیر متعدد	"تحویل شارژر"
نام‌های تاریخی دیگر استفاده نمی‌شوند	«میدلسکس، بریتانیا»
عناصر یا مقاصد غیرمکان‌محور	«چند قایق در بندر ونتورا وجود دارد؟»
نام‌های غیررسمی یا خیالی	"جنگا" "هلتر اسکلتر"
نهادهای سیاسی بزرگ (شهرها، ایالت‌ها، کشورها)	«شهر نیویورک» «کالیفرنیا» «آمریکا»
مسیرهای بدون آدرس مشخص	«خیابان اول، نیویورک، نیویورک» «آی-۹۵»

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

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

روش جستجوی مقصدها با شناسه‌های مکانی که نشان‌دهنده‌ی مقاصد خاص و قابل پیمایش هستند، بهترین عملکرد را دارد.

شناسه‌های مکان برای انواعی مانند establishment ، point_of_interest ، premise ، street_address و subpremise عموماً پشتیبانی می‌شوند.

شناسه‌های مکانی که مکان‌های مجزا را نشان نمی‌دهند، مانند آن‌هایی که از محدوده‌های آدرس استنباط می‌شوند (مثلاً «خیابان اصلی ۱۰-۲۰»)، بخش‌هایی از یک مسیر بدون شماره خاص، یا کدهای مثبت پشتیبانی نمی‌شوند .

برای اطمینان از سازگاری هنگام استفاده از Place Autocomplete برای یافتن Place IDها، فیلتر کردن نتایج بر اساس نوع را در نظر بگیرید. می‌توانید از پارامتر includedPrimaryTypes در درخواست‌های Autocomplete خود استفاده کنید تا فقط انواع پشتیبانی‌شده ذکر شده در بالا را شامل شود:

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

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

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

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

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

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

API ژئوکدینگ نسخه ۴ از OAuth 2.0 برای احراز هویت پشتیبانی می‌کند. برای استفاده از OAuth با API ژئوکدینگ، باید به توکن OAuth دامنه صحیح اختصاص داده شود. API ژئوکدینگ از دامنه‌های زیر برای استفاده با متد Destinations پشتیبانی می‌کند:

https://www.googleapis.com/auth/maps-platform.geocode — با تمام متدهای API مربوط به Geocoding قابل استفاده است.

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

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

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

پاسخ «مقاصد جستجو» زمینه‌ای غنی و فرامحلی در مورد مکان ارائه می‌دهد.

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

`primary`

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

`containingPlaces`

نهادهای بزرگ‌تری که مقصد اصلی بخشی از آنها است (برای مثال، یک مرکز خرید شامل یک فروشگاه).

`subDestinations`

مکان‌های خاص‌تر در مقصد اصلی (برای مثال، آپارتمان‌های یک ساختمان).

`entrances`

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

location
یک جفت مختصات طول و عرض جغرافیایی که موقعیت یک نقطه ورود و خروج به یک مکان را مشخص می‌کند.
entrance_tags[]
آرایه‌ای از تگ‌های ورودی که ویژگی‌های ورودی را توصیف می‌کند. مقدار زیر پشتیبانی می‌شود:
- "PREFERRED"
  نشان می‌دهد که این ورودی احتمالاً دسترسی فیزیکی به مکان مورد نظر را فراهم می‌کند. یک مکان می‌تواند چندین ورودی ترجیحی داشته باشد. اگر ورودی این برچسب را نداشته باشد، به این معنی است که ورودی از نظر فیزیکی در همان ساختمان قرار دارد اما لزوماً دسترسی به آن مکان را فراهم نمی‌کند.
  برای مثال، اگر مکان برگردانده شده یک رستوران در یک مرکز خرید باشد، ورودی‌های "PREFERRED" ورودی‌هایی خواهند بود که به خود رستوران منتهی می‌شوند، در حالی که سایر ورودی‌های برگردانده شده، ورودی‌های دیگر ساختمان، مانند ورودی‌های رستوران‌های دیگر در مرکز خرید، خواهند بود.
  اگر مکان مورد نظر خود یک ساختمان باشد، ورودی‌های "PREFERRED" ورودی‌هایی خواهند بود که به قسمت «اصلی» ساختمان منتهی می‌شوند. برای مثال، در یک مرکز خرید، ورودی‌های "PREFERRED" ورودی‌هایی هستند که امکان دسترسی به فضای اصلی سرسرا را فراهم می‌کنند، اما اگر یک ورودی فقط دسترسی به یک فروشگاه در کنار ساختمان را فراهم کند، ورودی "PREFERRED" نخواهد بود.

`structureType`

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

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

`navigationPoints`

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

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

`arrivalSummary`

بینش‌های مبتنی بر هوش مصنوعی برای کمک به ورود. به خلاصه‌های مبتنی بر هوش مصنوعی مراجعه کنید.

`landmarks`

مکان‌های نزدیک و قابل توجه برای کمک به کاربران در درک محیط اطراف مقصد.

قالب پاسخ

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": [
        {
          "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 - مختصات طول و عرض جغرافیایی مکانی که باید جستجو شود.
فیلد ماسک
با ایجاد یک ماسک فیلد پاسخ، لیست فیلدهایی را که باید در پاسخ بازگردانده شوند، مشخص کنید. ماسک فیلد پاسخ را با استفاده از پارامتر URL $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/v4beta/geocode/destinations
  
```
هیچ لیست پیش‌فرضی از فیلدهای برگردانده شده در پاسخ وجود ندارد. اگر ماسک فیلد را حذف کنید، متد خطا برمی‌گرداند. برای برگرداندن همه فیلدها، ماسک فیلد را روی * تنظیم کنید. برای جزئیات بیشتر به بخش «انتخاب فیلدها برای برگرداندن» مراجعه کنید.

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

حالت‌های سفر
مشخص می‌کند که کدام نوع از navigationPoints باید بازگردانده شوند. نقاط ناوبری برای سایر حالت‌های سفر فیلتر می‌شوند. اگر travelModes تنظیم نشده باشد، نقاط ناوبری همه حالت‌های سفر می‌توانند بازگردانده شوند.
زبانکد
زبانی که نتایج با آن برگردانده می‌شوند.
- فهرست زبان‌های پشتیبانی‌شده را ببینید. گوگل اغلب زبان‌های پشتیبانی‌شده را به‌روزرسانی می‌کند، بنابراین این فهرست ممکن است جامع نباشد.
- اگر languageCode ارائه نشود، API به طور پیش‌فرض en را در نظر می‌گیرد. اگر کد زبان نامعتبری را مشخص کنید، API خطای INVALID_ARGUMENT را برمی‌گرداند.
- این API تمام تلاش خود را می‌کند تا آدرسی را ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل خواندن باشد. برای دستیابی به این هدف، آدرس‌های خیابان را به زبان محلی برمی‌گرداند و در صورت لزوم با رعایت زبان ترجیحی، آنها را به اسکریپتی که توسط کاربر قابل خواندن باشد، تبدیل می‌کند. تمام آدرس‌های دیگر به زبان ترجیحی برگردانده می‌شوند. اجزای آدرس همگی به همان زبانی برگردانده می‌شوند که از اولین جزء انتخاب شده است.
- اگر نامی در زبان مورد نظر موجود نباشد، API از نزدیکترین مورد منطبق استفاده می‌کند.
- زبان ترجیحی تأثیر کمی بر مجموعه نتایجی که API برای برگرداندن انتخاب می‌کند و ترتیب برگرداندن آنها دارد. کدگذار جغرافیایی بسته به زبان، اختصارات را به طور متفاوتی تفسیر می‌کند، مانند اختصارات مربوط به انواع خیابان یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند.
کد منطقه
کد منطقه به عنوان یک مقدار کد CLDR دو کاراکتری . مقدار پیش‌فرضی وجود ندارد. اکثر کدهای CLDR مشابه کدهای ISO 3166-1 هستند.
هنگام ژئوکدینگ یک آدرس، ژئوکدینگ رو به جلو ، این پارامتر می‌تواند بر نتایج سرویس به منطقه مشخص شده تأثیر بگذارد، اما نمی‌تواند آن را به طور کامل محدود کند. هنگام ژئوکدینگ یک مکان یا یک مکان، ژئوکدینگ معکوس یا ژئوکدینگ مکان ، این پارامتر می‌تواند برای قالب‌بندی آدرس استفاده شود. در همه موارد، این پارامتر می‌تواند بر اساس قانون مربوطه بر نتایج تأثیر بگذارد.
فیلتر مکان
به شما امکان می‌دهد نتایج جستجوی 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/v4beta/geocode/destinations
```

بازخورد

این یک روش آزمایشی از API ژئوکدینگ است. ما از دریافت بازخورد در geocoding-feedback-channel@google.com استقبال می‌کنیم.

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

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

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

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

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

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

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

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

primary

containingPlaces

subDestinations

entrances

structureType

navigationPoints

arrivalSummary

landmarks

قالب پاسخ

پارامترهای مورد نیاز

فیلد ماسک

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

حالت‌های سفر

زبانکد

کد منطقه

فیلتر مکان

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

آدرس‌های مفید را تضمین کنید