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

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

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

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

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

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

نظرة عامة

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

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

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

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

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

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

مثال باستخدام حزمة تطوير برامج الأماكن لنظام التشغيل Android

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

للوصول إلى مكان من خلال رقم التعريف، يُرجى الاتصال بالرقم PlacesClient.fetchPlace() مع تمرير FetchPlaceRequest.

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

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

// 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")
        }
    }

      

// 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.
    }
});

      

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

يتم إعفاء معرّفات الأماكن من قيود التخزين المؤقت المنصوص عليها في الفقرة 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