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

پلتفرم مورد نظر را انتخاب کنید: اندروید، 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 های مرتبط با آنها، به فیلدهای داده مکانی (جدید) مراجعه کنید.

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

      addressComponents
      addressDescriptor *
      adrFormatAddress
      formattedAddress
      location
      plusCode
      postalAddress
      shortFormattedAddress
      types
      viewport

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

      برای فهرست کاملی از فیلدها و SKU های مرتبط با آنها، به فیلدهای داده مکانی (جدید) مراجعه کنید.

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

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

      برای فهرست کاملی از فیلدها و SKU های مرتبط با آنها، به فیلدهای داده مکانی (جدید) مراجعه کنید.

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

      currentOpeningHours
      currentSecondaryOpeningHours
      internationalPhoneNumber
      nationalPhoneNumber
      priceLevel
      priceRange
      rating
      regularOpeningHours
      regularSecondaryOpeningHours
      transitStation
      userRatingCount
      websiteUri

      برای فهرست کاملی از فیلدها و SKU های مرتبط با آنها، به فیلدهای داده مکانی (جدید) مراجعه کنید.

    • فیلدهای زیر، 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

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

      برای فهرست کاملی از فیلدها و SKU های مرتبط با آنها، به فیلدهای داده مکانی (جدید) مراجعه کنید.

  • شناسه مکان

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

    رشته 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 را در بدنه پاسخ حذف کند، یک مکان در مکان فعلی خود است.

کسب و کارهایی که در آینده افتتاح می‌شوند را پیدا کنید

می‌توانید جزئیات مربوط به کسب‌وکارهایی را که انتظار می‌رود در آینده افتتاح شوند، درخواست کنید. جستجوی نزدیک (جدید) در صورتی فیلد openingDate پر می‌کند که تاریخ افتتاح پیش‌بینی‌شده حداقل شامل ماه باشد و کمتر از ۹۰ روز تا آن فاصله داشته باشد.

مثال زیر یک درخواست جستجوی نزدیک (جدید) برای افتتاح یک کسب و کار در آینده در نیو مدوز، آیداهو را نشان می‌دهد: 

curl -X GET \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,businessStatus,openingDate" \
"https://places.googleapis.com/v1/places/ChIJp1-VoKWJplQRMz8g-7Wa3Do"

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

{
  "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
  "businessStatus": "FUTURE_OPENING",
  "openingDate": {
    "year": 2026,
    "month": 4,
    "day": 15
  }
}

اطلاعات ایستگاه حمل و نقل را دریافت کنید

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

