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

توسعه دهندگان منطقه اقتصادی اروپا (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

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

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

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

می توانید آدرس را به عنوان یک رشته بدون ساختار مشخص کنید:

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 برای درخواست استفاده کنید

Geocoding API v4 از OAuth 2.0 برای احراز هویت پشتیبانی می کند. برای استفاده از OAuth با Geocoding API، نشانه OAuth باید دامنه صحیحی را به آن اختصاص دهد. Geocoding API از حوزه های زیر برای استفاده با نقطه پایانی Destinations پشتیبانی می کند:

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

همچنین، می‌توانید https://www.googleapis.com/auth/cloud-platform scope عمومی برای تمام نقاط پایانی Geocoding 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"
          ]
        }
      ]
    }
  ]
}

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

  • یکی از 3 پارامتر زیر باید در درخواست 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 تنظیم نشده باشد، نقاط ناوبری همه حالت‌های سفر را می‌توان برگرداند.

  • کد زبان

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

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

  • منطقه کد

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

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

بازخورد

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