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

اختيار النظام الأساسي: Android iOS JavaScript Web Service

المطوّرون في المنطقة الاقتصادية الأوروبية

إذا كان عنوان إرسال الفواتير الخاص بك يقع في المنطقة الاقتصادية الأوروبية، ستسري بنود خدمة "منصة خرائط Google" في المنطقة الاقتصادية الأوروبية على استخدامك للخدمات اعتبارًا من 8 تموز (يوليو) 2025. تختلف الوظائف حسب المنطقة. مزيد من المعلومات

مقدمة

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

• استرداد عنوان لرقم تعريف مكان في Geocoding API وGeocoding Service و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. بعد ذلك، استخدِم رقم تعريف المكان الذي تم عرضه لاسترداد تفاصيل المكان. يمكنك تخزين رقم تعريف المكان واستخدامه لاسترداد تفاصيل المكان نفسها لاحقًا. يمكنك الاطّلاع على معلومات حول حفظ أرقام تعريف الأماكن لاحقًا في هذا المستند.

مثال على استخدام حزمة تطوير البرامج Places SDK for Android (الإصدار الجديد)

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

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

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

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

Kotlin

// Define a Place ID.
val placeId = PlaceIdProvider.getRandomPlaceId()

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

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

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

        binding.placeName.text = name
        binding.placeAddress.text = address
        if (location != null) {
            binding.placeLocation.text = getString(
                R.string.place_location, location.latitude, location.longitude
            )
        } else {
            binding.placeLocation.text = null
        }
        Log.i(TAG, "Place found: ${place.displayName}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            val message = getString(R.string.place_not_found, exception.message)
            binding.placeName.text = message
            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 = PlaceIdProvider.getRandomPlaceId();

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

// 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();

    final CharSequence name = place.getDisplayName();
    final CharSequence address = place.getFormattedAddress();
    final LatLng location = place.getLocation();

    binding.placeName.setText(name);
    binding.placeAddress.setText(address);
    if (location != null) {
        binding.placeLocation.setText(
                getString(R.string.place_location, location.latitude, location.longitude)
        );
    } else {
        binding.placeLocation.setText(null);
    }

    Log.i(TAG, "Place found: " + place.getDisplayName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException apiException) {
        final String message = getString(R.string.place_not_found, apiException.getMessage());
        binding.placeName.setText(message);
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

      

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

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

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

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

يؤدي هذا الطلب إلى تشغيل رمز التخزين التعريفي تفاصيل الأماكن - إعادة تحميل المعرّف.

رموز الخطأ عند استخدام أرقام تعريف الأماكن

INVALID_REQUEST

يشير رمز الحالة INVALID_REQUEST إلى أنّ رقم تعريف المكان المحدّد غير صالح. قد يتم عرض INVALID_REQUEST عندما يتم اقتطاع رقم تعريف المكان أو تعديله بطريقة أخرى، ولم يعُد صحيحًا.

NOT_FOUND

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

ملاحظة: قد يستمر عرض أرقام تعريف الأماكن القديمة في الردود الصادرة عن الإكمال التلقائي للأماكن (الإصدار القديم) أو Query Autocomplete (الإصدار القديم) أو Autocomplete (الإصدار الجديد) لبضعة أيام بعد إزالة رقم تعريف المكان من قاعدة بيانات "خرائط Google".

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

قد تؤدي بعض أنواع أرقام تعريف الأماكن أحيانًا إلى ظهور الردّ NOT_FOUND، أو قد تعرض واجهة برمجة التطبيقات رقم تعريف مكان مختلفًا في الردّ. تشمل أنواع أرقام تعريف المكان هذه ما يلي:

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

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

EpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4