مثال زیر درخواستی برای اطلاعات ایستگاه حمل و نقل عمومی برای ایستگاه گرند سنترال را نشان می‌دهد: 

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

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

  {
  "id": "ChIJLVaKiQFZwokRgcybX3K6Pzg",
  "displayName": {
    "text": "Grand Central",
    "languageCode": "en"
  },
  "transitStation": {
    "displayName": {
      "text": "Grand Central",
      "languageCode": "en"
    },
    "agencies": [
      {
        "displayName": {
          "text": "MTA New York City Transit",
          "languageCode": "en"
        },
        "url": "http://www.mta.info/",
        "lines": [
          {
            "id": "ChIJ420yFwBZwokR903kVZLSsFc",
            "vehicleType": "SUBWAY",
            "displayName": {
              "text": "42 St Shuttle",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "S",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#808183",
            "url": "https://www.mta.info/schedules/subway/42-st-shuttle",
            "icon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/S.svg",
              "nameIncluded": true
            },
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg"
            }
          },
          {
            "id": "ChIJDdd_uEdfwokRHbLvWrdBdDM",
            "vehicleType": "SUBWAY",
            "displayName": {
              "text": "5 Train (Lexington Av Express)",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "5 Line",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#00933C",
            "url": "https://www.mta.info/schedules/subway/5-train",
            "icon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/5.svg",
              "nameIncluded": true
            },
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg"
            }
          }
          ...
        ]
      },
      {
        "displayName": {
          "text": "MTA",
          "languageCode": "en"
        },
        "url": "https://new.mta.info/",
        "lines": [
          {
            "id": "ChIJcwVpzKpZwokR24EBeh8arww",
            "vehicleType": "BUS",
            "displayName": {
              "text": "United Nations - W 42 St Pier",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "M42",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#1D59B3",
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg"
            }
          }
        ]
      },
      {
        "displayName": {
          "text": "Long Island Rail Road",
          "languageCode": "en"
        },
        "url": "http://www.mta.info/lirr",
        "lines": [
          {
            "id": "ChIJv9m8uWM56IkRUcVBQ6Q_In0",
            "vehicleType": "HEAVY_RAIL",
            "displayName": {
              "text": "Ronkonkoma Branch",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "LIRR",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#A626AA",
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg"
            }
          }
          ...
        ]
      }
    ],
    "stops": [
      {
        "id": "ChIJRcemlf1YwokRhFqqw5jKBFM",
        "stopCode": {
          "text": "GCT"
        },
        "location": {
          "latitude": 40.755161,
          "longitude": -73.975456
        },
        "wheelchairAccessibleEntrance": true
      },
      {
        "id": "ChIJ57l2zANZwokRD1pyhuwpfKY",
        "signageText": {
          "text": "34 St-Hudson Yards & Main St-Flushing, Queens, 7",
          "languageCode": "en"
        },
        "location": {
          "latitude": 40.750983,
          "longitude": -73.9750686
        },
        "wheelchairAccessibleEntrance": true
      },
      {
        "id": "ChIJoVXJgQFZwokR1yzq_WVuEuc",
        "displayName": {
          "text": "E 42 St/Park Av",
          "languageCode": "en"
        },
        "location": {
          "latitude": 40.7518199,
          "longitude": -73.9771918
        },
        "wheelchairAccessibleEntrance": true
      }
      ...
    ]
  }
}

ورودی‌ها و نقاط ناوبری را دریافت کنید

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

نقاط ناوبری یک navigationPointToken برمی‌گردانند. می‌توانید این توکن را به Navigation SDK (موجود برای اندروید یا iOS ) یا Routes API ارسال کنید تا رانندگان را به آن مکان خاص هدایت کنید. برای اطلاعات بیشتر، به Navigation point tokens مراجعه کنید.

مثال زیر جزئیات مربوط به فرودگاه بین‌المللی سانفرانسیسکو (شناسه مکان ChIJVVVVVYx3j4ARP-3NGldc8qQ ) شامل entrances و navigationPoints در ماسک فیلد را درخواست می‌کند: 

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

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

{
  "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ",
  "displayName": {
    "text": "San Francisco International Airport",
    "languageCode": "en"
  },
  "entrances": [
    {
      "location": {
        "latitude": 37.6172154,
        "longitude": -122.3839724
      }
    },
    {
      "location": {
        "latitude": 37.6174073,
        "longitude": -122.384196
      }
    },
    ...
  ],
  "navigationPoints": [
    {
      "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...",
      "displayName": {
        "text": "International Terminal Departures Level",
        "languageCode": "en"
      },
      "location": {
        "latitude": 37.6153121,
        "longitude": -122.3900833
      },
      "travelModes": ["WALK"]
    },
    {
      "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...",
      "displayName": {
        "text": "Domestic Garage - SFO Short Term Parking",
        "languageCode": "en"
      },
      "location": {
        "latitude": 37.6157153,
        "longitude": -122.3885012
      },
      "travelModes": ["DRIVE", "WALK"],
      "usages": ["PARKING"]
    },
    ...
  ]
}

امتحانش کن!

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

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

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

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

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

