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

اختيار النظام الأساسي: Android iOS JavaScript Web Service
المطوّرون في المنطقة الاقتصادية الأوروبية

مقدمة

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

  • استرداد عنوان لرقم تعريف مكان في Geocoding API وGeocoding Service وMaps JavaScript API
  • تحديد نقطة الانطلاق والوجهة والنقاط على المسار في Routes API وDirections API (الإصدار القديم) وDirections Service وMaps JavaScript API (الإصدار القديم)
  • تحديد نقاط الانطلاق والوجهات في Routes API وDistance Matrix API (الإصدار القديم) وخدمة Distance Matrix وMaps JavaScript API (الإصدار القديم)
  • استرداد تفاصيل المكان في Places API (جديد) وPlaces SDK لنظام التشغيل Android (جديد) وPlaces SDK لأجهزة iOS (جديد) وPlaces Library
  • استخدام مَعلمات رقم تعريف المكان في Maps Embed API
  • استرداد طلبات البحث في عناوين URL الخاصة بـ "خرائط Google"
  • عرض حدود السرعة في Roads API
  • العثور على مضلّعات الحدود وتصميمها في "التصميم المستند إلى البيانات" للحدود

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

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

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

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

من الطرق الشائعة لاستخدام أرقام تعريف الأماكن البحث عن مكان باستخدام Places API أو Places Library في Maps JavaScript API. بعد ذلك، استخدِم رقم تعريف المكان الذي تم عرضه لاسترداد تفاصيل المكان. يمكنك تخزين رقم تعريف المكان واستخدامه لاسترداد تفاصيل المكان نفسها لاحقًا. يمكنك الاطّلاع على مزيد من المعلومات عن حفظ أرقام تعريف الأماكن لاحقًا في هذا المستند.

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

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

للحصول على مكان حسب رقم التعريف، اتّصِل بـ GMSPlacesClient fetchPlaceFromPlaceID:، مع تمرير المَعلمات التالية:

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

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

حزمة تطوير البرامج Places Swift SDK لأجهزة iOS

// Initialize Places Swift Client.
let placesClient = PlacesClient.shared

// A hotel in Saigon with an attribution
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
    
// Fetch Place Request.
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.displayName]
)
    
Task {
  switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
  case .success(let place):
    print("The selected place is: \(place.displayName): \(String(describing: place.description))")
  case .failure(let placesError):
    print("Place not found: \(placeID); \(placesError)")
  }
}

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". وبالتالي، يمكنك تخزين قيم أرقام تعريف الأماكن لاستخدامها لاحقًا.

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

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

يؤدي هذا الطلب إلى تفعيل رمز التخزين التعريفي تفاصيل الأماكن - إعادة تحميل المعرّف.

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

INVALID_REQUEST

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

NOT_FOUND

يشير رمز الحالة 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