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

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

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

يتيح لك "مستكشف واجهة برمجة التطبيقات" إجراء طلبات مباشرة لتتمكن من الإلمام بواجهة برمجة التطبيقات وخيارات واجهة برمجة التطبيقات:

جرِّبه الآن

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

طلب تفاصيل المكان هو طلب 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: *

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

  • 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. يمكنك ضبط المعلَمة name بشكل اختياري على:
    places/PLACE_ID
  2. يمكنك اختياريًا توسيع قسم عرض المَعلمات العادية وضبط المَعلمة fields على قناع الحقل.
  3. انقر على الزر تنفيذ. في النافذة المنبثقة، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.