بعد حصولك على رقم تعريف المكان، يمكنك طلب المزيد من التفاصيل حول منشأة أو نقطة اهتمام معيّنة من خلال بدء طلب تفاصيل المكان (جديد). يعرض طلب تفاصيل المكان (جديد) معلومات أكثر شمولاً عن المكان المشار إليه مثل العنوان الكامل ورقم الهاتف وتقييم المستخدم والمراجعات.
هناك العديد من الطرق للحصول على رقم تعريف مكان. يمكنك استخدام:
- البحث النصي (جديد) أو البحث عن قرب (جديد)
- 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
، أو باستخدام عنوان HTTPX-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" } }
تجربة
يتيح لك مستكشف واجهات برمجة التطبيقات تقديم طلبات نموذجية حتى تتعرّف على خيارات واجهة برمجة التطبيقات وواجهة برمجة التطبيقات.
لتقديم طلب:
- انقر على رمز واجهة برمجة التطبيقات، ، على يسار الصفحة.
- يمكنك اختياريًا ضبط المَعلمة
name
على:places/PLACE_ID
- يمكنك اختياريًا توسيع عرض المعلَمات العادية وضبط المَعلمة
fields
على قناع الحقل. - انقر على الزر تنفيذ. في النافذة المنبثقة، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز التوسيع، ، لتوسيع نافذة "مستكشف واجهة برمجة التطبيقات".