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

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

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

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

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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

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

      

// 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