جزئیات جا (جدید)

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

مقدمه

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

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

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

درخواست‌های «جزئیات جا (جدید)»

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

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

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

شیء JSON کامل در فرم است:

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

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

  • FieldMask

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

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

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

    X-Goog-FieldMask: displayName,formattedAddress

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

    X-Goog-FieldMask: *

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

    • فیلدهای زیر شناسه واحد نگهداری موجودی فقط ضروریات جزئیات جا را راه‌اندازی می‌کنند:

      attributions
      consumerAlert
      id
      movedPlace
      movedPlaceId
      name*
      photos

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

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

    • فیلدهای زیر شناسه محصول ضروریات جزئیات جا را راه‌اندازی می‌کنند:

      addressComponents
      addressDescriptor*
      adrFormatAddress
      formattedAddress
      location
      plusCode
      postalAddress
      shortFormattedAddress
      types
      viewport

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

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

    • فیلدهای زیر باعث فعال شدن شناسه محصول Place Details Pro می‌شوند:

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

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

    • فیلدهای زیر شناسه محصول سازمانی جزئیات جا را راه‌اندازی می‌کنند:

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

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

    • فیلدهای زیر شناسه محصول Place Details Enterprise + Atmosphere را راه‌اندازی می‌کنند:

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

  • placeId

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

    رشته places/PLACE_ID نام منبع مکان نیز نامیده می‌شود. در پاسخ از درخواست «جزئیات مکان (جدید)»، «جستجوی اطراف (جدید)»، و «جستجوی نوشتار (جدید)»، این رشته در فیلد name پاسخ قرار دارد. شناسه مکان مستقل در فیلد id پاسخ قرار دارد.

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

  • languageCode

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

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

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

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

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

  • sessionToken

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

نمونه «جزئیات جا (جدید)»

نمونه زیر جزئیات مکانی را با 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"
  }
}

دریافت رده‌بندی‌ها، تعداد مرورها، و مرورها

برای بازیابی میانگین رده‌بندی ستاره‌ای کسب‌وکار، تعداد کل رده‌بندی‌ها (مجموع مرورها)، یا نوشتار مرور مشتری، فیلدهای مربوطه را در سرصفحه X-Goog-FieldMask خود اضافه کنید:

اگر برنامه‌تان فقط به رده‌بندی ستاره‌ای و تعداد کل مرورها نیاز دارد، rating و userRatingCount را بدون reviews درخواست کنید تا درخواست در ردیف Place Details Enterprise SKU باقی بماند:

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

برای بازیابی حداکثر پنج شیء ارسال‌شده توسط کاربر Review ، reviews را به ماسک فیلد اضافه کنید (صورت‌حساب در سطح Place Details Enterprise + Atmosphere SKU صادر می‌شود):

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

پاسخ شامل رده‌بندی، تعداد کل رده‌بندی‌ها، و reviews آرایه است:

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  },
  "rating": 4.2,
  "userRatingCount": 2594,
  "reviews": [
    {
      "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/reviews/...",
      "relativePublishTimeDescription": "a month ago",
      "rating": 5,
      "text": {
        "text": "Iconic tech campus with visitor areas and cafes.",
        "languageCode": "en"
      },
      "authorAttribution": {
        "displayName": "Alex Rivera"
      }
    }
  ]
}

دریافت توصیف‌کننده‌های نشانی

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

مثال زیر درخواست «جزئیات مکان (جدید)» را برای فروشگاه بزرگ در مرکز خرید سن خوزه نشان می‌دهد. در این مثال، addressDescriptors را در ماسک فیلد اضافه می‌کنید:

  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 برای دریافت جزئیات مکان جدید استفاده کنید.

برای مکان‌هایی که برای همیشه بسته شده‌اند، «جزئیات جا (جدید)» CLOSED_PERMANENTLY را در فیلد businessStatus برمی‌گرداند و فیلدهای movedPlace و movedPlaceId را در بدنه پاسخ حذف می‌کند.

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

برای مکان‌هایی که منتقل نشده‌اند، «جزئیات جا (جدید)» 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"
}

برای درخواست جزئیات درباره مکان جدید، از نام منبع «مکان» در فیلد movedPlace در درخواست جدید «جزئیات مکان» (جدید) استفاده کنید.

برای مکان‌هایی که چندین‌بار جابه‌جا شده‌اند، دریافت جزئیات درباره مکان فعلی ممکن است به چندین درخواست زنجیره‌ای «جزئیات مکان (جدید)» نیاز داشته باشد. فیلدهای movedPlace و movedPlaceId نتیجه مکان فقط به مکان بعدی اشاره می‌کنند، نه آخرین مکان مشخص. اگر درخواست «جزئیات مکان (جدید)» فیلدهای 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 را برمی‌گرداند. می‌توانید این توکن را به «کیت توسعه نرم‌افزار ناوبری» (موجود برای Android یا iOS) یا میانای برنامه‌سازی کاربردی Routes ارسال کنید تا رانندگان را به آن مکان خاص هدایت کنید. برای اطلاعات بیشتر، نشان‌های نقطه ناوبری را ببینید.

مثال زیر جزئیات فرودگاه بین‌المللی سان‌فرانسیسکو (شناسه مکان 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 Explorer می‌توانید درخواست‌های نمونه ایجاد کنید تا با API و گزینه‌های API آشنا شوید.

  1. نماد API api را در سمت چپ صفحه انتخاب کنید.

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

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

  4. در پانل «کاوشگر API»، نماد تمام‌صفحه تمام‌صفحه را انتخاب کنید تا پنجره «کاوشگر API» ازهم باز شود.