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

اختيار النظام الأساسي: Android iOS JavaScript خدمة الويب

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

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

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

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

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

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

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

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

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

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

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

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

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

      

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

      

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

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

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

ننصحك بإعادة تحميل أرقام تعريف الأماكن إذا كان عمرها أكثر من 12 شهرًا. يمكنك إعادة تحميل أرقام تعريف الأماكن بدون أي رسوم من خلال تقديم طلب تفاصيل المكان، مع تحديد الحقل Place.Field.ID فقط في معلَمة fields. تؤدي هذه المكالمة إلى تشغيل رمز التخزين التعريفي تفاصيل الأماكن - إعادة تحميل رقم التعريف رمز التخزين التعريفي.

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

ملاحظة: في الأيام القليلة الأولى بعد أن يصبح رقم تعريف المكان غير صالح، قد تستمر هذه الاستراتيجية في تحقيق 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