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

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

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

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

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

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

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

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

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

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

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

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

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

برای اطمینان از سازگاری، از Autocomplete (جدید) برای یافتن شناسه‌های مکان جهت استفاده با Search Destinations استفاده کنید. هنگام استفاده از Autocomplete (جدید)، باید نتایج را بر اساس نوع با استفاده از پارامتر includedPrimaryTypes فیلتر کنید. شناسه‌های مکان برگردانده شده توسط Autocomplete (جدید) با استفاده از فیلتر پیشنهادی زیر توسط Search Destinations پشتیبانی می‌شوند:

"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 برای ارسال درخواست

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» مراجعه کنید.

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

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

اشیاء PlaceView درون پاسخ Search Destinations (مانند primary ، items در containingPlaces و landmarks ) از فیلدهایی برای نشان دادن نوع مکان استفاده می‌کنند:

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

مقادیر رشته‌ای ممکن برای هر دو types و primaryType از جدول A و جدول B در صفحه Place Types (جدید) گرفته شده‌اند.

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

primary

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

addressComponents

آرایه‌ای شامل اجزای جداگانه‌ای که برای این آدرس قابل استفاده هستند.

هر جزء آدرس معمولاً شامل فیلدهای زیر است:

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

containingPlaces

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

subDestinations

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

entrances

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

  • location

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

  • entrance_tags[]

    آرایه‌ای از تگ‌های ورودی که ویژگی‌های ورودی را توصیف می‌کند. مقدار زیر پشتیبانی می‌شود:

    • "PREFERRED"

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

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

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

  • streetViewThumbnail و streetViewAnnotation

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

structureType

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

  • POINT

    یک موقعیت نقطه‌ای.

  • SECTION

    بخشی فرعی از یک ساختمان.

  • BUILDING

    یک ساختمان.

  • GROUNDS

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

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

هر نقطه ناوبری شامل مقادیر زیر است:

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

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

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

