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