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

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

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

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

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

جرِّبه الآن

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

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