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

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

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

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

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

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

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

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

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

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

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

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

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

نوع پُرسمان مثال
مختصات طول و عرض جغرافیایی. به‌جای آن از پُرسمان مکان استفاده کنید. "37.422131,-122.084801"
مفاهیم یا محدودیت‌های بسیار زیاد، مانند نام چندین مکان، جاده، یا شهر در یک پُرسمان «Market Street San Francisco San Jose Airport»
عناصر نشانی پستی که در Google Maps نشان داده نمی‌شود «C/O John Smith 123 Main Street»
«P.O. Box 13 San Francisco»
نام کسب‌وکارها، زنجیره‌ها، یا دسته‌هایی که با مکان‌هایی ترکیب شده‌اند که این نهادها در آن‌ها دردسترس نیستند «Tesco near Dallas, Texas» (تسکو نزدیک دالاس، تگزاس)
پرسمان‌های مبهم با چند تفسیر «تحویل شارژر»
نام‌های قدیمی که دیگر استفاده نمی‌شوند "Middlesex United Kingdom"
عناصر یا هدف غیرزمین‌مکانی «چند قایق در بندر ونتورا وجود دارد؟»
نام‌های غیررسمی یا نام‌های سفارشی «برج هیجان»
«سرسره مارپیچ»
نهادهای سیاسی بزرگ (شهرها، ایالت‌ها، کشورها) "New York City"
"California"
"USA"
مسیرهای بدون نشانی مشخص «خیابان اول، ‫NYC, NY"
"I-95"
curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "601 S Bernardo Ave, Sunnyvale, CA 94087, USA"
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

primary

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

addressComponents

آرایه‌ای حاوی عناصر جداگانه مربوط به این نشانی.

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

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

containingPlaces

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

subDestinations

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

entrances

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

  • location

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

  • entrance_tags[]

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

    • "PREFERRED"

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

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

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

  • ‫streetViewThumbnail و streetViewAnnotation

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

structureType

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

  • POINT

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

  • SECTION

    زیرمجموعه‌ای از یک ساختمان.

  • BUILDING

    ساختمان.

  • GROUNDS

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

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

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

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

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

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

landmarks

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

هر نقطه عطف شامل فیلدهای زیر است:

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

arrivalSummary

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

parkingOptions

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

قالب پاسخ

‫SearchDestinations SearchDestinationsResponse از شکل JSON زیر برمی‌گرداند:

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

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

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

    با ایجاد پوشش فیلد پاسخ، فهرست فیلدهای برگشتی در پاسخ را مشخص کنید. ماسک فیلد پاسخ را بااستفاده از پارامتر نشانی وب $fields یا fields، یا بااستفاده از سرصفحه HTTP X-Goog-FieldMask به روش ارسال کنید. برای مثال، درخواست زیر فقط ورودی‌ها، نقاط پیمایش، و شناسه مکان مقصد اصلی را برمی‌گرداند.

      curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
        -H "X-Goog-Api-Key: API_KEY" \
        -H "Content-Type: application/json" \
        -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary.place" \
        https://geocode.googleapis.com/v4/geocode/destinations
      

    فهرست پیش‌فرضی از فیلدهای برگشتی در پاسخ وجود ندارد. اگر ماسک فیلد را حذف کنید، روش خطا برمی‌گرداند. ماسک فیلد را روی * تنظیم کنید تا همه فیلدها برگردانده شود. برای جزئیات بیشتر، انتخاب فیلدها برای برگرداندن را ببینید.

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

  • travelModes

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

  • languageCode

    زبانی که نتایج باید به آن برگردانده شود.

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

    کد منطقه به‌عنوان مقدار کد CLDR دو نویسه‌ای. مقدار پیش‌فرضی وجود ندارد. بیشتر کدهای CLDR با کدهای ISO 3166-1 یکسان هستند.

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

  • placeFilter

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

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

    فیلتر structureType به شما امکان می‌دهد نوع ساختارهایی را که پُرسمان برمی‌گرداند مشخص کنید:

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

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

    همه مکان‌ها نشانی واضحی در سطح خیابان ندارند. فیلتر addressability به شما کمک می‌کند کیفیت نشانی‌ها را در نتایجتان کنترل کنید:

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