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

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

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

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

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

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

شما می‌توانید با فراخوانی PlacesClient.fetchPlace() و ارسال یک شیء FetchPlaceRequest حاوی شناسه مکان و لیست فیلدها و همچنین هر پارامتر اختیاری ، جزئیات مکان را درخواست کنید:

// Define a place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList("INSERT_PLACE_FIELDS_HERE");

// Construct a request object, passing the place ID and field list.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

// Pass the request object and make the request
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);

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

جزئیات مکان (جدید) داده‌ها را در قالب یک شیء Place برمی‌گرداند، که فقط شامل فیلدهایی است که شما با استفاده از لیست فیلدها درخواست کرده‌اید. نتایج داده‌های مکان نمی‌توانند خالی باشند، بنابراین فقط نتایج مکانی که دارای داده هستند، بازگردانده می‌شوند (برای مثال، اگر یک مکان درخواستی هیچ عکسی نداشته باشد، فیلد عکس‌ها در نتیجه وجود نخواهد داشت).

برای دسترسی به فیلدهای داده، متد مربوطه را فراخوانی کنید. برای مثال، برای دسترسی به نام مکان، getName() را فراخوانی کنید.

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

پارامترهای مورد نیاز برای FetchPlaceRequest عبارتند از:

  • شناسه مکان

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

  • فهرست فیلدها

    وقتی مکانی را درخواست می‌کنید، باید مشخص کنید که کدام داده‌های مکانی برگردانده شوند. برای انجام این کار، لیستی از مقادیر Place.Field را که داده‌های برگردانده شده را مشخص می‌کنند، ارسال کنید. هیچ لیست پیش‌فرضی از فیلدهای برگردانده شده در پاسخ وجود ندارد.

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

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

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

      Place.Field.ID
      Place.Field.PHOTO_METADATAS
      Place.Field.RESOURCE_NAME

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

      Place.Field.ADDRESS_COMPONENTS
      ADR_FORMAT_ADDRESS
      Place.Field.FORMATTED_ADDRESS *
      * به جای Place.Field.ADDRESS (منسوخ شده) استفاده کنید.
      Place.Field.LOCATION *
      * به جای Place.Field.LAT_LNG (منسوخ شده) استفاده کنید.
      Place.Field.PLUS_CODE
      Place.Field.SHORT_FORMATTED_ADDRESS
      Place.Field.TYPES
      Place.Field.VIEWPORT

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

      Place.Field.ACCESSIBILITY_OPTIONS *
      * به جای Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (منسوخ شده) استفاده کنید.
      Place.Field.BUSINESS_STATUS
      Place.Field.DISPLAY_NAME *
      * به جای Place.Field.NAME که منسوخ شده است، استفاده کنید.
      Place.Field.GOOGLE_MAPS_URI
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL *
      * به جای Place.Field.ICON_URL (منسوخ شده) استفاده کنید.
      Place.Field.PRIMARY_TYPE
      Place.Field.PRIMARY_TYPE_DISPLAY_NAME
      Place.Field.SUB_DESTINATIONS
      Place.Field.UTC_OFFSET

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

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER *
      * به جای Place.Field.PHONE_NUMBER که منسوخ شده است، استفاده کنید.
      Place.Field.NATIONAL_PHONE_NUMBER
      Place.Field.OPENING_HOURS
      Place.Field.PRICE_LEVEL
      Place.Field.RATING
      Place.Field.SECONDARY_OPENING_HOURS
      Place.Field.USER_RATING_COUNT *
      * به جای Place.Field.USER_RATINGS_TOTAL که منسوخ شده است، استفاده کنید.
      Place.Field.WEBSITE_URI

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

      Place.Field.ALLOWS_DOGS
      Place.Field.CURBSIDE_PICKUP
      Place.Field.DELIVERY
      Place.Field.DINE_IN
      Place.Field.EDITORIAL_SUMMARY
      Place.Field.EV_CHARGE_OPTIONS
      Place.Field.FUEL_OPTIONS
      Place.Field.GOOD_FOR_CHILDREN
      Place.Field.GOOD_FOR_GROUPS
      Place.Field.GOOD_FOR_WATCHING_SPORTS
      Place.Field.LIVE_MUSIC
      Place.Field.MENU_FOR_CHILDREN
      Place.Field.OUTDOOR_SEATING
      Place.Field.PARKING_OPTIONS
      Place.Field.PAYMENT_OPTIONS
      Place.Field.RESERVABLE
      Place.Field.RESTROOM
      Place.Field.REVIEWS
      Place.Field.SERVES_BEER
      Place.Field.SERVES_BREAKFAST
      Place.Field.SERVES_BRUNCH
      Place.Field.SERVES_COCKTAILS
      Place.Field.SERVES_COFFEE
      Place.Field.SERVES_DESSERT
      Place.Field.SERVES_DINNER
      Place.Field.SERVES_LUNCH
      Place.Field.SERVES_VEGETARIAN_FOOD
      Place.Field.SERVES_WINE
      Place.Field.TAKEOUT

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

پارامترهای اختیاری برای FetchPlaceRequest عبارتند از:

  • کد منطقه

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

    اگر نام کشور فیلد Place.Field.FORMATTED_ADDRESS در پاسخ با regionCode مطابقت داشته باشد، کد کشور از Place.Field.FORMATTED_ADDRESS حذف می‌شود.

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

    برای تنظیم پارامتر کد منطقه، هنگام ساخت شیء FetchPlaceRequest ، متد setRegionCode() را فراخوانی کنید.

  • توکن جلسه

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

    برای تنظیم پارامتر توکن جلسه، هنگام ساخت شیء FetchPlaceRequest ، متد setSessionToken() را فراخوانی کنید.

مثال جزئیات مکان

مثال زیر فیلدهای ID ، DISPLAY_NAME و FORMATTED_ADDRESS را برای ساختمان امپایر استیت در شهر نیویورک درخواست می‌کند.

// Define a place ID.
final String placeId = "ChIJaXQRs6lZwokRY6EFpJnhNNE";

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS);

// Construct a request object, passing the place ID and field list.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

// Pass the request object and make the request
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);