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

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

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

• البحث النصي (جديد) أو البحث عن قرب (جديد)
• Geocoding API
• Routes 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, displayName, googleMapsUri, iconBackgroundColor, iconMaskBaseUri, primaryType, primaryTypeDisplayName, subDestinations, utcOffsetMinutes

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

    currentOpeningHours, currentSecondaryOpeningHours, internationalPhoneNumber, nationalPhoneNumber, priceLevel, rating, regularOpeningHours, regularSecondaryOpeningHours, userRatingCount, websiteUri

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

    allowsDogs, curbsidePickup, delivery, dineIn, editorialSummary, evChargeOptions, fuelOptions, goodForChildren, goodForGroups, goodForWatchingSports, liveMusic, menuForChildren, parkingOptions, paymentOptions, outdoorSeating, reservable, restroom, reviews, 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. في لوحة "مستكشف واجهة برمجة التطبيقات"، حدد رمز التوسيع، ، لتوسيع نافذة مستكشف واجهة برمجة التطبيقات