تضمين خريطة

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

إنشاء عنوان URL لواجهة برمجة التطبيقات لتضمين الخرائط

فيما يلي مثال على عنوان URL يحمِّل واجهة برمجة تطبيقات تضمين الخرائط:

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

استبدال:

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

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

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

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

  • سمة allowfullscreen للسماح بعرض أجزاء معيّنة من الخريطة بملء الشاشة
  • السمتَان frameborder="0" وstyle="border:0" لإزالة حدود الإطار المُدمَج العادي من حول الخريطة
  • سمة referrerpolicy="no-referrer-when-downgrade" للسماح للمتصفّح بإرسال عنوان URL الكامل كعنوان Referer مع الطلب لكي تعمل قيود مفتاح واجهة برمجة التطبيقات بشكل صحيح

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

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

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

الإعلانات على الخريطة

قد تتضمن واجهة برمجة التطبيقات Maps Embed API إعلانات على الخريطة. قد يتغير شكل الإعلان ومجموعة الإعلانات المعروضة في أي خريطة محددة بدون إشعار.

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

يمكنك تحديد أحد أوضاع الخريطة التالية لاستخدامه في عنوان 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 Codes‏ "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 لعرض المسار بين أوسلو وTelemark والنرويج والمسافة ووقت السفر من أجل تجنّب رسوم العبور والطرق السريعة.

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

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

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

  • 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 استخدام أرقام تعريف الأماكن بدلاً من تقديم اسم مكان أو عنوان. أرقام تعريف الأماكن هي طريقة ثابتة لتحديد مكان بشكلٍ فريد. لمزيد من المعلومات، يُرجى الاطّلاع على مستندات Google Places API.

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

  • q
  • origin
  • destination
  • waypoints

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

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

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

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