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

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

مقدمة

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

  • استرداد عنوان لرقم تعريف مكان في Geocoding API وخدمة الترميز الجغرافي وMaps JavaScript API
  • تحديد نقطة الانطلاق والوجهة ونقاط المسار الوسيطة في Routes API وDirections API (القديمة) وDirections Service وMaps JavaScript API (القديمة).
  • تحديد نقاط الانطلاق والوجهات في Routes API وDistance Matrix API (الإصدار القديم) وخدمة Distance Matrix وMaps JavaScript API (الإصدار القديم)
  • استرداد تفاصيل المكان في Places API (الإصدار الجديد) و"حزمة تطوير برامج الأماكن لأجهزة Android" (الإصدار الجديد) و"حزمة تطوير برامج الأماكن لأجهزة iOS" (الإصدار الجديد) و"مكتبة الأماكن"
  • استخدام مَعلمات رقم تعريف المكان في 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 أو مكتبة الأماكن في Maps JavaScript API. بعد ذلك، استخدِم رقم تعريف المكان الذي تم عرضه لاسترداد تفاصيل المكان. يمكنك تخزين رقم تعريف المكان واستخدامه لاسترداد تفاصيل المكان نفسه لاحقًا. يمكنك الاطّلاع على مزيد من المعلومات عن حفظ أرقام تعريف الأماكن لاحقًا في هذا المستند.

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

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

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

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

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

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

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

بما أنّ أرقام تعريف الأماكن قد تتغيّر بسبب التعديلات على قاعدة بيانات "خرائط 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