landmarks

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

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": [
        {
          "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/v4/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/v4/geocode/destinations
،
توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

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

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

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

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

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

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

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

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

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

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

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

برای اطمینان از سازگاری، از Autocomplete (جدید) برای یافتن شناسه‌های مکان جهت استفاده با Search Destinations استفاده کنید. هنگام استفاده از Autocomplete (جدید)، باید نتایج را بر اساس نوع با استفاده از پارامتر includedPrimaryTypes فیلتر کنید. شناسه‌های مکان برگردانده شده توسط Autocomplete (جدید) با استفاده از فیلتر پیشنهادی زیر توسط Search Destinations پشتیبانی می‌شوند:

"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 برای ارسال درخواست

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» مراجعه کنید.

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

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

اشیاء PlaceView درون پاسخ Search Destinations (مانند primary ، items در containingPlaces و landmarks ) از فیلدهایی برای نشان دادن نوع مکان استفاده می‌کنند:

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

مقادیر رشته‌ای ممکن برای هر دو types و primaryType از جدول A و جدول B در صفحه Place Types (جدید) گرفته شده‌اند.

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

primary

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

addressComponents

آرایه‌ای شامل اجزای جداگانه‌ای که برای این آدرس قابل استفاده هستند.

هر جزء آدرس معمولاً شامل فیلدهای زیر است:

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

containingPlaces

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

subDestinations

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

entrances

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

  • location

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

  • entrance_tags[]

    آرایه‌ای از تگ‌های ورودی که ویژگی‌های ورودی را توصیف می‌کند. مقدار زیر پشتیبانی می‌شود:

    • "PREFERRED"

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

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

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

  • streetViewThumbnail و streetViewAnnotation

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

structureType

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

  • POINT

    یک موقعیت نقطه‌ای.

  • SECTION

    بخشی فرعی از یک ساختمان.

  • BUILDING

    یک ساختمان.

  • GROUNDS

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

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

هر نقطه ناوبری شامل مقادیر زیر است:

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

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

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

landmarks

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

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": [
        {
          "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/v4/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" استفاده کنید. این گزینه زمانی که فقط به ویژگی‌های هندسی مانند خطوط بیرونی ساختمان و نقاط ناوبری نیاز دارید، اکیداً توصیه می‌شود، زیرا دقت این نتایج را بهبود می‌بخشد.
    Example: Filtering for Addressable Buildings 
    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
،
European Economic Area (EEA) developers

A Destination refers to a specific location or place that a user intends to reach or navigate towards. A Destination also includes a collection of information related to the location or place, such as navigation points, landmarks, entrances, and building outlines.

The SearchDestinations method of the Geocoding API lets you retrieve detailed information about various destinations based on different input criteria, such as an address, place ID, or latitude and longitude coordinates.

Search destinations request

A search destinations request is an HTTP POST request to a URL in the form:

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

Pass all parameters in the JSON request body or in headers as part of the POST request. For example:

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

You can specify the location to search for a destination in one of 3 ways:

  • آدرس
  • Place ID
  • Latitude and longitude coordinates

Search for a destination by address

You can specify the address as an unstructured string. Address geocoding does not resolve latitude and longitude coordinates, or other unstructured strings that don't represent an address. Requests using such strings are not supported and may lead to error responses or unspecified behavior. Examples of unsupported queries include the following:

Query type مثال
Latitude and longitude coordinates. Use a location query instead. "37.422131,-122.084801"
Too many concepts or constraints, such as the names of multiple places, roads, or cities in a single query "Market Street San Francisco San Jose Airport"
Postal address elements not represented on Google Maps "C/O John Smith 123 Main Street"
"PO Box 13 San Francisco"
Names of businesses, chains, or categories combined with locations where these entities are not available "Tesco near Dallas, Texas"
Ambiguous queries with multiple interpretations "Charger drop-off"
Historical names no longer in use "Middlesex United Kingdom"
Non-geospatial elements or intent "How many boats are in Ventura Harbor?"
Unofficial or vanity names "The Jenga"
"The Helter Skelter"
Large political entities (Cities, States, Countries) "New York City"
"California"
"USA"
Routes without specific addresses "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

or as a 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

You typically use the postalAddress format when processing address components captured in an HTML form.

Search for a destination by place ID

You can retrieve a destination by providing a place ID :

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

Supported Place IDs

The Search Destinations method works best with Place IDs that represent specific, navigable destinations. Place IDs for types such as establishment , point_of_interest , premise , street_address , and subpremise are generally supported. Place IDs that don't represent discrete locations, such as those inferred from address ranges (for example, "10-20 Main St"), sections of a route without a specific number, or plus codes are not supported. Place IDs for results that are too large in area (for example, "Pacific Ocean") are also not supported.

Use Autocomplete (New) with Search Destinations

To ensure compatibility, use Autocomplete (New) to find Place IDs for use with Search Destinations. When using Autocomplete (New), you should filter results by type using the includedPrimaryTypes parameter. Place IDs returned by Autocomplete (New) using the following recommended filter are supported by Search Destinations:

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

Additionally, you shouldn't set the include_pure_service_area_businesses flag to true in your Autocomplete (New) request.

Search for a destination by location

You can search for a destination by providing latitude and longitude coordinates:

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

Use OAuth to make a request

Geocoding API v4 supports OAuth 2.0 for authentication. To use OAuth with the Geocoding API, the OAuth token must be assigned the correct scope. Geocoding API supports the following scopes for use with the Destinations method:

  • https://www.googleapis.com/auth/maps-platform.geocode — Use with all Geocoding API methods.

Also, you can use the general https://www.googleapis.com/auth/cloud-platform scope for all Geocoding API methods. That scope is useful during development, but not production, because it is a general scope that allows access to all methods.

For more information and examples, see Use OAuth .

Search destinations response

The Search Destinations response provides rich, hyperlocal context about the location.

The PlaceView objects within the Search Destinations response (such as primary , items in containingPlaces , and landmarks ) use fields to indicate the place type:

  • types : An array of strings indicating the type(s) of the place.
  • primaryType : A string indicating the primary type of the place.

The possible string values for both types and primaryType are drawn from Table A and Table B on the Place Types (New) page.

This section describes the key response fields. For full details on all response fields, see the API Reference .

primary

The main place identified by the query in the request.

addressComponents

An array containing the separate components applicable to this address.

Each address component typically contains the following fields:

  • types[] is an array indicating the type of the address component. See the list of supported types .
  • longText is the full text description or name of the address component as returned by the Geocoder.
  • shortText is an abbreviated textual name for the address component, if available. For example, an address component for the state of Alaska might have a longText of "Alaska" and a shortText of "AK" using the two-letter postal abbreviation.
  • languageCode is the language used to format this component, in CLDR notation.

containingPlaces

Larger entities that the primary destination is part of (for example, a mall containing a store).

subDestinations

More specific locations within the primary destination (for example, apartments in a building).

entrances

The objects in the entrances[] array have the following fields:

  • location

    A single latitude/longitude coordinate pair that defines the location of an entry and exit point into a place.

  • entrance_tags[]

    An array of entrance tags that describes characteristics of the entrance. The following value is supported:

    • "PREFERRED"

    Indicates this entrance likely provides physical access to the returned place. A place can have multiple preferred entrances. If an entrance does not have this tag, it means the entrance is physically on the same building but does not necessarily provide access to the place.

    For example, if the returned place is a restaurant in a strip mall, the "PREFERRED" entrances will be the ones that lead into the restaurant itself, while the other returned entrances will be other entrances for the building, such as entrances into other restaurants in the strip mall.

    If the returned place is a building itself, the "PREFERRED" entrances will be the ones that lead into the "main" part of the building. For example, in a shopping center the "PREFERRED" entrances will be the ones that allow access to the main foyer area, but if an entrance only provides access to a store on the side of the building, it won't be a "PREFERRED" entrance.

  • streetViewThumbnail and streetViewAnnotation

    Parameters for the Street View Static API , allowing you to display relevant imagery for these locations. Learn more about these fields .

structureType

The type of structure that this place represents.

  • POINT

    A point location.

  • SECTION

    A subsection of a building.

  • BUILDING

    A building.

  • GROUNDS

    A large area that typically contains multiple buildings, such as a university campus, an apartment complex, or a shopping mall.

The navigationPoints field within the Geocoding response contains a list of points that are useful for navigating to the place. Specifically, they should be used either as the starting or ending points when routing on a road network from or to the place.

Each navigation point contains the following values:

  • navigationPointToken is a token containing the contextual information in the navigationPoints field. You can send this token to routing and navigation APIs to improve routing and river experience in your app. See Route using navigation point tokens for more information.
  • location contains the latitude, longitude value of the navigation point. This location will always be very close to the road network and represents an ideal stopping or starting point for navigating to and from a place. The point is intentionally slightly offset from the road's centerline to clearly mark the side of the road where the place is located.
  • travelModes is a list of travel modes that the navigation point is accessible from:
    • "DRIVE" is the travel mode corresponding to driving directions.
    • "WALK" is the travel mode corresponding to walking directions.
  • usages is a list of usages supported by the navigation point. Usages can be:
    • "DROPOFF"
    • "PICKUP"
    • "PARKING"

For pickups and drop-offs, use the navigation point where travel mode is DRIVE and usage is PICKUP or DROPOFF . If pickup or dropoff points are not available, use the top driving navigation point.

  • altitude_meters contains the altitude of the navigation point in meters relative to the WGS-84 ellipsoid . In instances where there are vertically stacked road segments, use the altitude_meters field to pick the best road segment for your system to navigate to.

landmarks

Notable nearby places to help users understand the destination's surroundings.

arrivalSummary

AI-powered insights to assist with arrival. See AI-powered summaries .

parkingOptions

Detailed parking information.

Response format

SearchDestinations returns a SearchDestinationsResponse of the following JSON form:

{
  "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"
          ]
        }
      ]
    }
  ]
}

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

  • One of the following 3 parameters must be in the API request, which specifies the address, place, or location to search for a destination:
    • addressQuery - the address to search for.
    • place - the place ID of the place to search for.
    • locationQuery - the latitude and longitude coordinates of the location to search for.

  • FieldMask

    Specify the list of fields to return in the response by creating a response field mask . Pass the response field mask to the method by using the URL parameter $fields or fields , or by using the HTTP header X-Goog-FieldMask . For example, the below request will return only the entrances, navigation points, and place ID of the primary destination.

      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

    There is no default list of returned fields in the response. If you omit the field mask, the method returns an error. Set the field mask to * in order to return all fields. See Choose fields to return for more details.

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

  • travelModes

    Specifies which types of navigationPoints to return. Navigation points for other travel modes will be filtered out. If travelModes is unset, navigation points of all travel modes can be returned.

  • languageCode

    The language in which to return results.

    • See the list of supported languages . Google often updates the supported languages, so this list may not be exhaustive.
    • If languageCode is not supplied, the API defaults to en . If you specify an invalid language code, the API returns an INVALID_ARGUMENT error.
    • The API does its best to provide a street address that is readable for both the user and locals. To achieve that goal, it returns street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component.
    • If a name is not available in the preferred language, the API uses the closest match.
    • The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another.

  • regionCode

    The region code as a two-character CLDR code value. There is no default value. Most CLDR codes are identical to ISO 3166-1 codes.

    When geocoding an address, forward geocoding , this parameter can influence, but not fully restrict, results from the service to the specified region. When geocoding a location or a place, reverse geocoding or place geocoding , this parameter can be used to format the address. In all cases, this parameter can affect results based on applicable law.

  • placeFilter

    Lets you filter the results of a locationQuery search to meet your requirements, such as returning only destinations that are buildings or only destinations that have clear addresses.

    Filter by structural granularity

    The structureType filter lets you specify the kind of structures that are returned by the query:

    • Isolating Buildings : Use "structureType": "BUILDING" to show building outlines on a map or get details for a specific structure.
    • Understanding Complexes : Use "structureType": "GROUNDS" to ensure the primary result is the overall grounds. This is useful when querying for larger areas like university campuses or shopping malls.
    • Focusing on Units/Sections : Use "structureType": "SECTION" to identify sections within a building.

    Ensure useful addresses

    Not all places have clear street-level addresses. The addressability filter helps you control the quality of addresses in your results:

    • Require a Clear Primary Address : To ensure the main destination result always has a street-level address or name, use "addressability": "PRIMARY" . This is useful for navigation or display purposes where a clear address is crucial.
    • Allow Addresses in Sub-Destinations : In cases where the primary place might not have an address, but units within it do (such as apartments in a building), "addressability": "WEAK" ensures that at least the primary place or one of its sub-destinations has an address.
    • Any Result : If address presence isn't relevant to your use case, use "addressability": "ANY" . This is highly recommended when you only need geometric attributes like building outlines and navigation points, as it improves the accuracy of these results.
    Example: Filtering for Addressable Buildings 
    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
