تضمين خريطة

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

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

فيما يلي مثال على عنوان URL يُحمِّل Maps تضمين API:

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

استبدال:

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

لاستخدام واجهة Maps inline API على صفحتك على الويب، حدِّد عنوان 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 inline 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 مطلوب لتحديد موقع محدِّد الخريطة اسم المكان أو العنوان أو رمز الموقع المفتوح أو رقم تعريف المكان الذي يتضمن أحرف إلغاء. تتوافق "واجهة برمجة التطبيقات لتضمين الخرائط" مع الترميزَين + و%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 لعرض المسار بين أوسلو وتيليمارك في النرويج والمسافة ووقت السفر مع تجنب رسوم العبور والطرق السريعة.

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

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

المَعلمة النوع الوصف القيم المقبولة
origin مطلوب تحدد نقطة البداية التي سيتم عرض الاتجاهات منها. اسم المكان أو عنوانه أو رمزه أو إحداثيات خطوط الطول والعرض أو معرّف المكان بدون عنوان URL. تتوافق "واجهة برمجة التطبيقات لتضمين الخرائط" مع الترميزَين + و%20 عند استبدال المسافات. على سبيل المثال، حوِّل "دار البلدية، القاهرة، الإسكندرية" إلى City+Hall,New+York,NY، أو رموز الجمع "849VCWC8+R9" إلى 849VCWC8%2BR9.
destination مطلوب تحدد نقطة نهاية الاتجاهات. اسم المكان أو عنوانه أو رمزه أو إحداثيات خطوط الطول والعرض أو معرّف المكان بدون عنوان URL. تتوافق "واجهة برمجة التطبيقات لتضمين الخرائط" مع الترميزَين + و%20 عند استبدال المسافات. على سبيل المثال، حوِّل "دار البلدية، القاهرة، الإسكندرية" إلى City+Hall,New+York,NY، أو رموز الجمع "849VCWC8+R9" إلى 849VCWC8%2BR9.
waypoints اختياري تُحدد مكانًا واحدًا أو أكثر من الأماكن الوسيطة لتوجيه الاتجاهات بين نقطة الانطلاق والوجهة. اسم المكان أو العنوان أو رقم تعريف المكان. يمكن تحديد عدة نقاط طرق باستخدام رمز الشرطة الرأسية (|) للفصل بين الأماكن (مثل Berlin,Germany|Paris,France). ويمكنك تحديد ما يصل إلى 20 نقطة طريق.
mode اختياري تحدد هذه السمة طريقة التنقّل. إذا لم يتم تحديد أي وضع، ستعرض واجهة Maps inline 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

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

توفر كل بانوراما في ميزة "التجوّل الافتراضي" عرضًا كاملاً بزاوية 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.

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

  • q
  • origin
  • destination
  • waypoints

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

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

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

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