جزئیات مکان (جدید)

پلتفرم مورد نظر را انتخاب کنید: اندروید، iOS، جاوا اسکریپت ، وب سرویس
توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

مقدمه

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

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

مرورگر APIها به شما امکان می‌دهد درخواست‌های زنده ارسال کنید تا بتوانید با API و گزینه‌های API آشنا شوید:

درخواست‌های جزئیات مکان (جدید)

درخواست جزئیات مکان (جدید) یک درخواست HTTP GET به شکل زیر است:

https://places.googleapis.com/v1/places/PLACE_ID

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

https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEY

یا در یک دستور curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

پاسخ‌های جزئیات مکان (جدید)

جزئیات مکان (جدید) یک شیء JSON را به عنوان پاسخ برمی‌گرداند. در پاسخ:

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

شیء کامل JSON به شکل زیر است:

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "displayName": {
    "text": "Trinidad"
  }
  ...
}

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

  • فیلد ماسک

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

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

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

    X-Goog-FieldMask: displayName,formattedAddress

    برای بازیابی همه فیلدها از * استفاده کنید.

    X-Goog-FieldMask: *

    یک یا چند مورد از فیلدهای زیر را مشخص کنید:

    • فیلدهای زیر، SKU مربوط به جزئیات مکان، ملزومات، شناسه‌ها و فقط کد کالا (Place Details Essentials IDs Only SKU) را فعال می‌کنند:

      attributions
      id
      moved_place
      moved_place_id
      name *
      photos

      * فیلد name شامل نام منبع مکان به شکل places/ PLACE_ID است. برای دریافت نام متنی مکان، فیلد displayName در Pro SKU درخواست کنید.

    • فیلدهای زیر SKU مربوط به جزئیات مکان (Place Details Essentials) را فعال می‌کنند:

      addressComponents
      addressDescriptor *
      adrFormatAddress
      formattedAddress
      location
      plusCode
      postalAddress
      shortFormattedAddress
      types
      viewport

      * توصیف‌گرهای آدرس عموماً برای مشتریان در هند در دسترس هستند و در جاهای دیگر آزمایشی می‌باشند.

    • فیلدهای زیر، SKU مربوط به Place Details Pro را فعال می‌کنند:

      accessibilityOptions
      businessStatus
      containingPlaces
      displayName
      googleMapsLinks
      googleMapsUri
      iconBackgroundColor
      iconMaskBaseUri
      primaryType
      primaryTypeDisplayName
      pureServiceAreaBusiness
      subDestinations
      utcOffsetMinutes

    • فیلدهای زیر، SKU مربوط به جزئیات مکان سازمانی را فعال می‌کنند:

      currentOpeningHours
      currentSecondaryOpeningHours
      internationalPhoneNumber
      nationalPhoneNumber
      priceLevel
      priceRange
      rating
      regularOpeningHours
      regularSecondaryOpeningHours
      userRatingCount
      websiteUri

    • فیلدهای زیر، SKU مربوط به جزئیات مکان، شرکت + اتمسفر را فعال می‌کنند:

      allowsDogs
      curbsidePickup
      delivery
      dineIn
      editorialSummary
      evChargeAmenitySummary
      evChargeOptions
      fuelOptions
      generativeSummary
      goodForChildren
      goodForGroups
      goodForWatchingSports
      liveMusic
      menuForChildren
      neighborhoodSummary
      parkingOptions
      paymentOptions
      outdoorSeating
      reservable
      restroom
      reviews
      reviewSummary
      routingSummaries *
      servesBeer
      servesBreakfast
      servesBrunch
      servesCocktails
      servesCoffee
      servesDessert
      servesDinner
      servesLunch
      servesVegetarianFood
      servesWine
      takeout

      * فقط جستجوی متنی و جستجوی نزدیک

  • شناسه مکان

    یک شناسه متنی که به طور منحصر به فرد یک مکان را مشخص می‌کند، از جستجوی متن (جدید) یا جستجوی نزدیک (جدید) برگردانده می‌شود. برای اطلاعات بیشتر در مورد شناسه‌های مکان، به نمای کلی شناسه مکان مراجعه کنید.

    رشته places/ PLACE_ID همچنین به عنوان نام منبع مکان نامیده می‌شود. در پاسخ از درخواست‌های Place Details (New)، Nearby Search (New) و Text Search (New)، این رشته در فیلد name پاسخ قرار دارد. شناسه مکان مستقل در فیلد id پاسخ قرار دارد.

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

  • زبانکد

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

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

  • کد منطقه

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

    اگر نام کشور فیلد formattedAddress در پاسخ با regionCode مطابقت داشته باشد، کد کشور از formattedAddress حذف می‌شود. این پارامتر هیچ تاثیری بر adrFormatAddress که همیشه شامل نام کشور است، یا shortFormattedAddress که هرگز شامل آن نمی‌شود، ندارد.

    بیشتر کدهای CLDR با کدهای ISO 3166-1 یکسان هستند، به جز برخی استثنائات قابل توجه. برای مثال، ccTLD بریتانیا "uk" (.co.uk) است در حالی که کد ISO 3166-1 آن "gb" است (از نظر فنی برای موجودیت "پادشاهی متحده بریتانیای کبیر و ایرلند شمالی"). این پارامتر می‌تواند بر اساس قانون مربوطه بر نتایج تأثیر بگذارد.

  • توکن جلسه

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

