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

اختيار النظام الأساسي: 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 Maps Platform. على سبيل المثال، يمكنك استخدام معرّف المكان نفسه للإشارة إلى مكان في Places API وMaps JavaScript API وGeocoding API وMaps Embed API وRoads API.

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

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

مثال على استخدام حزمة تطوير البرامج Places SDK for iOS

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

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

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

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

حزمة تطوير البرامج Places Swift لأجهزة 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 Maps Platform. وبالتالي، يمكنك تخزين قيم معرّفات الأماكن لاستخدامها لاحقًا.

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

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

يؤدي هذا الطلب إلى تشغيل رمز التخزين التعريفي Places Details - ID Refresh.

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

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