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

مقدمة

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

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

• البحث النصي (جديد) أو البحث في الجوار (جديد)
• Geocoding API
• Routes API
• Address Validation API
• الإكمال التلقائي (جديد)

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

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

طلب "تفاصيل المكان (جديد)" هو طلب 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 في حزمة Pro SKU.

  • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي لإصدار Place Details Essentials:

    addressComponents
addressDescriptor^*
    adrFormatAddress
formattedAddress
location
plusCode
postalAddress
shortFormattedAddress
types
viewport
    
    ^* تتوفّر أوصاف العناوين بشكل عام للعملاء في الهند، وهي تجريبية في أماكن أخرى.
    
    

  • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي الخاص بـ "تفاصيل المكان":

    accessibilityOptions
businessStatus
containingPlaces
displayName
googleMapsLinks
googleMapsUri
iconBackgroundColor
iconMaskBaseUri
primaryType
primaryTypeDisplayName
pureServiceAreaBusiness
subDestinations
utcOffsetMinutes
    
    

  • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي الخاص بميزة "تفاصيل المكان" في Enterprise:

    currentOpeningHours
currentSecondaryOpeningHours
internationalPhoneNumber
nationalPhoneNumber
priceLevel
priceRange
rating
regularOpeningHours
regularSecondaryOpeningHours
userRatingCount
websiteUri

  • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي "تفاصيل المكان" في Enterprise + Atmosphere:

    allowsDogs
curbsidePickup
delivery
dineIn
editorialSummary
evChargeAmenitySummary
evChargeOptions
fuelOptions
generativeSummary
goodForChildren
goodForGroups
goodForWatchingSports
liveMusic
menuForChildren
neighborhoodSummary
parkingOptions
paymentOptions
outdoorSeating
reservable
restroom
reviews
reviewSummary
routingSummaries^*
    servesBeer
servesBreakfast
servesBrunch
servesCocktails
servesCoffee
servesDessert
servesDinner
servesLunch
servesVegetarianFood
servesWine
takeout
    
    ^* "البحث النصي" و"البحث في الجوار" فقط

• placeId

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

  يُطلق على السلسلة places/PLACE_ID أيضًا اسم اسم مورد المكان. في الردّ الوارد من طلبات Place Details (New) وNearby Search (New) وText Search (New)، يتم تضمين هذه السلسلة في الحقل 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

  رموز الجلسات هي سلاسل من إنشاء المستخدمين تتتبّع طلبات الإكمال التلقائي (الجديد) باعتبارها "جلسات". تستخدم ميزة "الإكمال التلقائي" (جديدة) رموز الجلسات المميزة لتجميع طلب البحث ومراحل اختيار المكان في عملية بحث الإكمال التلقائي التي يجريها المستخدم، وذلك في جلسة منفصلة لأغراض الفوترة. يتم تمرير الرموز المميزة للجلسات إلى طلبات Place Details (New) التي تلي طلبات Autocomplete (New). لمزيد من المعلومات، يُرجى الاطّلاع على رموز الجلسات المميزة.

مثال على "تفاصيل المكان (جديد)"

يطلب المثال التالي تفاصيل مكان معيّن باستخدام 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 لتضمين العنوان ورمز Plus Code في الرد:

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"
  }
}

الحصول على أوصاف العناوين

توفّر أوصاف العناوين معلومات ذات صلة بموقع المكان، بما في ذلك المعالم القريبة والمناطق التي يقع فيها.

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

  curl -X GET https://places.googleapis.com/v1/places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4 \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  -H "X-Goog-FieldMask: name,displayName,addressDescriptor"

يتضمّن الردّ المكان المحدّد في الطلب، وقائمة بالمعالم القريبة والمسافة بينها وبين المكان، وقائمة بالمناطق وعلاقة الاحتواء بينها وبين المكان:

  {
    "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
    "displayName": {
      "text": "Macy's",
      "languageCode": "en"
    },
    "addressDescriptor": {
      "landmarks": [
        {
          "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
          "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
          "displayName": {
            "text": "Westfield Valley Fair",
            "languageCode": "en"
          },
          "types": [
            "clothing_store",
            "department_store",
            "establishment",
            "food",
            "movie_theater",
            "point_of_interest",
            "restaurant",
            "shoe_store",
            "shopping_mall",
            "store"
          ],
          "spatialRelationship": "WITHIN",
          "straightLineDistanceMeters": 220.29175
        },
        {
          "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
          "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
          "displayName": {
            "text": "Nordstrom",
            "languageCode": "en"
          },
          "types": [
            "clothing_store",
            "department_store",
            "establishment",
            "point_of_interest",
            "shoe_store",
            "store"
          ],
          "straightLineDistanceMeters": 329.45178
        },
        {
          "name": "places/ChIJmx1c5x7Lj4ARJXJy_CU_JbE",
          "placeId": "ChIJmx1c5x7Lj4ARJXJy_CU_JbE",
          "displayName": {
            "text": "Monroe Parking Garage",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "parking",
            "point_of_interest"
          ],
          "straightLineDistanceMeters": 227.05153
        },
        {
          "name": "places/ChIJxcwBziHLj4ARUQLAvtzkRCM",
          "placeId": "ChIJxcwBziHLj4ARUQLAvtzkRCM",
          "displayName": {
            "text": "Studios Inn by Daiwa Living California Inc.",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "lodging",
            "point_of_interest",
            "real_estate_agency"
          ],
          "straightLineDistanceMeters": 299.9955
        },
        {
          "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
          "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
          "displayName": {
            "text": "Din Tai Fung",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "food",
            "point_of_interest",
            "restaurant"
          ],
          "straightLineDistanceMeters": 157.70943
        }
      ],
      "areas": [
        {
          "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
          "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
          "displayName": {
            "text": "Westfield Valley Fair",
            "languageCode": "en"
          },
          "containment": "WITHIN"
        },
        {
          "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
          "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
          "displayName": {
            "text": "Valley Fair",
            "languageCode": "en"
          },
          "containment": "WITHIN"
        },
        {
          "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
          "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
          "displayName": {
            "text": "Central San Jose",
            "languageCode": "en"
          },
          "containment": "WITHIN"
        }
      ]
    }
  }

جرِّبها الآن

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

1. انقر على رمز واجهة برمجة التطبيقات api في يسار الصفحة.

2. عدِّل مَعلمات الطلب اختياريًا.

3. انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.

4. في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز ملء الشاشة fullscreen لتوسيع نافذة "مستكشف واجهات برمجة التطبيقات".