المرجع السريع لواجهة Maps Embed API

تضع Maps Embed API خريطة تفاعلية أو بانوراما في "التجوّل الافتراضي" على صفحة ويب من خلال طلب HTTP تم ضبطه كعنوان URL لإطار iframe‏ src، بدون الحاجة إلى JavaScript. وهو يتيح استخدام أوضاع الخريطة place وview وdirections وstreetview وsearch.

‫Maps Embed API: حقائق أساسية

  • المنتج: Maps Embed API
  • تُعرف أيضًا باسم: Google Maps Embed API وMaps Embed
  • الفئة: خرائط Google
  • المنصة: JavaScript (المتصفّح)
  • يعمل على: العميل (رمز التطبيق أو المتصفّح)
  • مرحلة الإطلاق: GA
  • Lifecycle: نشط
  • نظرة عامة: نظرة عامة على Maps Embed API
  • نطاق التوفّر الجغرافي: على مستوى العالم يعتمد وضع "التجوّل الافتراضي" على تغطية ميزة "التجوّل الافتراضي". تقبل المَعلمة region المناطق المدرَجة في صفحة تفاصيل التغطية في "منصة خرائط Google". (تفاصيل التغطية)

‫Maps Embed API: حالات الاستخدام

استخدِم Maps Embed API في الحالات التالية:

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

لا تستخدِم Maps Embed API في الحالات التالية:

  • تحتاج إلى تخصيص خريطة ويب باستخدام المحتوى والصور الخاصة بك. استخدِم Maps JavaScript API بدلاً من ذلك.
  • تحتاج إلى توسيع خريطة مضمّنة باستخدام ميزات برمجية تتجاوز مَعلمات عنوان URL لإطار iframe. استخدِم Maps JavaScript API بدلاً من ذلك.

‫Maps Embed API: الإعداد

Maps Embed API: الأخطاء الشائعة

  • المشكلة: إذا ضبطت الصفحة المضيفة علامة وصفية referrer على no-referrer أو same-origin، لن يرسل المتصفّح العنوان Referer، ويمكن لمفتاح واجهة برمجة التطبيقات المقيّد بمرجع HTTP رفض طلبات التضمين. الحلّ: أضِف referrerpolicy="strict-origin-when-cross-origin" إلى إطار iframe ليتم إرسال نطاق الموقع الإلكتروني إلى Google. يُرجى الاطّلاع على /maps/documentation/embed/embedding-map.
  • المشكلة: لا تتوفّر الخرائط المضمّنة بأبعاد أقل من 200 بكسل. الحلّ: اضبط السمتَين width وheight في iframe على 200 بكسل على الأقل. يُرجى الاطّلاع على /maps/documentation/embed/embedding-map.
  • المشكلة: على الرغم من أنّ الاستخدام بدون أي رسوم، تظهر خريطة داكنة تحمل علامة مائية "لأغراض التطوير فقط" في حال عدم تفعيل الفوترة أو إذا كانت طريقة الدفع غير صالحة أو تم تجاوز الحدّ اليومي الذي فرضته بنفسك أو إذا كان الطلب لا يتضمّن مُحيل HTTP أثناء استخدام مفتاح مقيّد بالمُحيل. الحلّ: فعِّل الفوترة باستخدام طريقة دفع صالحة في المشروع، وارفع أي حدّ مفروض ذاتيًا على الحصة اليومية أو أزِله، وتأكَّد من إرسال المُحيل للمفاتيح المحظورة من قِبل المُحيل (على سبيل المثال، باستخدام referrerpolicy="strict-origin-when-cross-origin" في إطار iframe). يُرجى الاطّلاع على /maps/documentation/embed/error-messages.
  • المشكلة: بالنسبة إلى الطلبات غير الصالحة (المَعلمات غير الصالحة أو غير المتوفّرة، وأخطاء مفتاح واجهة برمجة التطبيقات والحصة، مثل مفتاح غير متوفّر أو غير صالح، أو عدم تفعيل Maps Embed API، أو مخالفة قيود المفتاح)، يتم الإبلاغ عن رمز حالة HTTP 4xx فقط في وحدة تحكّم المتصفّح، وليس رسالة وصفية، ويظهر نص الخطأ داخل إطار iframe بدلاً من الخريطة. الحلّ: اقرأ نص الخطأ في إطار iframe ورمز حالة وحدة التحكّم (400 لأخطاء المَعلمات، و401 لمفتاح مفقود، و403 لمفتاح غير صالح)، ثم تأكَّد من أنّ المَعلمات صالحة، والمفتاح صالح، وواجهة برمجة التطبيقات Maps Embed API مفعَّلة، وقيود المفتاح تسمح بالطلب. يُرجى الاطّلاع على /maps/documentation/embed/error-messages.

الإجراءات التي تتيح Maps Embed API تنفيذها

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

‫Maps Embed API: الاتجاهات والمسارات

Maps Embed API: الخرائط

‫Maps Embed API: الأماكن

‫Maps Embed API: ميزة "التجوّل الافتراضي"