تضمين خريطة

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

في ما يلي مثال لعنوان URL يحمّل API للخرائط المضمنة:

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.

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

قد تتضمن 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 أو العنوان أو رمز الموقع المفتوح أو رقم تعريف المكان. تدعم واجهة برمجة التطبيقات لتضمين الخرائط كل من + و%20 عند الهروب من المساحات. على سبيل المثال، يمكنك تحويل "دار البلدية، القاهرة، دبي" إلى City+Hall,New+York,NY، أو رمز الموقع المفتوح "849VCWC8+R9" إلى 849VCWC8%2BR9.
center اختياري لتحديد مركز عرض الخريطة. تقبل قيمة خطوط الطول وخطوط العرض مفصولة بفواصل، على سبيل المثال: 37.4218,-122.0840.
zoom اختياري تعيين مستوى التكبير/التصغير الأولي للخريطة. تتراوح القيم من 0 (العالم بأسره) إلى 21 (مباني فردية). ويمكن أن يختلف الحد الأقصى اعتمادًا على بيانات الخريطة المتوفّرة في الموقع الجغرافي المحدّد.
maptype اختياري لتحديد نوع مربعات الخرائط المراد تحميلها. roadmap (تلقائي) أو satellite
language اختياري تحدّد اللغة التي سيتم استخدامها لعناصر واجهة المستخدم ولعرض التصنيفات على مربّعات الخريطة. بشكل افتراضي، سيطّلع الزائرون على الخريطة بلغتهم. هذه المعلَمة متوافقة مع بعض مربّعات البلدان، وإذا كانت اللغة المحدّدة المطلوبة غير متوافقة مع مجموعة المربّعات، سيتم استخدام اللغة التلقائية لتلك المجموعة.
region اختياري تحدّد الحدود الجغرافية والتصنيفات المناسبة لعرضها، استنادًا إلى الحساسيات الجغرافية السياسية. يقبل رمز المنطقة المحدد كتعيين علامة فرعية لـ unicode مكون من حرفين (غير رقمي) إلى قيم مكونة من حرفين في 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 اختياري تحدّد الحدود الجغرافية والتصنيفات المناسبة لعرضها، استنادًا إلى الحساسيات الجغرافية السياسية. يقبل رمز المنطقة المحدد كتعيين علامة فرعية لـ unicode مكون من حرفين (غير رقمي) إلى قيم مكونة من حرفين في 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 اختياري تحدد طريقة السفر. في حال عدم تحديد وضع، ستعرض "واجهة برمجة التطبيقات لتضمين الخرائط" وضعًا واحدًا أو أكثر من الأوضاع الأكثر صلة للمسار المحدّد. 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 اختياري تحدّد الحدود الجغرافية والتصنيفات المناسبة لعرضها، استنادًا إلى الحساسيات الجغرافية السياسية. يقبل رمز المنطقة المحدد كتعيين علامة فرعية لـ unicode مكون من حرفين (غير رقمي) إلى قيم مكونة من حرفين في ccTLD ("نطاق المستوى الأعلى") المعتاد. اطّلِع على تفاصيل التغطية في "منصة خرائط Google" للمناطق المتوافقة.

وضع streetview

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

وتوفر كل صورة بانورامية للتجوّل الافتراضي عرضًا كاملاً بزاوية 360 درجة من موقع واحد. تحتوي الصور على عرض أفقي بزاوية 360 درجة (ملفوف بالكامل) وعمودي بزاوية 180 درجة (من أعلى لأسفل وحتى مستقيم لأسفل). يوفر الوضع streetview عارضًا يعرض البانوراما الناتجة كبانوراما 360 درجة مع وضع كاميرا في منتصفها. يمكنك التعامل مع الكاميرا للتحكم في التكبير/التصغير واتجاه الكاميرا.

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

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

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

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

  • q
  • origin
  • destination
  • waypoints

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

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

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

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