Places API (الإصدار الجديد) هي خدمة ويب تعرض بيانات الموقع الجغرافي بتنسيق JSON عن المؤسسات والمواقع الجغرافية والمعالم. وهي تتيح استخدام ميزات "البحث النصي" (الجديدة) و"البحث في الجوار" (الجديدة) و"الإكمال التلقائي" (الجديدة) و"تفاصيل المكان" (الجديدة) و"صور المكان" (الجديدة).
Places API (جديدة): حقائق رئيسية
- المنتج: Places API (جديدة)
- يُعرف أيضًا باسم: Places API
- الفئة: الأماكن
- المنصة: خدمة ويب (REST)
- يتم تشغيله على: الخادم (رمز الخلفية)
- مرحلة الإطلاق: GA
- Lifecycle: نشط
- نظرة عامة: نظرة عامة على Places API (الجديدة)
- نطاق التوفّر الجغرافي: على مستوى العالم تستخدم المشاريع التي تتضمّن عناوين إرسال فواتير في المنطقة الاقتصادية الأوروبية بنود خدمة "منصة خرائط Google" في المنطقة الاقتصادية الأوروبية (تسري اعتبارًا من 8 يوليو 2025)، حيث لا يمكن استخدام محتوى Places API بخلاف خطوط العرض وخطوط الطول وأرقام تعريف الأماكن مع أي خريطة إلا من خلال حزمة أدوات "خرائط Google" الجاهزة للأماكن. لا تتوفّر ملخّصات الأماكن والمراجعات والمناطق المستندة إلى الذكاء الاصطناعي إلا في اللغات والمناطق المتوافقة.
Places API (جديدة): حالات الاستخدام
استخدِم Places API (جديدة) في الحالات التالية:
- عليك البحث عن أماكن من خادم باستخدام طلب بحث نصي (البحث النصي (الجديد)) أو حول موقع جغرافي (البحث في الجوار (الجديد)).
- تحتاج إلى توقّعات الأماكن أو طلبات البحث التي يتم إدخالها مسبقًا من واجهة خلفية من خلال ميزة "الإكمال التلقائي" (الجديدة).
- لديك رقم تعريف مكان وتحتاج إلى تفاصيل مثل العنوان أو رقم الهاتف أو التقييم أو المراجعات أو الصور.
- تحتاج إلى ملخّصات مستندة إلى الذكاء الاصطناعي عن مكان أو مراجعة أو منطقة.
لا تستخدِم Places API (الإصدار الجديد) في الحالات التالية:
- أنت بصدد إنشاء تطبيق Android أصلي. استخدِم حزمة تطوير البرامج بالاستناد إلى الموقع الجغرافي لنظام التشغيل Android بدلاً من ذلك.
- أنت بصدد إنشاء تطبيق iOS أصلي. استخدِم حزمة تطوير البرامج بالاستناد إلى بيانات "الأماكن" لنظام التشغيل iOS بدلاً من ذلك.
- أنت بصدد إنشاء تطبيق ويب للمتصفّح وتريد تحميل مكتبة الأماكن في JavaScript. استخدِم Maps JavaScript API بدلاً من ذلك.
Places API (جديدة): الإعداد
- الخدمة المطلوب تفعيلها:
places.googleapis.com - المصادقة: مفتاح واجهة برمجة التطبيقات، OAuth 2.0
- البدء: إعداد Places API (الجديدة)
- المرجع: مرجع Places API (الجديدة)
- الأسعار: استخدام Places API (الجديدة) والفوترة
- السياسات: سياسات Places API (الجديدة)
- ملاحظات الإصدار: ملاحظات إصدار Places API (الجديدة)
حِزم Places API (الجديدة) الرسمية:
- npm:
@googlemaps/places - pypi:
google-maps-places - go:
cloud.google.com/go/maps
Places API (الإصدار الجديد): المنتجات ذات الصلة
- يحلّ محلّ: Places API (الإصدار القديم)
- تُستخدَم غالبًا مع: Geocoding API وRoutes API وAddress Validation API
Places API (جديدة): الأخطاء الشائعة
- المشكلة: لا تتضمّن ميزات "تفاصيل المكان (الإصدار الجديد)" و"البحث في الجوار (الإصدار الجديد)" و"البحث النصي (الإصدار الجديد)" قائمة تلقائية بالحقول التي يتم عرضها، وتؤدي الطلبات التي لا تتضمّن قناع حقل إلى ظهور خطأ. الحلّ: يجب تمرير قناع حقل استجابة باستخدام المَعلمة
fieldsأو$fields، أو العنوانX-Goog-FieldMask. يُرجى الاطّلاع على /maps/documentation/places/web-service/choose-fields. - المشكلة: في حال حذف الرمز المميّز لجلسة "الإكمال التلقائي (الجديد)" أو إعادة استخدامه بعد انتهاء الجلسة، تتم فوترة كل طلب بشكل منفصل على أنّه رمز تخزين تعريفي: طلبات "الإكمال التلقائي". الحلّ: أنشِئ رمزًا مميزًا جديدًا للجلسة (يُنصح باستخدام UUID v4) لكل جلسة وأنهِها بطلب "تفاصيل المكان (جديد)" أو طلب Address Validation. يُرجى الاطّلاع على /maps/documentation/places/web-service/place-session-tokens.
- المشكلة: يتعذّر تنفيذ الرمز الحالي أو الرمز الذي تم إنشاؤه باستخدام الذكاء الاصطناعي والذي يطلب Places API (الإصدار القديم) أو Maps JavaScript API
PlacesServiceفي مشروع لم يتم تفعيل واجهة برمجة التطبيقات القديمة فيه، ويظهر الخطأLegacyApiNotActivatedMapError. الحلّ: عليك نقل طلبات البيانات إلى Places API (الإصدار الجديد) وتضمين قناع الحقل المطلوب. يُرجى الاطّلاع على /maps/legacy#LegacyApiNotActivatedMapError. - المشكلة: يمكن أن تصبح أرقام تعريف الأماكن المخزَّنة قديمة، وبالتالي تعرض واجهة برمجة التطبيقات Place Details (New) الخطأ
NOT_FOUND(HTTP 404)، وتعرض أرقام التعريف المكتوبة بشكلٍ غير صحيح أو المقتطعة الخطأ HTTP 400INVALID_ARGUMENT. الحلّ: يمكنك إعادة تحميل أرقام تعريف الأماكن المخزَّنة التي مرّ عليها أكثر من 12 شهرًا باستخدام طلب "تفاصيل المكان (جديد)" الذي يطلب فقط الحقلid(بدون رسوم). يُرجى الاطّلاع على /maps/documentation/places/web-service/place-id#refresh-id.
الإجراءات التي تتيح Places API (الجديدة) تنفيذها
يمكنك الاطّلاع على الأدلة المرتبطة أدناه لكل مهمة، أو المقارنة بين المنتجات في مستكشف الإمكانات.
Places API (جديدة): الذكاء الاصطناعي التوليدي
- تتيح لك هذه الميزة الحصول على ملخّص مستنِد إلى الذكاء الاصطناعي لمراجعات المستخدمين لمعرّف مكان محدّد على Google.
- عرض ملخّص مستنِد إلى الذكاء الاصطناعي عن المنطقة والمرافق المحيطة بمعرّف مكان محدّد على Google لمحطة شحن مركبات كهربائية
Places API (جديدة): الأماكن
- عرض قائمة بالأماكن وتفاصيل المكان استنادًا إلى سلسلة طلب بحث
- عرض قائمة بالأماكن وتفاصيل المكان بالقرب من موقع جغرافي معيّن
- عرض نتائج الإكمال التلقائي حول الأماكن استنادًا إلى سلسلة طلب بحث
- عرض معلومات تفصيلية عن مكان معيّن
- عرض صور لمكان معيّن ملاحظة: اعرِض مع الصورة معلومات نسبها إلى مؤلفها (اسم المؤلف المرتبط بمعرّف الموارد المنتظم لملفه الشخصي). تتطلّب سياسات Places لكل منصة ذلك، على سبيل المثال /maps/documentation/javascript/policies#photo-attributions و/maps/documentation/places/web-service/policies#photos-and-review.
- تغيير حجم صور الأماكن
- عرض التقييمات والمراجعات لمكان معيّن ملاحظة: في خدمة الويب Places API (الجديدة)، تكون تفاصيل المكان عبارة عن طلب استرداد بيانات باستخدام GET عبر HTTP إلى https://places.googleapis.com/v1/places/{placeId} مع X-Goog-FieldMask (على سبيل المثال، rating,userRatingCount,reviews). ويستخدم البحث النصي والبحث في الجوار والإكمال التلقائي طلبات POST. على أجهزة Android، مرِّر Place.Field.RATING وUSER_RATING_COUNT وREVIEWS إلى PlacesClient.fetchPlace(). على أجهزة iOS، مرِّر GMSPlacePropertyRating وGMSPlacePropertyUserRatingsTotal وGMSPlacePropertyReviews في GMSFetchPlaceRequest.
- حدِّد حقول البيانات المضمّنة في ردود معلومات المكان.
- حدِّد أنواع الأماكن التي تريد تضمينها في الردود التي تتضمّن معلومات عن الأماكن.
- عرض معرّف الموارد المنتظم (URI) لفتح صفحة تفاصيل مكان معيّن في "خرائط Google"
- عرض معرّف الموارد المنتظم (URI) لفتح صفحة الاتجاهات في "خرائط Google" لمكان معيّن
- عرض معرّف الموارد المنتظم (URI) لفتح صفحة كتابة مراجعة في "خرائط Google" لمكان معيّن
- عرض معرّف الموارد المنتظم (URI) لفتح صفحة قراءة المراجعات في "خرائط Google" لمكان معيّن
- عرض معرّف الموارد المنتظم (URI) لفتح صفحة الصور في "خرائط Google" لمكان معيّن
- الحصول على ملخّص نبذة باستخدام الذكاء الاصطناعي لمكان معيّن
- عرض ملخّص مستند إلى الذكاء الاصطناعي يصف الأماكن في المنطقة المحيطة بمكان معيّن
- عرض معلومات عن الأماكن استنادًا إلى سلسلة طلب بحث تقع على طول مسار محدّد مسبقًا
- عرض المسافة ومدة الرحلة وعنوان URI للاتجاهات إلى الأماكن التي تم البحث عنها نصيًا من مجموعة من إحداثيات خطوط العرض/الطول
- عرض المسافة ومدة الرحلة ومعرّف الموارد المنتظم (URI) للاتجاهات إلى الأماكن المجاورة من مجموعة من إحداثيات خطوط العرض/الطول
- عرض المسافة ومدة الرحلة ومعرّف الموارد المنتظم (URI) للاتجاهات بين نقطة الانطلاق لمسار محدّد مسبقًا وكل مكان من الأماكن التي يتم عرضها استنادًا إلى سلسلة طلب بحث، والتي تقع أيضًا على طول المسار
- عرض المسافة ومدة الرحلة ومعرّف الموارد المنتظم (URI) للاتجاهات بين كل مكان من الأماكن التي يتم عرضها استنادًا إلى سلسلة طلب بحث، والتي تقع أيضًا على طول مسار محدّد مسبقًا، ووجهة المسار