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

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

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

• البحث النصي (جديد) أو البحث عن قرب (جديد)
• واجهة برمجة تطبيقات الترميز الجغرافي
• Routes API
• Address Verification 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 في قسم رموز الأماكن.

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

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

    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، servesBeer، delivery، servesBeer،
    ، liveMusic،reviewsservesBreakfastservesBrunchservesCocktailsservesCoffeeservesDessertsservesDinnerservesLunchservesVegetarianFoodservesWinetakeout

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