،
پلتفرم مورد نظر را انتخاب کنید: اندروید، 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 های مرتبط با آنها، به فیلدهای داده مکانی (جدید) مراجعه کنید.

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

      addressComponents
      addressDescriptor *
      adrFormatAddress
      formattedAddress
      location
      plusCode
      postalAddress
      shortFormattedAddress
      types
      viewport

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

      برای فهرست کاملی از فیلدها و SKU های مرتبط با آنها، به فیلدهای داده مکانی (جدید) مراجعه کنید.

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

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

      برای فهرست کاملی از فیلدها و SKU های مرتبط با آنها، به فیلدهای داده مکانی (جدید) مراجعه کنید.

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

      currentOpeningHours
      currentSecondaryOpeningHours
      internationalPhoneNumber
      nationalPhoneNumber
      priceLevel
      priceRange
      rating
      regularOpeningHours
      regularSecondaryOpeningHours
      transitStation
      userRatingCount
      websiteUri

      برای فهرست کاملی از فیلدها و SKU های مرتبط با آنها، به فیلدهای داده مکانی (جدید) مراجعه کنید.

    • فیلدهای زیر، 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

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

      برای فهرست کاملی از فیلدها و SKU های مرتبط با آنها، به فیلدهای داده مکانی (جدید) مراجعه کنید.

  • شناسه مکان

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

    رشته 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 را در بدنه پاسخ حذف کند، یک مکان در مکان فعلی خود است.

کسب و کارهایی که در آینده افتتاح می‌شوند را پیدا کنید

می‌توانید جزئیات مربوط به کسب‌وکارهایی را که انتظار می‌رود در آینده افتتاح شوند، درخواست کنید. جستجوی نزدیک (جدید) در صورتی فیلد openingDate پر می‌کند که تاریخ افتتاح پیش‌بینی‌شده حداقل شامل ماه باشد و کمتر از ۹۰ روز تا آن فاصله داشته باشد.

مثال زیر یک درخواست جستجوی نزدیک (جدید) برای افتتاح یک کسب و کار در آینده در نیو مدوز، آیداهو را نشان می‌دهد: 

curl -X GET \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,businessStatus,openingDate" \
"https://places.googleapis.com/v1/places/ChIJp1-VoKWJplQRMz8g-7Wa3Do"

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

{
  "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
  "businessStatus": "FUTURE_OPENING",
  "openingDate": {
    "year": 2026,
    "month": 4,
    "day": 15
  }
}

اطلاعات ایستگاه حمل و نقل را دریافت کنید

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

مثال زیر درخواستی برای اطلاعات ایستگاه حمل و نقل عمومی برای ایستگاه گرند سنترال را نشان می‌دهد: 

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

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

  {
  "id": "ChIJLVaKiQFZwokRgcybX3K6Pzg",
  "displayName": {
    "text": "Grand Central",
    "languageCode": "en"
  },
  "transitStation": {
    "displayName": {
      "text": "Grand Central",
      "languageCode": "en"
    },
    "agencies": [
      {
        "displayName": {
          "text": "MTA New York City Transit",
          "languageCode": "en"
        },
        "url": "http://www.mta.info/",
        "lines": [
          {
            "id": "ChIJ420yFwBZwokR903kVZLSsFc",
            "vehicleType": "SUBWAY",
            "displayName": {
              "text": "42 St Shuttle",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "S",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#808183",
            "url": "https://www.mta.info/schedules/subway/42-st-shuttle",
            "icon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/S.svg",
              "nameIncluded": true
            },
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg"
            }
          },
          {
            "id": "ChIJDdd_uEdfwokRHbLvWrdBdDM",
            "vehicleType": "SUBWAY",
            "displayName": {
              "text": "5 Train (Lexington Av Express)",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "5 Line",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#00933C",
            "url": "https://www.mta.info/schedules/subway/5-train",
            "icon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/5.svg",
              "nameIncluded": true
            },
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg"
            }
          }
          ...
        ]
      },
      {
        "displayName": {
          "text": "MTA",
          "languageCode": "en"
        },
        "url": "https://new.mta.info/",
        "lines": [
          {
            "id": "ChIJcwVpzKpZwokR24EBeh8arww",
            "vehicleType": "BUS",
            "displayName": {
              "text": "United Nations - W 42 St Pier",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "M42",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#1D59B3",
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg"
            }
          }
        ]
      },
      {
        "displayName": {
          "text": "Long Island Rail Road",
          "languageCode": "en"
        },
        "url": "http://www.mta.info/lirr",
        "lines": [
          {
            "id": "ChIJv9m8uWM56IkRUcVBQ6Q_In0",
            "vehicleType": "HEAVY_RAIL",
            "displayName": {
              "text": "Ronkonkoma Branch",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "LIRR",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#A626AA",
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg"
            }
          }
          ...
        ]
      }
    ],
    "stops": [
      {
        "id": "ChIJRcemlf1YwokRhFqqw5jKBFM",
        "stopCode": {
          "text": "GCT"
        },
        "location": {
          "latitude": 40.755161,
          "longitude": -73.975456
        },
        "wheelchairAccessibleEntrance": true
      },
      {
        "id": "ChIJ57l2zANZwokRD1pyhuwpfKY",
        "signageText": {
          "text": "34 St-Hudson Yards & Main St-Flushing, Queens, 7",
          "languageCode": "en"
        },
        "location": {
          "latitude": 40.750983,
          "longitude": -73.9750686
        },
        "wheelchairAccessibleEntrance": true
      },
      {
        "id": "ChIJoVXJgQFZwokR1yzq_WVuEuc",
        "displayName": {
          "text": "E 42 St/Park Av",
          "languageCode": "en"
        },
        "location": {
          "latitude": 40.7518199,
          "longitude": -73.9771918
        },
        "wheelchairAccessibleEntrance": true
      }
      ...
    ]
  }
}