مثال جزئیات مکان (جدید)

مثال زیر جزئیات یک مکان را با استفاده از placeId درخواست می‌کند:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

توجه داشته باشید که هدر X-Goog-FieldMask مشخص می‌کند که پاسخ شامل فیلدهای داده زیر است: id,displayName . در این صورت، پاسخ به شکل زیر خواهد بود:

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  }
}

برای برگرداندن اطلاعات بیشتر، انواع داده بیشتری را به ماسک فیلد اضافه کنید. برای مثال، formattedAddress,plusCode برای گنجاندن آدرس و Plus Code را در پاسخ اضافه کنید:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,formattedAddress,plusCode" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

پاسخ اکنون به این شکل است: 

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "plusCode": {
    "globalCode": "849VCWC7+RW",
    "compoundCode": "CWC7+RW Mountain View, CA, USA"
  },
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  }
}

دریافت توصیفگرهای آدرس

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

مثال زیر یک درخواست Place Details (جدید) برای یک فروشگاه بزرگ در یک مرکز خرید در سن خوزه را نشان می‌دهد. در این مثال، شما addressDescriptors در فیلد mask قرار می‌دهید: 

  curl -X GET https://places.googleapis.com/v1/places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4 \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  -H "X-Goog-FieldMask: name,displayName,addressDescriptor"

پاسخ شامل مکان مشخص شده در درخواست، فهرستی از مکان‌های دیدنی نزدیک و فاصله آنها از مکان، و فهرستی از مناطق و ارتباط آنها با مکان است: 

  {
    "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
    "displayName": {
      "text": "Macy's",
      "languageCode": "en"
    },
    "addressDescriptor": {
      "landmarks": [
        {
          "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
          "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
          "displayName": {
            "text": "Westfield Valley Fair",
            "languageCode": "en"
          },
          "types": [
            "clothing_store",
            "department_store",
            "establishment",
            "food",
            "movie_theater",
            "point_of_interest",
            "restaurant",
            "shoe_store",
            "shopping_mall",
            "store"
          ],
          "spatialRelationship": "WITHIN",
          "straightLineDistanceMeters": 220.29175
        },
        {
          "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
          "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
          "displayName": {
            "text": "Nordstrom",
            "languageCode": "en"
          },
          "types": [
            "clothing_store",
            "department_store",
            "establishment",
            "point_of_interest",
            "shoe_store",
            "store"
          ],
          "straightLineDistanceMeters": 329.45178
        },
        {
          "name": "places/ChIJmx1c5x7Lj4ARJXJy_CU_JbE",
          "placeId": "ChIJmx1c5x7Lj4ARJXJy_CU_JbE",
          "displayName": {
            "text": "Monroe Parking Garage",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "parking",
            "point_of_interest"
          ],
          "straightLineDistanceMeters": 227.05153
        },
        {
          "name": "places/ChIJxcwBziHLj4ARUQLAvtzkRCM",
          "placeId": "ChIJxcwBziHLj4ARUQLAvtzkRCM",
          "displayName": {
            "text": "Studios Inn by Daiwa Living California Inc.",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "lodging",
            "point_of_interest",
            "real_estate_agency"
          ],
          "straightLineDistanceMeters": 299.9955
        },
        {
          "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
          "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
          "displayName": {
            "text": "Din Tai Fung",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "food",
            "point_of_interest",
            "restaurant"
          ],
          "straightLineDistanceMeters": 157.70943
        }
      ],
      "areas": [
        {
          "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
          "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
          "displayName": {
            "text": "Westfield Valley Fair",
            "languageCode": "en"
          },
          "containment": "WITHIN"
        },
        {
          "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
          "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
          "displayName": {
            "text": "Valley Fair",
            "languageCode": "en"
          },
          "containment": "WITHIN"
        },
        {
          "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
          "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
          "displayName": {
            "text": "Central San Jose",
            "languageCode": "en"
          },
          "containment": "WITHIN"
        }
      ]
    }
  }

