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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 شرح نوشتاری کامل یا نام مؤلفه نشانی است که توسط Geocoder برگردانده شده است.
shortText نام متنی اختصاری برای مؤلفه نشانی است، درصورت وجود. برای مثال، مؤلفه نشانی برای ایالت آلاسکا ممکن است longText «آلاسکا» و shortText «AK» را بااستفاده از مخفف پستی دوحرفی داشته باشد.
‫languageCode زبانی است که برای قالب‌بندی این مؤلفه در نماد CLDR استفاده می‌شود.

`containingPlaces`

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

`subDestinations`

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

`entrances`

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

displayName

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

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

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

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

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

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

`structureType`

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

POINT

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

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

ساختمان.
GROUNDS

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

`navigationPoints`

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

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

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

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

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

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

`landmarks`

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

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

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

`arrivalSummary`

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

`parkingOptions`

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

قالب پاسخ

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

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

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

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

با ایجاد کردن ماسک فیلد پاسخ، فهرست فیلدهایی را که باید در پاسخ برگردانده شود مشخص کنید. ماسک فیلد پاسخ را بااستفاده از پارامتر نشانی وب $fields یا fields، یا بااستفاده از سرصفحه HTTP X-Goog-FieldMask به روش ارسال کنید. برای مثال، درخواست زیر فقط ورودی‌ها، نقاط پیمایش، و شناسه مکان مقصد اصلی را برمی‌گرداند.
```
  curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
    -H "X-Goog-Api-Key: API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary.place" \
    https://geocode.googleapis.com/v4/geocode/destinations
  
```
هیچ فهرست پیش‌فرضی از فیلدهای برگردانده‌شده در پاسخ وجود ندارد. اگر ماسک فیلد را حذف کنید، روش خطا برمی‌گرداند. ماسک فیلد را روی * تنظیم کنید تا همه فیلدها برگردانده شود. برای جزئیات بیشتر، انتخاب فیلدها برای برگرداندن را ببینید.

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

travelModes

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

primary

addressComponents

containingPlaces

subDestinations

entrances

structureType

navigationPoints

landmarks

arrivalSummary

parkingOptions

قالب پاسخ

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

FieldMask

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

travelModes

languageCode

regionCode

placeFilter

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

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