ورودی‌ها و نقاط ناوبری را دریافت کنید

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

نقاط ناوبری یک navigationPointToken برمی‌گردانند. می‌توانید این توکن را به Navigation SDK (موجود برای اندروید یا iOS ) یا Routes API ارسال کنید تا رانندگان را به آن مکان خاص هدایت کنید. برای اطلاعات بیشتر، به Navigation point tokens مراجعه کنید.

مثال زیر جزئیات مربوط به فرودگاه بین‌المللی سانفرانسیسکو (شناسه مکان ChIJVVVVVYx3j4ARP-3NGldc8qQ ) شامل entrances و navigationPoints در ماسک فیلد را درخواست می‌کند: 

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

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

{
  "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ",
  "displayName": {
    "text": "San Francisco International Airport",
    "languageCode": "en"
  },
  "entrances": [
    {
      "location": {
        "latitude": 37.6172154,
        "longitude": -122.3839724
      }
    },
    {
      "location": {
        "latitude": 37.6174073,
        "longitude": -122.384196
      }
    },
    ...
  ],
  "navigationPoints": [
    {
      "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...",
      "displayName": {
        "text": "International Terminal Departures Level",
        "languageCode": "en"
      },
      "location": {
        "latitude": 37.6153121,
        "longitude": -122.3900833
      },
      "travelModes": ["WALK"]
    },
    {
      "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...",
      "displayName": {
        "text": "Domestic Garage - SFO Short Term Parking",
        "languageCode": "en"
      },
      "location": {
        "latitude": 37.6157153,
        "longitude": -122.3885012
      },
      "travelModes": ["DRIVE", "WALK"],
      "usages": ["PARKING"]
    },
    ...
  ]
}

امتحانش کن!

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

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

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

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

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

،
پلتفرم مورد نظر را انتخاب کنید: اندروید، 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 های مرتبط با آنها، به فیلدهای داده مکانی (جدید) مراجعه کنید.

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

      addressComponents
      addressDescriptor *
      adrFormatAddress
      formattedAddress
      location
      plusCode
      postalAddress
      shortFormattedAddress
      types
      viewport

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

      برای فهرست کاملی از فیلدها و SKU های مرتبط با آنها، به فیلدهای داده مکانی (جدید) مراجعه کنید.

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

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

      برای فهرست کاملی از فیلدها و SKU های مرتبط با آنها، به فیلدهای داده مکانی (جدید) مراجعه کنید.

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

      currentOpeningHours
      currentSecondaryOpeningHours
      internationalPhoneNumber
      nationalPhoneNumber
      priceLevel
      priceRange
      rating
      regularOpeningHours
      regularSecondaryOpeningHours
      transitStation
      userRatingCount
      websiteUri

      برای فهرست کاملی از فیلدها و SKU های مرتبط با آنها، به فیلدهای داده مکانی (جدید) مراجعه کنید.

    • فیلدهای زیر، 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

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

      برای فهرست کاملی از فیلدها و SKU های مرتبط با آنها، به فیلدهای داده مکانی (جدید) مراجعه کنید.

  • شناسه مکان

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

    رشته 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

