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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
اختَر النظام الأساسي: Android iOS JavaScript خدمة الويب

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

  • استرداد عنوان لمعرّف المكان في خدمة الويب Geocoding API على الويب وخدمة Geocoding API، وMaps JavaScript API.
  • تحديد نقطة الانطلاق والوجهة ونقاط الطريق الوسيطة في خدمة الويب Directions API وخدمة الاتجاهات وMaps JavaScript API.
  • تحديد مصادر الوجهات ووجهاتها في خدمة ويب لمصفوفة المسافة وواجهة برمجة تطبيقات مصفوفة المسافة و"واجهة برمجة تطبيقات JavaScript" للخرائط
  • جارٍ استرداد تفاصيل المكان في خدمة ويب Places API و Places Places for Android و Places Places for iOS و Places Library وJavaScript API
  • استخدام معلمات رقم تعريف المكان في واجهة برمجة تطبيقات تضمين الخرائط.
  • استرداد طلبات البحث في عناوين URL للخرائط
  • يتم عرض حدود السرعة في Roads API.
  • العثور على مضلعات الحدود وتصميمها في نمط مستند إلى البيانات.

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

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

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

نظرة عامة

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

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

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

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

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

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

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

مثال باستخدام حزمة تطوير البرامج (SDK) لأماكن Android

في حزمة تطوير البرامج (SDK) الخاصة بالأماكن لجهاز Android، يمكنك استرداد رقم تعريف المكان من خلال الاتصال Place.getId(). تعرض خدمة الإكمال التلقائي أيضًا رقم تعريف مكان لكل مكان يتطابق مع طلب البحث والفلتر الذي تم توفيره. استخدِم رقم تعريف المكان لاسترداد الكائن Place مرة أخرى لاحقًا.

للحصول على مكان حسب رقم التعريف، اطلب PlacesClient.fetchPlace()، مع تمرير FetchPlaceRequest.

تعرض واجهة برمجة التطبيقات FetchPlaceResponse في Task. يحتوي العنصر FetchPlaceResponse على عنصر Place يتطابق مع رقم تعريف المكان المقدَّم.

يوضّح مثال الرمز التالي الاتصال بـ fetchPlace() للحصول على تفاصيل المكان المحدّد.

Java


// Define a Place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Construct a request object, passing the place ID and fields array.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

placesClient.fetchPlace(request).addOnSuccessListener((response) -> {
    Place place = response.getPlace();
    Log.i(TAG, "Place found: " + place.getName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
        final ApiException apiException = (ApiException) exception;
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

      

Kotlin


// Define a Place ID.
val placeId = "INSERT_PLACE_ID_HERE"

// Specify the fields to return.
val placeFields = listOf(Place.Field.ID, Place.Field.NAME)

// Construct a request object, passing the place ID and fields array.
val request = FetchPlaceRequest.newInstance(placeId, placeFields)

placesClient.fetchPlace(request)
    .addOnSuccessListener { response: FetchPlaceResponse ->
        val place = response.place
        Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

      

حفظ أرقام تعريف الأماكن لاستخدامها لاحقًا

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

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

ننصح بإعادة تحميل معرّفات الأماكن إذا كان عمرها أكثر من 12 شهرًا. يمكنك إعادة تحميل أرقام تعريف الأماكن بدون أي رسوم، من خلال إنشاء طلب تفاصيل المكان، مع تحديد الحقل Place.Field.ID فقط في المَعلمة 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