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

پلتفرم را انتخاب کنید: سرویس وب جاوا اسکریپت اندروید iOS

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

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

• جستجوی متن (جدید) یا جستجوی نزدیک (جدید)
• API کدگذاری جغرافیایی
• Routes API
• Address Validation API
• محل تکمیل خودکار

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

  علامت عام "*" همه فیلدها را انتخاب می کند. با این حال، در حالی که استفاده از حروف عام در توسعه مناسب است، گوگل از استفاده از ماسک فیلد پاسخ علامت عام (*) در تولید خودداری می‌کند، زیرا حجم زیادی از داده‌هایی که می‌توانند برگردانده شوند.
  راهنمایی بیشتر برای استفاده از iconMaskBaseUri و iconBackgroundColor را می توان در بخش Place Icons یافت.

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

  • فیلدهای زیر SKU جزئیات مکان (فقط شناسه) را فعال می کنند:

    attributions ، id ، name ^* ، photos
    
    ^* فیلد name حاوی نام منبع مکان به شکل است: places/ PLACE_ID . از displayName برای دسترسی به نام متنی مکان استفاده کنید.

  • فیلدهای زیر SKU جزئیات مکان (فقط مکان) را فعال می کنند:

    addressComponents , adrFormatAddress , formattedAddress , location , plusCode , shortFormattedAddress , types , viewport

  • فیلدهای زیر SKU جزئیات مکان (پایه) را فعال می کنند:

    accessibilityOptions , businessStatus , containingPlaces , displayName , googleMapsLinks ^* , googleMapsUri utcOffsetMinutes iconBackgroundColor , iconMaskBaseUri , primaryType , primaryTypeDisplayName , pureServiceAreaBusiness , subDestinations
    
    ^* فیلد googleMapsLinks در مرحله پیش‌نمایش پیش‌نمایش GA است و هزینه‌ای دریافت نمی‌کند، به این معنی که صورت‌حساب 0 دلار برای استفاده در حین پیش‌نمایش است.

  • فیلدهای زیر SKU جزئیات مکان (پیشرفته) را فعال می کنند:

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

  • فیلدهای زیر SKU جزئیات مکان (ترجیحا) را فعال می کنند:

    allowsDogs ، curbsidePickup ، delivery ، dineIn ، editorialSummary ، evChargeOptions ، fuelOptions ، goodForChildren ، goodForGroups گروه‌ها، goodForWatchingSports ، liveMusic ، menuForChildren ، گزینه‌های parkingOptions ، paymentOptions outdoorSeating سرویس‌دهی restroom ، reviews ، ^* servesBeer routingSummaries servesBreakfast ، servesBrunch reservable servesCocktails ، servesCoffee ، servesDessert , servesDinner , servesLunch , servesVegetarianFood , servesWine , takeout
    
    ^* فقط جستجوی متن و جستجوی نزدیک

• شناسه مکان

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

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

  توجه: در جزئیات مکان موجود، قسمت name پاسخ حاوی نام قابل خواندن توسط انسان برای مکان است. در API جدید، آن فیلد اکنون displayName نامیده می شود.

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

• کد زبان

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

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

• منطقه کد

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

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

  اکثر کدهای CLDR با کدهای ISO 3166-1 یکسان هستند، با برخی استثناهای قابل توجه. برای مثال، ccTLD بریتانیا "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 را اضافه کنید تا آدرس و کد پلاس را در پاسخ اضافه کنید:

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

آن را امتحان کنید!

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

برای درخواست:

1. نماد API را انتخاب کنید، ، در سمت راست صفحه.
2. به صورت اختیاری پارامتر name روی:

   places/PLACE_ID

3. به صورت اختیاری نمایش پارامترهای استاندارد را گسترش دهید و پارامتر fields را روی فیلد ماسک تنظیم کنید.
4. دکمه Execute را انتخاب کنید. در پنجره پاپ آپ، حسابی را که می خواهید برای درخواست استفاده کنید، انتخاب کنید.

5. در پانل API Explorer، نماد گسترش را انتخاب کنید، ، برای گسترش پنجره API Explorer.