تفاصيل المكان (جديد)

اختيار النظام الأساسي: Android iOS JavaScript خدمة الويب

بعد الحصول على معرّف مكان، يمكنك طلب المزيد من التفاصيل عن مؤسسة معيّنة أو نقطة اهتمام معيّنة من خلال تقديم طلب تفاصيل المكان (جديد). يعرض طلب "تفاصيل المكان (جديد)" معلومات أكثر شمولاً عن المكان المشار إليه، مثل العنوان الكامل ورقم الهاتف وتقييم المستخدم والمراجعات.

هناك العديد من الطرق للحصول على رقم تعريف مكان. يمكنك استخدام:

• البحث النصي (ميزة جديدة) أو البحث في الجوار (ميزة جديدة)
• Geocoding API
• Routes API
• Address Validation 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"
  }
  ...
}

المعلمات المطلوبة

• FieldMask

  حدِّد قائمة الحقول التي تريد عرضها في الاستجابة عن طريق إنشاء قناع حقل الاستجابة. نقْل قناع حقل الاستجابة إلى الطريقة باستخدام مَعلمة عنوان URL $fields أو fields، أو باستخدام عنوان HTTP X-Goog-FieldMask. لا تتوفّر قائمة تلقائية بالحقول المعروضة في الردّ. في حال حذف قناع الحقل، ستعرض الطريقة خطأ.

  إنّ إخفاء الحقول هو ممارسة تصميم جيدة لضمان عدم طلب بيانات غير ضرورية، ما يساعد في تجنُّب وقت المعالجة غير الضروري و الرسوم المرتبطة بالفوترة.

  حدِّد قائمة مفصولة بفواصل بأنواع بيانات الأماكن المطلوب عرضها. على سبيل المثال، لاسترداد الاسم المعروض وعنوان المكان.

  X-Goog-FieldMask: displayName,formattedAddress

  ملاحظة: لا يُسمح باستخدام المسافات في أي مكان في قائمة الحقول.

  استخدِم * لاسترداد جميع الحقول.

  X-Goog-FieldMask: *

  يختار العنصر النائب "*" جميع الحقول. ومع أنّه يُسمح باستخدام علامة البدل هذه في مرحلة التطوير، لا تنصح Google باستخدام علامة البدل (*) لقناع حقل الردّ في مرحلة الإنتاج بسبب العدد الكبير من البيانات التي يمكن عرضها.
  يمكنك الاطّلاع على مزيد من الإرشادات حول استخدام iconMaskBaseUri و iconBackgroundColor في قسم رموز الأماكن.

  حدِّد حقلًا واحدًا أو أكثر من الحقول التالية:

  • تؤدي الحقول التالية إلى تنشيط رقم تعريف رمز التخزين التعريفي لميزة "تفاصيل المكان" الأساسية فقط:

    attributions
id
name^*
    photos
    
    ^* يحتوي الحقل name على مكان اسم المورد في الشكل: places/PLACE_ID. استخدِم displayName للوصول إلى الاسم النصي للمكان.

  • تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي لإصدار Essentials من "تفاصيل المكان":

    addressComponents
adrFormatAddress
formattedAddress
location
plusCode
shortFormattedAddress
types
viewport

  • تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي لميزة "تفاصيل الأماكن" المدفوعة:

    accessibilityOptions
businessStatus
containingPlaces
displayName
googleMapsLinks^*
    googleMapsUri
iconBackgroundColor
iconMaskBaseUri
primaryType
primaryTypeDisplayName
pureServiceAreaBusiness
subDestinations
utcOffsetMinutes
    
    ^* الحقل googleMapsLinks في مرحلة معاينة الإصدار التمهيدي للجمهور العام ولا يتم تحصيل أي رسوم، أي أنّ الفوترة هي 0 دولار أمريكي مقابل الاستخدام أثناء المعاينة.

  • تؤدي الحقول التالية إلى تنشيط Place Details EnterpriseSKU:

    currentOpeningHours
