تضمين خريطة

يوضّح هذا الدليل كيفية تضمين خريطة تفاعلية في صفحة الويب.

إنشاء عنوان URL الخاص بـ Maps Embed API

في ما يلي مثال على عنوان URL يحمّل Maps Embed API:

https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS

استبدال:

إضافة عنوان URL إلى إطار iframe

لاستخدام Maps Embed API على صفحة الويب، اضبط عنوان URL الذي أنشأته كقيمة للسمة src الخاصة بإطار iframe. يمكنك التحكّم في حجم الخريطة باستخدام سمتَي height وwidth في iframe، على سبيل المثال:

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  referrerpolicy="strict-origin-when-cross-origin"
  src="https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS"
  allowfullscreen>
</iframe>

يستخدم نموذج iframe أعلاه الخصائص الإضافية التالية:

  • السمة allowfullscreen للسماح بعرض أجزاء معيّنة من الخريطة بملء الشاشة
  • السمتان frameborder="0" وstyle="border:0" لإزالة إطار iframe العادي من حول الخريطة
  • تضمن السمة referrerpolicy="strict-origin-when-cross-origin" أن يرسل المتصفّح نطاق موقعك الإلكتروني كعنوان Referer إلى Google. يتيح ذلك للقيود المفروضة على مفتاح واجهة برمجة التطبيقات التحقّق من صحة الطلب، مع الحفاظ على خصوصية مسارات الصفحات المحدّدة.

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

معلومات عن المصدر والقيود المفروضة على مفتاح واجهة برمجة التطبيقات