Note that the X-Goog-FieldMask header specifies that the response contains the following data fields: id,displayName . The response is then in the form:

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

Add more data types to the field mask to return additional information. For example, add formattedAddress,plusCode to include the address and Plus Code in the response :

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

The response is now in the form: 

{
  "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"
  }
}

Get address descriptors

Address descriptors provide relational information about a place's location, including nearby landmarks and containing areas.

The following example shows a Place Details (New) request for a department store in a San Jose mall. In this example, you include addressDescriptors in the field 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"

The response includes the place specified in the request, a list of nearby landmarks and their distance from the place, and a list of areas and their containment relationship to the place: 

  {
    "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"
        }
      ]
    }
  }

Get place details for a moved place

If a place referenced in your app has relocated, you can use the movedPlace and movedPlaceId fields to get the details of the new place.

For places that are permanently closed , Place Details (New) returns CLOSED_PERMANENTLY in the businessStatus field and omits the movedPlace and movedPlaceId fields in the response body.

For places that have moved to a new location , Place Details (New) returns CLOSED_PERMANENTLY in the businessStatus field and returns the new location in the movedPlace and movedPlaceId fields of the response body.

For places that have not moved , Place Details (New) does not return movedPlace or movedPlaceId in the response body.

The following example requests place information about Marche IGA St-Canut in Quebec, Canada: 

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

The request returns the following response: 

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

To request details about the new place, use the Place resource name in the movedPlace field in a new Place Details (New) request.

For places that have relocated multiple times , getting details about the current location may require multiple chained Place Details (New) requests. The movedPlace and movedPlaceId fields of a place result only point to the next location, not the last known location. A place is in its current location if a Place Details (New) request omits the movedPlace and movedPlaceId fields in the response body.

Find businesses opening in the future

You can request details about businesses that are expected to open in the future. Nearby Search (New) will populate the openingDate field if the anticipated opening date includes at least the month and is fewer than 90 days away.

The following example shows a Nearby Search (New) request for a business opening in the future in New Meadows, Idaho: 

curl -X GET \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,businessStatus,openingDate" \
"https://places.googleapis.com/v1/places/ChIJp1-VoKWJplQRMz8g-7Wa3Do"

The response includes the place's business status and anticipated opening date: 

{
  "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
  "businessStatus": "FUTURE_OPENING",
  "openingDate": {
    "year": 2026,
    "month": 4,
    "day": 15
  }
}

Get transit station information

You can use Place Details (New) to get information about transit stations. The response body includes information about the station, including the station name, affiliated transit agencies, and transit lines serving the station. Additionally, the response includes a vehicle icon and colors that you can use to display the transit station information.

The following example shows a request for transit station information for Grand Central Station: 

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