،
European Economic Area (EEA) developers

A Destination refers to a specific location or place that a user intends to reach or navigate towards. A Destination also includes a collection of information related to the location or place, such as navigation points, landmarks, entrances, and building outlines.

The SearchDestinations method of the Geocoding API lets you retrieve detailed information about various destinations based on different input criteria, such as an address, place ID, or latitude and longitude coordinates.

Search destinations request

A search destinations request is an HTTP POST request to a URL in the form:

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

Pass all parameters in the JSON request body or in headers as part of the POST request. For example:

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

You can specify the location to search for a destination in one of 3 ways:

  • آدرس
  • Place ID
  • Latitude and longitude coordinates

Search for a destination by address

You can specify the address as an unstructured string. Address geocoding does not resolve latitude and longitude coordinates, or other unstructured strings that don't represent an address. Requests using such strings are not supported and may lead to error responses or unspecified behavior. Examples of unsupported queries include the following:

Query type مثال
Latitude and longitude coordinates. Use a location query instead. "37.422131,-122.084801"
Too many concepts or constraints, such as the names of multiple places, roads, or cities in a single query "Market Street San Francisco San Jose Airport"
Postal address elements not represented on Google Maps "C/O John Smith 123 Main Street"
"PO Box 13 San Francisco"
Names of businesses, chains, or categories combined with locations where these entities are not available "Tesco near Dallas, Texas"
Ambiguous queries with multiple interpretations "Charger drop-off"
Historical names no longer in use "Middlesex United Kingdom"
Non-geospatial elements or intent "How many boats are in Ventura Harbor?"
Unofficial or vanity names "The Jenga"
"The Helter Skelter"
Large political entities (Cities, States, Countries) "New York City"
"California"
"USA"
Routes without specific addresses "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

