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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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",
          "american_restaurant",
          "meal_takeaway",
          "restaurant",
          "food_store",
          "food",
          "point_of_interest",
          "store",
          "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/ChIJteQ0Fum2j4ARGi3tqK4Zm14",
            "displayName": {
              "text": "Safeway",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "florist",
              "butcher_shop",
              "deli",
              "bakery",
              "food_delivery",
              "supermarket",
              "market",
              "food_store",
              "food",
              "point_of_interest",
              "store",
              "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
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ]
        },
        {
          "place": {
            "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs",
            "displayName": {
              "text": "Starbird Chicken",
              "languageCode": "en"
            },
            "types": [
              "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": {
              "type": "Polygon",
              "coordinates": [
                [
                  [
                    -122.057003840785,
                    37.3747648209809
                  ],
                  [
                    -122.057136852459,
                    37.3747919153144
                  ],
                  [
                    -122.057205005705,
                    37.3745815131859
                  ],
                  [
                    -122.057071994114,
                    37.3745544186944
                  ],
                  [
                    -122.057003840785,
                    37.3747648209809
                  ]
                ]
              ]
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ]
        },
        {
          "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
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ]
        },
        {
          "place": {
            "place": "places/ChIJlbIO1Oi2j4ARp17Uf24xkHk",
            "displayName": {
              "text": "Madras Café",
              "languageCode": "en"
            },
            "primaryType": "indian_restaurant",
            "types": [
              "indian_restaurant",
              "coffee_shop",
              "cafe",
              "restaurant",
              "food_store",
              "food",
              "point_of_interest",
              "store",
              "establishment"
            ],
            "formattedAddress": "Madras Café, 1177 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1026",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1177 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3743,
              "longitude": -122.0549333
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ]
        }
      ],
      "entrances": [
        {
          "location": {
            "latitude": 37.373531299999996,
            "longitude": -122.05694519999999
          },
          "tags": [
            "PREFERRED"
          ],
          "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
        }
      ],
      "navigationPoints": [
        {
          "location": {
            "latitude": 37.3738659,
            "longitude": -122.05693620000001
          },
          "travelModes": [
            "DRIVE",
            "WALK"
          ],
          "usages": [
            "UNKNOWN"
          ]
        }
      ]
    }
  ]
}

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

  • یکی از ۳ پارامتر زیر باید در درخواست 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/v4alpha/geocode/destinations

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

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

  • حالت‌های سفر

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

  • زبانکد

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

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

  • کد منطقه

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

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

بازخورد

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