مرجع سريع حول Places API (الإصدار الجديد)

‫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 (الإصدار الجديد) في الحالات التالية:

‫Places API (جديدة): الإعداد

حِزم Places API (الجديدة) الرسمية:

  • npm: @googlemaps/places
  • pypi: google-maps-places
  • go: cloud.google.com/go/maps

‫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 400 INVALID_ARGUMENT. الحلّ: يمكنك إعادة تحميل أرقام تعريف الأماكن المخزَّنة التي مرّ عليها أكثر من 12 شهرًا باستخدام طلب "تفاصيل المكان (جديد)" الذي يطلب فقط الحقل id (بدون رسوم). يُرجى الاطّلاع على /maps/documentation/places/web-service/place-id#refresh-id.

الإجراءات التي تتيح Places API (الجديدة) تنفيذها

يمكنك الاطّلاع على الأدلة المرتبطة أدناه لكل مهمة، أو المقارنة بين المنتجات في مستكشف الإمكانات.

‫Places API (جديدة): الذكاء الاصطناعي التوليدي

‫Places API (جديدة): الأماكن