إذا كان الموقع الإلكتروني المضيف يتضمّن علامة وصفية referrer مضبوطة على no-referrer أو same-origin، لن يرسل المتصفّح العنوان Referer إلى Google. وقد يؤدي ذلك إلى رفض الطلبات بسبب القيود المفروضة على مفتاح واجهة برمجة التطبيقات. لكي يعمل هذا القيد بشكل صحيح، أضِف السمة referrerpolicy إلى إطار iframe، كما هو موضّح في المثال أعلاه، للسماح بشكل صريح بإرسال عناوين Referer إلى Google.

  • strict-origin-when-cross-origin (يُنصح به): يرسل هذا الخيار نطاقك الأساسي فقط (مثل https://example.com/) إلى Google. يؤدي ذلك إلى إبقاء مسارات صفحاتك المحدّدة خاصة مع السماح في الوقت نفسه بعمل قيود مفتاح واجهة برمجة التطبيقات.
  • no-referrer-when-downgrade (إصدار قديم): يرسل عنوان URL الكامل، بما في ذلك مسارات الصفحات المحدّدة ومَعلمات طلب البحث (مثلاً، https://example.com/contact?user=123).

مزيد من المعلومات حول العنوان Referrer-Policy

اختيار أوضاع الخريطة

يمكنك تحديد أحد أوضاع الخريطة التالية لاستخدامه في عنوان URL للطلب:

  • place: تعرض دبوس خريطة في مكان أو عنوان معيّنَين، مثل معلَم أو نشاط تجاري أو ميزة جغرافية أو بلدة.
  • ‫view: تعرض خريطة بدون علامات أو اتجاهات.
  • directions: تعرض هذه السمة المسار بين نقطتَين أو أكثر محدّدة على الخريطة، بالإضافة إلى المسافة ووقت السفر.
  • ‫streetview: تعرض هذه السمة مناظر بانورامية تفاعلية من مواقع جغرافية محددة.
  • ‫search: تعرض نتائج بحث في منطقة الخريطة الظاهرة.

وضع place

يستخدم عنوان URL التالي وضع الخريطة place لعرض محدّد خريطة في &quot;برج إيفل&quot;:

https://www.google.com/maps/embed/v1/place
  ?key=YOUR_API_KEY
  &q=Eiffel+Tower,Paris+France

يمكنك استخدام المَعلمات التالية:

المَعلمة النوع الوصف القيم المقبولة
q مطلوب تحدّد هذه السمة الموقع الجغرافي لمحدّد الخريطة. اسم المكان أو عنوانه أو رمز Plus Code أو معرّف المكان مع إلغاء الترميز لعنوان URL تتوافق واجهة برمجة التطبيقات Maps Embed API مع كل من + و%20 عند إلغاء المسافات. على سبيل المثال، يمكنك تحويل "مبنى البلدية، نيويورك، نيويورك" إلى City+Hall,New+York,NY، أو رموز Plus Codes "849VCWC8+R9" إلى 849VCWC8%2BR9.
center اختياري تحدّد هذه السمة مركز عرض الخريطة. تقبل هذه السمة قيمتَي خط الطول وخط العرض مفصولتَين بفاصلة، على سبيل المثال: 37.4218,-122.0840.
zoom اختياري تضبط هذه السمة مستوى التكبير أو التصغير الأولي للخريطة. تتراوح القيم من 0 (العالم بأسره) إلى 21 (المباني الفردية). يمكن أن يختلف الحدّ الأقصى حسب بيانات الخريطة المتاحة في الموقع الجغرافي المحدّد.
maptype اختياري تحدّد هذه السمة نوع مربّعات الخريطة التي سيتم تحميلها. ‫roadmap (الإعداد التلقائي) أو satellite
language اختياري تحدّد هذه السمة اللغة التي سيتم استخدامها لعناصر واجهة المستخدم ولعرض التسميات على مربّعات الخريطة. سيشاهد الزوّار بشكل تلقائي خريطة بلغتهم. لا تتوفّر هذه المَعلمة إلا لبعض مربّعات البلدان. وإذا لم تكن اللغة المحدّدة المطلوبة متوافقة مع مجموعة المربّعات، سيتم استخدام اللغة التلقائية لهذه المجموعة.
region اختياري تحدّد هذه السمة الحدود والتصنيفات المناسبة للعرض، استنادًا إلى الحساسيات الجغرافية السياسية. يقبل رمز منطقة محدّدًا كعلامة فرعية للمنطقة من حرفين (غير رقميين) في يونيكود، ويتم ربطها بقيم من حرفين مألوفة لنطاق مستوى أعلى يتم ترميزه حسب البلد ("نطاق المستوى الأعلى"). يمكنك الاطّلاع على تفاصيل تغطية &quot;منصة خرائط Google&quot; لمعرفة المناطق المتاحة.

وضع view

يستخدم المثال التالي الوضع view والمعلَمة الاختيارية maptype لعرض خريطة القمر الصناعي:

https://www.google.com/maps/embed/v1/view
  ?key=YOUR_API_KEY
  &center=-33.8569,151.2152
  &zoom=18
  &maptype=satellite

يمكنك استخدام المَعلمات التالية:

المَعلمة النوع الوصف القيم المقبولة
center مطلوب تحدّد هذه السمة مركز عرض الخريطة. تقبل هذه السمة قيمتَي خط الطول وخط العرض مفصولتَين بفاصلة، على سبيل المثال: 37.4218,-122.0840.
zoom اختياري تضبط هذه السمة مستوى التكبير أو التصغير الأولي للخريطة. تتراوح القيم من 0 (العالم بأسره) إلى 21 (المباني الفردية). يمكن أن يختلف الحدّ الأقصى حسب بيانات الخريطة المتاحة في الموقع الجغرافي المحدّد.
maptype اختياري تحدّد هذه السمة نوع مربّعات الخريطة التي سيتم تحميلها. ‫roadmap (الإعداد التلقائي) أو satellite
language اختياري تحدّد هذه السمة اللغة التي سيتم استخدامها لعناصر واجهة المستخدم ولعرض التسميات على مربّعات الخريطة. سيشاهد الزوّار بشكل تلقائي خريطة بلغتهم. لا تتوفّر هذه المَعلمة إلا لبعض مربّعات البلدان. وإذا لم تكن اللغة المحدّدة المطلوبة متوافقة مع مجموعة المربّعات، سيتم استخدام اللغة التلقائية لهذه المجموعة.
region اختياري تحدّد هذه السمة الحدود والتصنيفات المناسبة للعرض، استنادًا إلى الحساسيات الجغرافية السياسية. يقبل رمز منطقة محدّدًا كعلامة فرعية للمنطقة من حرفين (غير رقميين) في يونيكود، ويتم ربطها بقيم من حرفين مألوفة لنطاق المستوى الأعلى لرمز البلد. يمكنك الاطّلاع على تفاصيل تغطية &quot;منصة خرائط Google&quot; لمعرفة المناطق المتاحة.

وضع directions

يستخدم المثال التالي وضع directions لعرض المسار بين أوسلو وتيليمارك في النرويج والمسافة بينهما ومدة الرحلة مع تجنُّب الطرق السريعة والطرق التي يتم فيها تحصيل رسوم.

https://www.google.com/maps/embed/v1/directions
  ?key=YOUR_API_KEY
  &origin=Oslo+Norway
  &destination=Telemark+Norway
  &avoid=tolls|highways

يمكنك استخدام المَعلمات التالية:

المَعلمة النوع الوصف القيم المقبولة
origin مطلوب تحدّد هذه السمة نقطة البداية التي سيتم عرض الاتجاهات منها. اسم المكان أو عنوانه أو الرمز الإضافي أو إحداثيات خطوط الطول والعرض أو معرّف المكان، مع ترميز عنوان URL تتوافق واجهة برمجة التطبيقات Maps Embed API مع كل من + و%20 عند إلغاء المسافات. على سبيل المثال، يمكنك تحويل "مبنى البلدية، نيويورك، نيويورك" إلى City+Hall,New+York,NY، أو رموز Plus Codes "849VCWC8+R9" إلى 849VCWC8%2BR9.
destination مطلوب تحدّد هذه السمة نقطة نهاية الاتجاهات. اسم المكان أو عنوانه أو الرمز الإضافي أو إحداثيات خطوط الطول والعرض أو معرّف المكان، مع ترميز عنوان URL تتوافق واجهة برمجة التطبيقات Maps Embed API مع كل من + و%20 عند إلغاء المسافات. على سبيل المثال، يمكنك تحويل "مبنى البلدية، نيويورك، نيويورك" إلى City+Hall,New+York,NY، أو رموز Plus Codes "849VCWC8+R9" إلى 849VCWC8%2BR9.
waypoints اختياري تحدّد هذه السمة مكانًا وسيطًا واحدًا أو أكثر لتوجيه الاتجاهات بين نقطة الانطلاق والوجهة. اسم المكان أو عنوانه أو معرّف المكان يمكن تحديد نقاط طريق متعدّدة باستخدام رمز الشرطة الرأسية (|) للفصل بين الأماكن (مثلاً Berlin,Germany|Paris,France). يمكنك تحديد ما يصل إلى 20 نقطة طريق.
mode اختياري تحدّد هذه السمة طريقة السفر. في حال عدم تحديد وسيلة نقل، ستعرض واجهة Maps Embed API وسيلة نقل واحدة أو أكثر من وسائل النقل الأكثر ملاءمةً للمسار المحدّد. driving أو walking (الذي يفضّل المسارات المخصّصة للمشاة والأرصفة، إذا كانت متاحة) أو bicycling (الذي يفضّل المسارات التي تستخدم الطرق المخصّصة للدراجات والشوارع المفضّلة، إذا كانت متاحة) أو transit أو flying
avoid اختياري تحدّد هذه السمة الميزات التي يجب تجنُّبها في الاتجاهات. يُرجى العِلم أنّ هذا لا يستبعد المسارات التي تتضمّن الميزات المحظورة، بل يرجّح النتيجة لصالح المسارات الأكثر ملاءمة. tolls و/أو ferries و/أو highways يجب الفصل بين القيم المتعددة باستخدام حرف التوجيه (على سبيل المثال، avoid=tolls|highways).
units اختياري تحدّد هذه السمة طريقة القياس، سواء كانت مترية أو إنجليزية، عند عرض المسافات في النتائج. في حال عدم تحديد units، يحدّد بلد origin في طلب البحث الوحدات التي سيتم استخدامها. metric أو imperial
center اختياري تحدّد هذه السمة مركز عرض الخريطة. تقبل هذه السمة قيمتَي خط الطول وخط العرض مفصولتَين بفاصلة، على سبيل المثال: 37.4218,-122.0840.
zoom اختياري تضبط هذه السمة مستوى التكبير أو التصغير الأولي للخريطة. تتراوح القيم من 0 (العالم بأسره) إلى 21 (المباني الفردية). يمكن أن يختلف الحدّ الأقصى حسب بيانات الخريطة المتاحة في الموقع الجغرافي المحدّد.
maptype اختياري تحدّد هذه السمة نوع مربّعات الخريطة التي سيتم تحميلها. ‫roadmap (الإعداد التلقائي) أو satellite
language اختياري تحدّد هذه السمة اللغة التي سيتم استخدامها لعناصر واجهة المستخدم ولعرض التسميات على مربّعات الخريطة. سيشاهد الزوّار بشكل تلقائي خريطة بلغتهم. لا تتوفّر هذه المَعلمة إلا لبعض مربّعات البلدان. وإذا لم تكن اللغة المحدّدة المطلوبة متوافقة مع مجموعة المربّعات، سيتم استخدام اللغة التلقائية لهذه المجموعة.
region اختياري تحدّد هذه السمة الحدود والتصنيفات المناسبة للعرض، استنادًا إلى الحساسيات الجغرافية السياسية. يقبل رمز منطقة محدّدًا كعلامة فرعية للمنطقة من حرفين (غير رقميين) في يونيكود، ويتم ربطها بقيم من حرفين مألوفة لنطاق مستوى أعلى يتم ترميزه حسب البلد ("نطاق المستوى الأعلى"). يمكنك الاطّلاع على تفاصيل تغطية &quot;منصة خرائط Google&quot; لمعرفة المناطق المتاحة.

وضع streetview

تتيح لك Maps Embed API عرض صور &quot;التجوّل الافتراضي&quot; كصور بانورامية تفاعلية من مواقع جغرافية محدّدة في جميع أنحاء منطقة التغطية. تتوفّر أيضًا صور Photosphere التي يساهم بها المستخدمون ومجموعات "التجوّل الافتراضي" الخاصة.

تقدّم كل صورة بانورامية في &quot;التجوّل الافتراضي&quot; عرضًا كاملاً بزاوية 360 درجة من موقع جغرافي واحد. تحتوي الصور على عرض أفقي بزاوية 360 درجة (تغطية كاملة) وعرض عمودي بزاوية 180 درجة (من الأعلى إلى الأسفل). يوفّر الوضع streetview عارضًا يعرض البانوراما الناتجة على شكل كرة في مركزها كاميرا. يمكنك التحكّم في الكاميرا لضبط التكبير والاتجاه.

انظر إلى بانوراما وضع streetview التالية:

https://www.google.com/maps/embed/v1/streetview
  ?key=YOUR_API_KEY
  &location=46.414382,10.013988
  &heading=210
  &pitch=10
  &fov=35

يجب توفُّر إحدى مَعلمات عناوين URL التالية:

  • تقبل location خط عرض وخط طول كقيم مفصولة بفواصل (46.414382,10.013988). تعرض واجهة برمجة التطبيقات الصورة البانورامية التي تم التقاطها بالقرب من هذا الموقع الجغرافي. بما أنّ صور &quot;التجوّل الافتراضي&quot; يتم تجديدها بشكل دوري، وقد يتم التقاط الصور من مواضع مختلفة قليلاً في كل مرة، من المحتمل أن يتم نقل موقعك الجغرافي إلى صورة بانورامية مختلفة عند تعديل الصور.

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

معلَمات عناوين URL التالية اختيارية:

المَعلمة النوع الوصف القيم المقبولة
heading اختياري تشير هذه السمة إلى اتجاه البوصلة للكاميرا بالدرجات في اتجاه عقارب الساعة من الشمال. قيمة بالدرجات من ‎-180° إلى ‎360°
pitch اختياري تحدّد هذه السمة زاوية الكاميرا، سواء كانت متجهة للأعلى أو للأسفل. ستؤدي القيم الموجبة إلى إمالة الكاميرا للأعلى، بينما ستؤدي القيم السالبة إلى إمالة الكاميرا للأسفل. يتم ضبط درجة الميل التلقائية البالغة 0 درجة استنادًا إلى موضع الكاميرا عند التقاط الصورة. لهذا السبب، يكون الميل بمقدار 0 درجة أفقيًا في أغلب الأحيان، ولكن ليس دائمًا. على سبيل المثال، من المرجّح أن تعرض صورة تم التقاطها على تلّ زاوية ميل تلقائية غير أفقية. قيمة بالدرجات من ‎-90° إلى ‎90°
fov اختياري تحدّد مجال الرؤية الأفقي للصورة. القيمة التلقائية هي 90 درجة. عند التعامل مع إطار عرض ثابت الحجم، يمكن اعتبار مجال الرؤية مستوى التكبير/التصغير، حيث تشير الأرقام الأصغر إلى مستوى تكبير/تصغير أعلى. القيمة بالدرجات، مع نطاق من 10 إلى 100 درجة
center اختياري تحدّد هذه السمة مركز عرض الخريطة. تقبل هذه السمة قيمتَي خط الطول وخط العرض مفصولتَين بفاصلة، على سبيل المثال: 37.4218,-122.0840.
zoom اختياري تضبط هذه السمة مستوى التكبير أو التصغير الأولي للخريطة. تتراوح القيم من 0 (العالم بأسره) إلى 21 (المباني الفردية). يمكن أن يختلف الحدّ الأقصى حسب بيانات الخريطة المتاحة في الموقع الجغرافي المحدّد.
maptype اختياري تحدّد هذه السمة نوع مربّعات الخريطة التي سيتم تحميلها. ‫roadmap (الإعداد التلقائي) أو satellite
language اختياري تحدّد هذه السمة اللغة التي سيتم استخدامها لعناصر واجهة المستخدم ولعرض التسميات على مربّعات الخريطة. سيشاهد الزوّار بشكل تلقائي خريطة بلغتهم. لا تتوفّر هذه المَعلمة إلا لبعض مربّعات البلدان. وإذا لم تكن اللغة المحدّدة المطلوبة متوافقة مع مجموعة المربّعات، سيتم استخدام اللغة التلقائية لهذه المجموعة.
region اختياري تحدّد هذه السمة الحدود والتصنيفات المناسبة للعرض، استنادًا إلى الحساسيات الجغرافية السياسية. يقبل رمز منطقة محدّدًا كعلامة فرعية للمنطقة من حرفين (غير رقميين) في يونيكود، ويتم ربطها بقيم من حرفين مألوفة لنطاق مستوى أعلى يتم ترميزه حسب البلد ("نطاق المستوى الأعلى"). يمكنك الاطّلاع على تفاصيل تغطية &quot;منصة خرائط Google&quot; لمعرفة المناطق المتاحة.

وضع search

يعرض الوضع Search نتائج البحث في منطقة الخريطة المرئية. يُنصح بتحديد موقع جغرافي للبحث، إما من خلال تضمين موقع جغرافي في عبارة البحث (record+stores+in+Seattle) أو من خلال تضمين المَعلمتَين center وzoom لتحديد نطاق البحث.

https://www.google.com/maps/embed/v1/search
  ?key=YOUR_API_KEY
  &q=record+stores+in+Seattle

يمكنك استخدام المَعلمات التالية:

المَعلمة النوع الوصف القيم المقبولة
q مطلوب تحدّد هذه السمة عبارة البحث. يمكن أن يتضمّن ذلك قيودًا جغرافية، مثل in+Seattle أو near+98033.
center اختياري تحدّد هذه السمة مركز عرض الخريطة. تقبل هذه السمة قيمتَي خط الطول وخط العرض مفصولتَين بفاصلة، على سبيل المثال: 37.4218,-122.0840.
zoom اختياري تضبط هذه السمة مستوى التكبير أو التصغير الأولي للخريطة. تتراوح القيم من 0 (العالم بأسره) إلى 21 (المباني الفردية). يمكن أن يختلف الحدّ الأقصى حسب بيانات الخريطة المتاحة في الموقع الجغرافي المحدّد.
maptype اختياري تحدّد هذه السمة نوع مربّعات الخريطة التي سيتم تحميلها. ‫roadmap (الإعداد التلقائي) أو satellite
language اختياري تحدّد هذه السمة اللغة التي سيتم استخدامها لعناصر واجهة المستخدم ولعرض التسميات على مربّعات الخريطة. سيشاهد الزوّار بشكل تلقائي خريطة بلغتهم. لا تتوفّر هذه المَعلمة إلا لبعض مربّعات البلدان. وإذا لم تكن اللغة المحدّدة المطلوبة متوافقة مع مجموعة المربّعات، سيتم استخدام اللغة التلقائية لهذه المجموعة.
region اختياري تحدّد هذه السمة الحدود والتصنيفات المناسبة للعرض، استنادًا إلى الحساسيات الجغرافية السياسية. يقبل رمز منطقة محدّدًا كعلامة فرعية للمنطقة من حرفين (غير رقميين) في يونيكود، ويتم ربطها بقيم من حرفين مألوفة لنطاق المستوى الأعلى لرمز البلد. يمكنك الاطّلاع على تفاصيل تغطية &quot;منصة خرائط Google&quot; لمعرفة المناطق المتاحة.

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

تتيح واجهة برمجة التطبيقات Maps Embed API استخدام معرّفات الأماكن بدلاً من تقديم اسم مكان أو عنوان. توفّر أرقام تعريف الأماكن طريقة ثابتة لتحديد مكان بشكلٍ فريد. لمزيد من المعلومات، يُرجى الاطّلاع على مستندات Google Places API.

تقبل واجهة برمجة التطبيقات Maps Embed API معرّفات الأماكن لمعلمات عناوين URL التالية:

  • q
  • origin
  • destination
  • waypoints

لاستخدام معرّف مكان، عليك أولاً إضافة البادئة place_id:. يوضّح الرمز التالي أنّ نقطة البداية لطلب الاتجاهات هي &quot;قاعة مدينة نيويورك&quot;: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8.

  • يضبط radius نصف قطر، محدّدًا بالأمتار، يتم البحث فيه عن صورة بانورامية، مع توسيطها على خط الطول وخط العرض المحدّدَين. القيم الصالحة هي أعداد صحيحة غير سالبة. القيمة التلقائية هي 50.

  • تقتصر عمليات البحث في source على المصادر المحدّدة. القيم الصالحة هي:

    • يستخدم default المصادر التلقائية لـ &quot;التجوّل الافتراضي&quot;، ولا تقتصر عمليات البحث على مصادر معيّنة.
    • تقتصر عمليات البحث في outdoor على المجموعات الخارجية. لا يتم تضمين المجموعات الداخلية في نتائج البحث. يُرجى العِلم أنّه قد لا تتوفّر صور بانورامية خارجية للموقع الجغرافي المحدّد. يُرجى العِلم أيضًا أنّ البحث لا يعرض سوى الصور البانورامية التي يمكن تحديد ما إذا كانت في مكان مغلق أو مفتوح. على سبيل المثال، لا يتم عرض صور PhotoSphere لأنّه من غير المعروف ما إذا كانت في مكان مغلق أو مفتوح.