أرقام تعريف الأماكن

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

تحدد أرقام تعريف الأماكن مكانًا بشكل فريد في قاعدة بيانات أماكن Google وفي خرائط Google. يتم قبول معرّفات الأماكن في الطلبات الواردة إلى واجهات API للخرائط التالية:

  • استرداد عنوان لرقم تعريف المكان في خدمة الويب لواجهة برمجة تطبيقات الترميز الجغرافي وخدمة الترميز الجغرافي، وواجهة برمجة تطبيقات JavaScript JavaScript.
  • يتم تحديد نقاط الطريق المصدر والوجهة والمتوسطة في خدمة الويب Routes API وخدمة Directions API وخدمة الاتجاهات، وواجهة برمجة التطبيقات Maps JavaScript API.
  • تحديد المصادر والوجهات في Routes API وخدمة الويب لواجهة برمجة تطبيقات مصفوفة المسافة، وخدمة مصفوفة المسافة، وواجهة برمجة التطبيقات Maps JavaScript API.
  • استرداد تفاصيل المكان في خدمة الويب لواجهة برمجة تطبيقات الأماكن وحزمة تطوير برامج الأماكن لأجهزة Android وحزمة تطوير برامج الأماكن لنظام التشغيل iOS ومكتبة الأماكن.
  • استخدام معلمات رقم تعريف المكان في واجهة برمجة تطبيقات تضمين الخرائط.
  • استرداد طلبات البحث في عناوين URL للخرائط.
  • يتم عرض حدود السرعة في واجهة برمجة التطبيقات للطرق.
  • العثور على مضلّعات الحدود وتصميمها في تصميم الحدود المستند إلى البيانات.

العثور على رقم تعريف مكان معيّن

هل تبحث عن رقم تعريف مكان معيّن؟ استخدِم أداة البحث عن رقم تعريف المكان أدناه للبحث عن مكان والحصول على معرّفه:

بدلاً من ذلك، يمكنك الاطّلاع على أداة البحث عن رقم تعريف المكان باستخدام رمزها في مستندات JavaScript API للخرائط.

نظرة عامة

رقم تعريف المكان هو معرّف نصي يعرّف المكان بشكل فريد. وقد يختلف طول المعرّف (ما مِن حد أقصى لطول أرقام تعريف الأماكن). أمثلة:

  • ChIJgUbEo8cfqokR5lP9_Wh_DaM
  • GhIJQWDl0CIeQUARxks3icF8U8A
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E
  • IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ

تتوفّر أرقام تعريف الأماكن لمعظم المواقع الجغرافية، بما في ذلك الأنشطة التجارية والمعالم والمنتزهات والتقاطعات. من الممكن أن يكون للمكان أو الموقع الجغرافي نفسه عدة معرّفات أماكن مختلفة. قد تتغيّر أرقام تعريف الأماكن بمرور الوقت.

يمكنك استخدام رقم تعريف المكان نفسه في Places API وعدد من واجهات برمجة التطبيقات في "منصة خرائط Google". على سبيل المثال، يمكنك استخدام معرّف المكان نفسه للإشارة إلى مكان في واجهة برمجة تطبيقات الأماكن وواجهة برمجة تطبيقات JavaScript للخرائط وواجهة برمجة تطبيقات الترميز الجغرافي وواجهة برمجة تطبيقات تضمين الخرائط وواجهة برمجة تطبيقات الطرق.

استرداد تفاصيل المكان باستخدام معرّف المكان

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

مثال باستخدام حزمة تطوير برامج الأماكن لأجهزة iOS

رقم تعريف المكان هو معرّف نصي يعرّف المكان بشكل فريد. في حزمة تطوير برامج الأماكن لأجهزة iOS، يمكنك استرداد رقم تعريف مكان من كائن GMSPlace. يمكنك تخزين رقم تعريف المكان واستخدامه لاسترداد عنصر GMSPlace مرة أخرى لاحقًا.

للحصول على مكان من خلال رقم التعريف، اطلب GMSPlacesClient fetchPlaceFromPlaceID:، مع ضبط المَعلمات التالية:

  • سلسلة تحتوي على رقم تعريف المكان.
  • سمة GMSPlaceField واحدة أو أكثر، مع تحديد أنواع البيانات المطلوب عرضها.
  • رمز مميز للجلسة إذا تم إجراء الاستدعاء لإنهاء طلب بحث يتم إكماله تلقائيًا. أو لا، لا شيء.
  • GMSPlaceResultCallback لمعالجة النتيجة.

