تضمين خريطة

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

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

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

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