تضمين خريطة

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

إنشاء عنوان 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" لإزالة حد iframe العادي من جميع أنحاء الخريطة
  • السمة 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 مطلوب لتحديد موقع محدِّد الخريطة. اسم المكان أو العنوان أو رمز الموقع المفتوح أو رقم تعريف المكان الذي يتضمن حروف إلغاء عنوان URL تتوافق واجهة برمجة التطبيقات Maps Embed API مع كل من + و%20 عند الخروج من المساحات. على سبيل المثال، يمكنك تحويل "مجلس المدينة، نيويورك، نيويورك" إلى City+Hall,New+York,NY، أو رموز المواقع المفتوحة "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 مطلوب تحدد نقطة نهاية الاتجاهات. اسم المكان أو العنوان الذي يتضمن عنوان URL بالإضافة إلى رمز الموقع الجغرافي أو إحداثيات خط العرض/خط الطول أو رقم تعريف المكان بدون عنوان 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). ستعرض واجهة برمجة التطبيقات الصورة البانورامية التي تم التقاطها الأقرب إلى هذا الموقع. نظرًا لتحديث صور "التجوّل الافتراضي" بشكل دوري، وإمكانية التقاط الصور من مواضع مختلفة قليلاً في كل مرة، من الممكن أن يتم التقاط موقعك على صورة بانورامية مختلفة عند تحديث الصور.

  • 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" لمعرفة المناطق المتاحة.

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

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

تقبل واجهة برمجة تطبيقات تضمين الخرائط معرّفات الأماكن لمعلمات عناوين URL التالية:

  • q
  • origin
  • destination
  • waypoints

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

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

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

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