or as a 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

You typically use the postalAddress format when processing address components captured in an HTML form.

Search for a destination by place ID

You can retrieve a destination by providing a place ID :

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

Supported Place IDs

The Search Destinations method works best with Place IDs that represent specific, navigable destinations. Place IDs for types such as establishment , point_of_interest , premise , street_address , and subpremise are generally supported. Place IDs that don't represent discrete locations, such as those inferred from address ranges (for example, "10-20 Main St"), sections of a route without a specific number, or plus codes are not supported. Place IDs for results that are too large in area (for example, "Pacific Ocean") are also not supported.

Use Autocomplete (New) with Search Destinations

To ensure compatibility, use Autocomplete (New) to find Place IDs for use with Search Destinations. When using Autocomplete (New), you should filter results by type using the includedPrimaryTypes parameter. Place IDs returned by Autocomplete (New) using the following recommended filter are supported by Search Destinations:

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

Additionally, you shouldn't set the include_pure_service_area_businesses flag to true in your Autocomplete (New) request.

Search for a destination by location

You can search for a destination by providing latitude and longitude coordinates:

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

Use OAuth to make a request

Geocoding API v4 supports OAuth 2.0 for authentication. To use OAuth with the Geocoding API, the OAuth token must be assigned the correct scope. Geocoding API supports the following scopes for use with the Destinations method:

  • https://www.googleapis.com/auth/maps-platform.geocode — Use with all Geocoding API methods.