جزئیات مکان را برای مکان جابجا شده دریافت کنید

اگر مکانی که در برنامه شما به آن ارجاع داده شده است، تغییر مکان داده باشد، می‌توانید از فیلدهای movedPlace و movedPlaceId برای دریافت جزئیات مکان جدید استفاده کنید.

برای مکان‌هایی که به‌طور دائم بسته شده‌اند ، Place Details (New) CLOSED_PERMANENTLY را در فیلد businessStatus برمی‌گرداند و فیلدهای movedPlace و movedPlaceId در بدنه پاسخ حذف می‌کند.

برای مکان‌هایی که به مکان جدیدی منتقل شده‌اند ، تابع Place Details (New) CLOSED_PERMANENTLY را در فیلد businessStatus برمی‌گرداند و مکان جدید را در فیلدهای movedPlace و movedPlaceId از بدنه پاسخ برمی‌گرداند.

برای مکان‌هایی که جابجا نشده‌اند ، تابع Place Details (New) در بدنه پاسخ movedPlace یا movedPlaceId برنمی‌گرداند.

مثال زیر اطلاعات مکانی در مورد Marche IGA St-Canut در کبک، کانادا را درخواست می‌کند: 

curl -X  GET -H 'Content-Type: application/json' \
-H 'x-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: id,displayName,businessStatus,movedPlace,movedPlaceId' \
https://places.googleapis.com/v1/places/ChIJUfQdGInVzkwRzAjmjzWB7CQ

درخواست، پاسخ زیر را برمی‌گرداند: 

{
  "id": "ChIJUfQdGInVzkwRzAjmjzWB7CQ",
  "businessStatus": "CLOSED_PERMANENTLY",
  "displayName": {
    "text": "Marche IGA St-Canut",
    "languageCode": "en"
  },
  "movedPlace": "places/ChIJ36QT7n8qz0wRDqVZ_UBlUlQ",
  "movedPlaceId": "ChIJ36QT7n8qz0wRDqVZ_UBlUlQ"
}

برای درخواست جزئیات مربوط به مکان جدید، از نام منبع Place در فیلد movedPlace در یک درخواست new Place Details (New) استفاده کنید.

برای مکان‌هایی که چندین بار جابجا شده‌اند ، دریافت جزئیات مربوط به مکان فعلی ممکن است نیاز به چندین درخواست زنجیره‌ای Place Details (New) داشته باشد. فیلدهای movedPlace و movedPlaceId از نتیجه یک مکان فقط به مکان بعدی اشاره می‌کنند، نه آخرین مکان شناخته شده. اگر درخواست Place Details (New) فیلدهای movedPlace و movedPlaceId را در بدنه پاسخ حذف کند، یک مکان در مکان فعلی خود قرار دارد.

امتحانش کن!

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

  1. آیکون API یعنی api را در سمت راست صفحه انتخاب کنید.

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

  3. دکمه اجرا را انتخاب کنید. در کادر محاوره‌ای، حسابی را که می‌خواهید برای ارسال درخواست استفاده کنید، انتخاب کنید.

  4. در پنل APIs Explorer، آیکون تمام صفحه را در حالت تمام صفحه انتخاب کنید تا پنجره APIs Explorer باز شود.