currentSecondaryOpeningHours
internationalPhoneNumber
nationalPhoneNumber
priceLevel
priceRange
rating
regularOpeningHours
regularSecondaryOpeningHours
userRatingCount
websiteUri

  • تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي لميزة "تفاصيل المكان" في Enterprise Plus:

    allowsDogs
curbsidePickup
delivery
dineIn
editorialSummary
evChargeOptions
fuelOptions
goodForChildren
goodForGroups
goodForWatchingSports
liveMusic
menuForChildren
parkingOptions
paymentOptions
outdoorSeating
reservable
restroom
reviews
routingSummaries^*
    servesBeer
servesBreakfast
servesBrunch
servesCocktails
servesCoffee
servesDessert
servesDinner
servesLunch
servesVegetarianFood
servesWine
takeout
    
    ^* البحث النصي والبحث عن الأجهزة المجاورة فقط

• placeId

  معرّف نصي يحدِّد مكانًا بشكل فريد، ويتم عرضه في نتيجة البحث النصي (جديد) أو البحث عن الأماكن القريبة (جديد). لمزيد من المعلومات عن أرقام تعريف الأماكن، اطّلِع على نظرة عامة على أرقام تعريف الأماكن.

  تُعرف السلسلة places/PLACE_ID أيضًا باسم اسم المورد للمكان. في الردّ على طلب "تفاصيل المكان" (جديد)، "البحث في الأماكن القريبة" (جديد)، و"البحث النصي" (جديد)، تكون هذه السلسلة مضمّنة في حقل name من الردّ. يتضمّن الحقل id في الاستجابة رقم تعريف المكان المستقل.

  ملاحظة: في تفاصيل المكان (الإصدار القديم)، كان الحقل name في الاستجابة يحتوي على الاسم القابل للقراءة من قِبل البشر للمكان. في واجهة برمجة التطبيقات الجديدة، يُطلَق على هذا الحقل الآن اسم displayName.

المعلمات الاختيارية

• languageCode

  اللغة التي يتم عرض النتائج بها

  • اطّلِع على قائمة اللغات المتاحة. غالبًا ما تعدّل Google اللغات المتاحة، لذا قد لا تكون هذه القائمة شاملة.
  • إذا لم يتم تقديم languageCode، يتم ضبط واجهة برمجة التطبيقات تلقائيًا على en. إذا حدّدت رمز لغة غير صالح، ستعرِض واجهة برمجة التطبيقات خطأ INVALID_ARGUMENT.
  • تبذل واجهة برمجة التطبيقات قصارى جهدها لتقديم عنوان شارع سهل القراءة لكل من المستخدمين والسكان المحليين. لتحقيق هذا الهدف، يعرض التطبيق عناوين الشارع باللغة المحلية، ويتم تحويلها إلى نص قابل للقراءة من قِبل المستخدم إذا لزم الأمر، مع مراعاة اللغة المفضّلة. يتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكونات العنوان باللغة نفسها التي يتم اختيارها من المكوّن الأول.
  • إذا لم يكن الاسم متوفّرًا باللغة المفضّلة، ستستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابقة.
  • يكون للّغة المفضّلة تأثير بسيط في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وترتيب عرضها. يفسّر المعرّف الجغرافي الاختصارات بشكلٍ مختلف حسب اللغة، مثل الاختصارات لأنواع الشوارع أو المرادفات التي قد تكون صالحة بلغة معيّنة ولكنّها غير صالحة بلغة أخرى.

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

جرّب الآن

يتيح لك "مستكشف واجهات برمجة التطبيقات" إنشاء نماذج طلبات لكي تتمكّن من التعرّف على واجهة برمجة التطبيقات وخياراتها.

1. انقر على رمز واجهة برمجة التطبيقات api على يسار الصفحة.

2. يمكنك اختياريًا تعديل مَعلمات الطلب.

3. انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.

4. في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز ملء الشاشة fullscreen لتوسيع نافذة "مستكشف واجهات برمجة التطبيقات".