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

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

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

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

• البحث النصي (جديد) أو البحث عن قرب (جديد)
• 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

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

تعرض "تفاصيل المكان" (New) كائن 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 للوصول إلى الاسم النصي للمكان.

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

    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، servesBreakfastservesBrunchservesCocktailsservesCoffeeservesDessertsservesDinnerservesLunchservesVegetarianFoodservesWinetakeout
    

• 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، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (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. في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز التوسيع، ، لتوسيع نافذة "مستكشف واجهة برمجة التطبيقات".