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

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

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

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

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

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

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

نظرة عامة

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

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

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

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

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

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

مثال باستخدام حزمة تطوير برامج الأماكن لأجهزة 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