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

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

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

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

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

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

وبدلاً من ذلك، يمكنك عرض أداة البحث عن أرقام تعريف الأماكن باستخدام رمزها في مستندات واجهة برمجة التطبيقات JavaScript JavaScript.

نظرة عامة

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

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

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

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

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

يتم إعفاء أرقام تعريف الأماكن من قيود التخزين المؤقت المنصوص عليها في البند 3.2.3(ب) من بنود خدمة "منصة خرائط Google". بعد تحديد معرّف المكان، يمكنك إعادة استخدامه في المرة القادمة التي تبحث فيها عن ذلك المكان. ولمزيد من المعلومات، راجِع حفظ أرقام تعريف الأماكن لاستخدامها لاحقًا أدناه.

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

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

رقم تعريف المكان هو معرّف نصي يحدِّد مكانًا بشكلٍ فريد. في حزمة تطوير البرامج (SDK) للأماكن على جهاز 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