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

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

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

• البحث النصي (ميزة جديدة) أو البحث في الجوار (ميزة جديدة)
• 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: *

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

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

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

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

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

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

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

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

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

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

    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 في الاستجابة رقم تعريف المكان المستقل.

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

• languageCode

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

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

• regionCode

  رمز المنطقة المستخدَم لتنسيق الاستجابة، ويتم تحديده على أنّه قيمة رمز 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"
  }
}

جرّب الآن

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

لتقديم طلب:

1. انقر على رمز واجهة برمجة التطبيقات على يسار الصفحة.
2. يمكنك اختياريًا ضبط المَعلمة name على:

   places/PLACE_ID

3. يمكنك اختياريًا توسيع عرض المَعلمات العادية وضبط مَعلمة fields على قناع الحقل.
4. انقر على الزر تنفيذ. في النافذة المنبثقة، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.

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