تستدعي واجهة برمجة التطبيقات طريقة معاودة الاتصال المحدّدة، مع تمرير كائن GMSPlace. إذا لم يتم العثور على المكان، يكون كائن المكان معدومًا.

Swift

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
  UInt(GMSPlaceField.placeID.rawValue))!

placesClient?.fetchPlace(fromPlaceID: placeID, placeFields: fields, sessionToken: nil, callback: {
  (place: GMSPlace?, error: Error?) in
  if let error = error {
    print("An error occurred: \(error.localizedDescription)")
    return
  }
  if let place = place {
    self.lblName?.text = place.name
    print("The selected place is: \(place.name)")
  }
})

Objective-C

// A hotel in Saigon with an attribution.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to return.
GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);

[_placesClient fetchPlaceFromPlaceID:placeID placeFields:fields sessionToken:nil callback:^(GMSPlace * _Nullable place, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"An error occurred %@", [error localizedDescription]);
    return;
  }
  if (place != nil) {
    NSLog(@"The selected place is: %@", [place name]);
  }
}];

حفظ أرقام تعريف الأماكن لاستخدامها لاحقًا

تُعفى أرقام تعريف الأماكن من قيود التخزين المؤقت المنصوص عليها في الفقرة 3.2.3(ب) من بنود خدمة "منصة خرائط Google". وبالتالي، يمكنك تخزين قيم رقم تعريف المكان لاستخدامها في وقت لاحق.

جارٍ إعادة تحميل أرقام تعريف الأماكن المخزَّنة

ننصح بإعادة تحميل معرّفات الأماكن إذا كان عمرها أكثر من 12 شهرًا. يمكنك إعادة تحميل أرقام تعريف الأماكن بدون أي رسوم من خلال تقديم طلب تفاصيل المكان مع تحديد الحقل GMSPlaceFieldPlaceID فقط في المعلَمة fields. تؤدي هذه الاستدعاء إلى تشغيل رمز التخزين التعريفي تفاصيل الأماكن - تحديث المعرّف. في المقابل، قد يعرض هذا الطلب أيضًا رمز الحالة NOT_FOUND. تتمثّل إحدى الاستراتيجيات في تخزين الطلب الأصلي الذي عرض كل رقم تعريف مكان. وإذا أصبح معرّف المكان غير صالح، يمكنك إعادة إصدار هذا الطلب للحصول على نتائج جديدة. قد تتضمّن هذه النتائج المكان الأصلي أو لا تتضمّنه. ويمكن تحصيل رسوم الطلب.

رموز الخطأ عند استخدام معرّفات الأماكن

يشير رمز الحالة INVALID_REQUEST إلى أنّ رقم تعريف المكان المحدّد غير صالح. يجوز عرض INVALID_REQUEST عندما يتم اقتطاع رقم تعريف المكان أو تعديله بأي طريقة أخرى، ويصبح غير صحيح بعد ذلك.

يشير رمز الحالة NOT_FOUND إلى أن رقم تعريف المكان المحدّد قديم. قد يصبح معرّف المكان قديمًا إذا تم إغلاق نشاط تجاري أو نقله إلى موقع جغرافي جديد. قد تتغيّر أرقام تعريف الأماكن بسبب تعديلات واسعة النطاق على قاعدة بيانات "خرائط Google". وفي هذه الحالات، قد يتلقّى المكان معرّفًا جديدًا للمكان، ويعرض المعرّف القديم رد NOT_FOUND.

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

  • عناوين الشوارع غير المتوفرة في "خرائط Google" كعناوين دقيقة، ولكن يتم استنتاجها من مجموعة من العناوين.
  • أجزاء من مسار طويل، حيث يحدد الطلب أيضًا مدينة أو منطقة محلية.
  • التقاطعات.
  • الأماكن التي تحتوي على مكوّن عنوان من النوع subpremise

غالبًا ما تأخذ أرقام التعريف هذه في شكل سلسلة طويلة (لا يوجد حد أقصى لطول أرقام تعريف الأماكن). مثال:

EpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4