تضمين خريطة

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

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

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

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

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

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

  • q
  • origin
  • destination
  • waypoints

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

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

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

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