Also, you can use the general https://www.googleapis.com/auth/cloud-platform scope for all Geocoding API methods. That scope is useful during development, but not production, because it is a general scope that allows access to all methods.

For more information and examples, see Use OAuth .

Search destinations response

The Search Destinations response provides rich, hyperlocal context about the location.

The PlaceView objects within the Search Destinations response (such as primary , items in containingPlaces , and landmarks ) use fields to indicate the place type:

  • types : An array of strings indicating the type(s) of the place.
  • primaryType : A string indicating the primary type of the place.

The possible string values for both types and primaryType are drawn from Table A and Table B on the Place Types (New) page.

This section describes the key response fields. For full details on all response fields, see the API Reference .

primary

The main place identified by the query in the request.

addressComponents

An array containing the separate components applicable to this address.

Each address component typically contains the following fields:

  • types[] is an array indicating the type of the address component. See the list of supported types .
  • longText is the full text description or name of the address component as returned by the Geocoder.
  • shortText is an abbreviated textual name for the address component, if available. For example, an address component for the state of Alaska might have a longText of "Alaska" and a shortText of "AK" using the two-letter postal abbreviation.
  • languageCode is the language used to format this component, in CLDR notation.

containingPlaces

Larger entities that the primary destination is part of (for example, a mall containing a store).

subDestinations

More specific locations within the primary destination (for example, apartments in a building).

entrances

The objects in the entrances[] array have the following fields:

  • location

    A single latitude/longitude coordinate pair that defines the location of an entry and exit point into a place.

  • entrance_tags[]

    An array of entrance tags that describes characteristics of the entrance. The following value is supported:

    • "PREFERRED"

    Indicates this entrance likely provides physical access to the returned place. A place can have multiple preferred entrances. If an entrance does not have this tag, it means the entrance is physically on the same building but does not necessarily provide access to the place.

    For example, if the returned place is a restaurant in a strip mall, the "PREFERRED" entrances will be the ones that lead into the restaurant itself, while the other returned entrances will be other entrances for the building, such as entrances into other restaurants in the strip mall.

    If the returned place is a building itself, the "PREFERRED" entrances will be the ones that lead into the "main" part of the building. For example, in a shopping center the "PREFERRED" entrances will be the ones that allow access to the main foyer area, but if an entrance only provides access to a store on the side of the building, it won't be a "PREFERRED" entrance.

  • streetViewThumbnail and streetViewAnnotation

    Parameters for the Street View Static API , allowing you to display relevant imagery for these locations. Learn more about these fields .

structureType

The type of structure that this place represents.

  • POINT

    A point location.

  • SECTION

    A subsection of a building.

  • BUILDING

    A building.

  • GROUNDS

    A large area that typically contains multiple buildings, such as a university campus, an apartment complex, or a shopping mall.

The navigationPoints field within the Geocoding response contains a list of points that are useful for navigating to the place. Specifically, they should be used either as the starting or ending points when routing on a road network from or to the place.