The response body includes information about each station within the radius, lines served by the station, alerts issued by transit agencies at that stop, and departure information: 

  {
  "id": "ChIJLVaKiQFZwokRgcybX3K6Pzg",
  "displayName": {
    "text": "Grand Central",
    "languageCode": "en"
  },
  "transitStation": {
    "displayName": {
      "text": "Grand Central",
      "languageCode": "en"
    },
    "agencies": [
      {
        "displayName": {
          "text": "MTA New York City Transit",
          "languageCode": "en"
        },
        "url": "http://www.mta.info/",
        "lines": [
          {
            "id": "ChIJ420yFwBZwokR903kVZLSsFc",
            "vehicleType": "SUBWAY",
            "displayName": {
              "text": "42 St Shuttle",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "S",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#808183",
            "url": "https://www.mta.info/schedules/subway/42-st-shuttle",
            "icon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/S.svg",
              "nameIncluded": true
            },
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg"
            }
          },
          {
            "id": "ChIJDdd_uEdfwokRHbLvWrdBdDM",
            "vehicleType": "SUBWAY",
            "displayName": {
              "text": "5 Train (Lexington Av Express)",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "5 Line",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#00933C",
            "url": "https://www.mta.info/schedules/subway/5-train",
            "icon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/5.svg",
              "nameIncluded": true
            },
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg"
            }
          }
          ...
        ]
      },
      {
        "displayName": {
          "text": "MTA",
          "languageCode": "en"
        },
        "url": "https://new.mta.info/",
        "lines": [
          {
            "id": "ChIJcwVpzKpZwokR24EBeh8arww",
            "vehicleType": "BUS",
            "displayName": {
              "text": "United Nations - W 42 St Pier",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "M42",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#1D59B3",
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg"
            }
          }
        ]
      },
      {
        "displayName": {
          "text": "Long Island Rail Road",
          "languageCode": "en"
        },
        "url": "http://www.mta.info/lirr",
        "lines": [
          {
            "id": "ChIJv9m8uWM56IkRUcVBQ6Q_In0",
            "vehicleType": "HEAVY_RAIL",
            "displayName": {
              "text": "Ronkonkoma Branch",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "LIRR",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#A626AA",
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg"
            }
          }
          ...
        ]
      }
    ],
    "stops": [
      {
        "id": "ChIJRcemlf1YwokRhFqqw5jKBFM",
        "stopCode": {
          "text": "GCT"
        },
        "location": {
          "latitude": 40.755161,
          "longitude": -73.975456
        },
        "wheelchairAccessibleEntrance": true
      },
      {
        "id": "ChIJ57l2zANZwokRD1pyhuwpfKY",
        "signageText": {
          "text": "34 St-Hudson Yards & Main St-Flushing, Queens, 7",
          "languageCode": "en"
        },
        "location": {
          "latitude": 40.750983,
          "longitude": -73.9750686
        },
        "wheelchairAccessibleEntrance": true
      },
      {
        "id": "ChIJoVXJgQFZwokR1yzq_WVuEuc",
        "displayName": {
          "text": "E 42 St/Park Av",
          "languageCode": "en"
        },
        "location": {
          "latitude": 40.7518199,
          "longitude": -73.9771918
        },
        "wheelchairAccessibleEntrance": true
      }
      ...
    ]
  }
}

Get entrances and navigation points

You can request entrances and navigation points for a destination. Entrances define entry and exit points for a place (for example, different gates at an airport or mall). Navigation points define road-side locations where navigation should end, which is useful for directing users to the correct side of the road or a specific drop-off point.

Navigation points return a navigationPointToken . You can pass this token to the Navigation SDK (available for Android or iOS ) or the Routes API to guide drivers to that specific location. For more information, see Navigation point tokens .

The following example requests details for San Francisco International Airport (place ID ChIJVVVVVYx3j4ARP-3NGldc8qQ ), including entrances and navigationPoints in the field mask: 

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

The response includes the entrances and navigation points for the place: 

{
  "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ",
  "displayName": {
    "text": "San Francisco International Airport",
    "languageCode": "en"
  },
  "entrances": [
    {
      "location": {
        "latitude": 37.6172154,
        "longitude": -122.3839724
      }
    },
    {
      "location": {
        "latitude": 37.6174073,
        "longitude": -122.384196
      }
    },
    ...
  ],
  "navigationPoints": [
    {
      "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...",
      "displayName": {
        "text": "International Terminal Departures Level",
        "languageCode": "en"
      },
      "location": {
        "latitude": 37.6153121,
        "longitude": -122.3900833
      },
      "travelModes": ["WALK"]
    },
    {
      "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...",
      "displayName": {
        "text": "Domestic Garage - SFO Short Term Parking",
        "languageCode": "en"
      },
      "location": {
        "latitude": 37.6157153,
        "longitude": -122.3885012
      },
      "travelModes": ["DRIVE", "WALK"],
      "usages": ["PARKING"]
    },
    ...
  ]
}

امتحانش کن!

The APIs Explorer lets you make sample requests so that you can get familiar with the API and the API options.

  1. Select the API icon api on the right side of the page.

  2. Optionally edit the request parameters.

  3. Select the Execute button. In the dialog, choose the account that you want to use to make the request.

  4. In the APIs Explorer panel, select the fullscreen icon fullscreen to expand the APIs Explorer window.