تضمين خريطة

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

إنشاء عنوان URL لواجهة برمجة التطبيقات Maps Embed API

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

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

استبدال:

• MAP_MODE باستخدام وضع الخريطة.
• 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 لعرض محدّد خريطة في "برج إيفل":

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" إلى City+Hall,New+York,NY، أو رمز Plus Code‏ "849VCWC8+R9" إلى 849VCWC8%2BR9.
center	اختياري	يحدّد مركز عرض الخريطة.	تقبل هذه السمة قيمة خط العرض وخط الطول مفصولة بفاصلة، على سبيل المثال: 37.4218,-122.0840.
zoom	اختياري	يضبط مستوى التكبير الأولي للخريطة.	تتراوح القيم من 0 (العالم بأكمله) إلى 21 (المباني الفردية). ويمكن أن يختلف الحدّ الأقصى حسب بيانات الخريطة المتاحة في الموقع الجغرافي المحدّد.
maptype	اختياري	تحدّد نوع مربّعات الخريطة المطلوب تحميلها.	‫roadmap (تلقائي) أو satellite
language	اختياري	تحدّد هذه السمة اللغة التي سيتم استخدامها لعناصر واجهة المستخدم ولعرض التصنيفات على مربّعات الخريطة. بشكل تلقائي، سيظهر للزوّار خريطة بلغتهم. لا تتوفّر هذه المَعلمة إلا لبعض مربّعات البلدان. إذا كانت اللغة المحدّدة المطلوبة غير متاحة لمجموعة المربّعات، سيتم استخدام اللغة التلقائية لمجموعة المربّعات هذه.
region	اختياري	يحدّد الحدود والتصنيفات المناسبة التي يجب عرضها، استنادًا إلى الحساسيات الجغرافية السياسية.	تقبل هذه السمة رمز منطقة محدّدًا كعلامة فرعية للمنطقة في يونيكود تتألف من حرفَين (غير رقميَّين) وتتوافق مع قيم مألوفة من حرفَين لنطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD). يُرجى الاطّلاع على تفاصيل تغطية "منصة خرائط Google" لمعرفة المناطق المعتمدة.

وضع 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	اختياري	يحدّد الحدود والتصنيفات المناسبة التي يجب عرضها، استنادًا إلى الحساسيات الجغرافية السياسية.	تقبل هذه السمة رمز منطقة محدّدًا كعلامة فرعية للمنطقة في يونيكود تتألف من حرفَين (غير رقميَّين) وتتوافق مع قيم مألوفة من حرفَين لنطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD). يُرجى الاطّلاع على تفاصيل تغطية "منصة خرائط Google" لمعرفة المناطق المعتمدة.

وضع directions

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

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

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

المَعلمة	النوع	الوصف	القيم المقبولة
origin	مطلوب	تحدّد نقطة البداية التي سيتم عرض الاتجاهات منها.	اسم المكان أو العنوان أو رمز Plus Code أو إحداثيات خطوط العرض/الطول أو رقم تعريف المكان، مع إلغاء ترميز عنوان URL. تتيح Maps Embed API استخدام كل من + و%20 عند إلغاء المسافات. على سبيل المثال، يمكنك تحويل "City Hall, New York, NY" إلى City+Hall,New+York,NY، أو رمز Plus Code‏ "849VCWC8+R9" إلى 849VCWC8%2BR9.
destination	مطلوب	تحدّد نقطة نهاية الاتجاهات.	اسم المكان أو العنوان أو رمز Plus Code أو إحداثيات خطوط العرض/الطول أو رقم تعريف المكان، مع إلغاء ترميز عنوان URL. تتيح Maps Embed API استخدام كل من + و%20 عند إلغاء المسافات. على سبيل المثال، يمكنك تحويل "City Hall, New York, NY" إلى City+Hall,New+York,NY، أو رمز Plus Code‏ "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	اختياري	يحدّد الحدود والتصنيفات المناسبة التي يجب عرضها، استنادًا إلى الحساسيات الجغرافية السياسية.	تقبل هذه السمة رمز منطقة محدّدًا كعلامة فرعية للمنطقة في يونيكود تتألف من حرفَين (غير رقميَّين) وتتوافق مع قيم مألوفة من حرفَين لنطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD). يُرجى الاطّلاع على تفاصيل تغطية "منصة خرائط Google" لمعرفة المناطق المعتمدة.

وضع streetview

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

توفّر كل بانوراما في "التجوّل الافتراضي" عرضًا كاملاً بزاوية 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). تعرض واجهة برمجة التطبيقات الصورة البانورامية التي تم التقاطها في أقرب مكان من هذا الموقع الجغرافي. بما أنّه يتم تحديث صور "التجوّل الافتراضي" بشكل دوري، وقد يتم التقاط الصور من مواضع مختلفة قليلاً في كل مرة، من الممكن أن يتم نقل موقعك الجغرافي إلى صورة بانورامية مختلفة عند تحديث الصور.

• ‫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	اختياري	يحدّد الحدود والتصنيفات المناسبة التي يجب عرضها، استنادًا إلى الحساسيات الجغرافية السياسية.	تقبل هذه السمة رمز منطقة محدّدًا كعلامة فرعية للمنطقة في يونيكود تتألف من حرفَين (غير رقميَّين) وتتوافق مع قيم مألوفة من حرفَين لنطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD). يُرجى الاطّلاع على تفاصيل تغطية "منصة خرائط Google" لمعرفة المناطق المعتمدة.

وضع 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	اختياري	يحدّد الحدود والتصنيفات المناسبة التي يجب عرضها، استنادًا إلى الحساسيات الجغرافية السياسية.	تقبل هذه السمة رمز منطقة محدّدًا كعلامة فرعية للمنطقة في يونيكود تتألف من حرفَين (غير رقميَّين) وتتوافق مع قيم مألوفة من حرفَين لنطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD). يُرجى الاطّلاع على تفاصيل تغطية "منصة خرائط Google" لمعرفة المناطق المعتمدة.

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

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

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

• q
• origin
• destination
• waypoints

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

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

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

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