Each navigation point contains the following values:

  • navigationPointToken is a token containing the contextual information in the navigationPoints field. You can send this token to routing and navigation APIs to improve routing and river experience in your app. See Route using navigation point tokens for more information.
  • location contains the latitude, longitude value of the navigation point. This location will always be very close to the road network and represents an ideal stopping or starting point for navigating to and from a place. The point is intentionally slightly offset from the road's centerline to clearly mark the side of the road where the place is located.
  • travelModes is a list of travel modes that the navigation point is accessible from:
    • "DRIVE" is the travel mode corresponding to driving directions.
    • "WALK" is the travel mode corresponding to walking directions.
  • usages is a list of usages supported by the navigation point. Usages can be:
    • "DROPOFF"
    • "PICKUP"
    • "PARKING"

For pickups and drop-offs, use the navigation point where travel mode is DRIVE and usage is PICKUP or DROPOFF . If pickup or dropoff points are not available, use the top driving navigation point.

  • altitude_meters contains the altitude of the navigation point in meters relative to the WGS-84 ellipsoid . In instances where there are vertically stacked road segments, use the altitude_meters field to pick the best road segment for your system to navigate to.

landmarks

Notable nearby places to help users understand the destination's surroundings.

arrivalSummary

AI-powered insights to assist with arrival. See AI-powered summaries .

parkingOptions

Detailed parking information.

Response format

SearchDestinations returns a SearchDestinationsResponse of the following JSON form:

{
  "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"
          ]
        }
      ]
    }
  ]
}

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

  • One of the following 3 parameters must be in the API request, which specifies the address, place, or location to search for a destination:
    • addressQuery - the address to search for.
    • place - the place ID of the place to search for.
    • locationQuery - the latitude and longitude coordinates of the location to search for.

  • FieldMask

    Specify the list of fields to return in the response by creating a response field mask . Pass the response field mask to the method by using the URL parameter $fields or fields , or by using the HTTP header X-Goog-FieldMask . For example, the below request will return only the entrances, navigation points, and place ID of the primary destination.

      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

    There is no default list of returned fields in the response. If you omit the field mask, the method returns an error. Set the field mask to * in order to return all fields. See Choose fields to return for more details.

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

  • travelModes

    Specifies which types of navigationPoints to return. Navigation points for other travel modes will be filtered out. If travelModes is unset, navigation points of all travel modes can be returned.

  • languageCode

    The language in which to return results.

    • See the list of supported languages . Google often updates the supported languages, so this list may not be exhaustive.
    • If languageCode is not supplied, the API defaults to en . If you specify an invalid language code, the API returns an INVALID_ARGUMENT error.
    • The API does its best to provide a street address that is readable for both the user and locals. To achieve that goal, it returns street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component.
    • If a name is not available in the preferred language, the API uses the closest match.
    • The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another.

  • regionCode

    The region code as a two-character CLDR code value. There is no default value. Most CLDR codes are identical to ISO 3166-1 codes.

    When geocoding an address, forward geocoding , this parameter can influence, but not fully restrict, results from the service to the specified region. When geocoding a location or a place, reverse geocoding or place geocoding , this parameter can be used to format the address. In all cases, this parameter can affect results based on applicable law.

  • placeFilter

    Lets you filter the results of a locationQuery search to meet your requirements, such as returning only destinations that are buildings or only destinations that have clear addresses.

    Filter by structural granularity

    The structureType filter lets you specify the kind of structures that are returned by the query:

    • Isolating Buildings : Use "structureType": "BUILDING" to show building outlines on a map or get details for a specific structure.
    • Understanding Complexes : Use "structureType": "GROUNDS" to ensure the primary result is the overall grounds. This is useful when querying for larger areas like university campuses or shopping malls.
    • Focusing on Units/Sections : Use "structureType": "SECTION" to identify sections within a building.

    Ensure useful addresses

    Not all places have clear street-level addresses. The addressability filter helps you control the quality of addresses in your results:

    • Require a Clear Primary Address : To ensure the main destination result always has a street-level address or name, use "addressability": "PRIMARY" . This is useful for navigation or display purposes where a clear address is crucial.
    • Allow Addresses in Sub-Destinations : In cases where the primary place might not have an address, but units within it do (such as apartments in a building), "addressability": "WEAK" ensures that at least the primary place or one of its sub-destinations has an address.
    • Any Result : If address presence isn't relevant to your use case, use "addressability": "ANY" . This is highly recommended when you only need geometric attributes like building outlines and navigation points, as it improves the accuracy of these results.
    Example: Filtering for Addressable Buildings 
    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