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

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

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

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

البحث عن رقم تعريف مكان معيّن

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

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

نظرة عامة

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

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

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

يمكنك استخدام معرّف المكان نفسه في Places API وعدد من واجهات برمجة تطبيقات منصة خرائط Google. على سبيل المثال، يمكنك استخدام رقم تعريف المكان نفسه للإشارة إلى مكان في Places API وMaps JavaScript API وGeocoding API وMaps Embed API وRoads API.

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

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

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

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

للحصول على مكان باستخدام رقم التعريف، يمكنك استدعاء GMSPlacesClient fetchPlaceFromPlaceID:، مع إدخال المَعلمات التالية:

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

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

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. وتتمثّل إحدى الإستراتيجيات في تخزين الطلب الأصلي الذي عرض كل رقم تعريف مكان. إذا أصبح رقم تعريف المكان غير صالح، يمكنك إعادة إصدار هذا الطلب للحصول على نتائج حديثة. وقد تتضمّن هذه النتائج المكان الأصلي أو لا تتضمّنه. ومع ذلك، يمكن تحصيل رسوم من هذا الطلب.

ملاحظة: في الأيام القليلة الأولى بعد أن يصبح رقم تعريف المكان غير صالح، قد تستمر هذه الاستراتيجية في تحقيق 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