تضمين خريطة

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

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

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

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

الاستبدال:

• MAP_MODE باستخدام وضع الخريطة الخاص بك.
• YOUR_API_KEY باستخدام مفتاح API الخاص بك. لمزيد من المعلومات، يُرجى الاطّلاع على الحصول على مفتاح واجهة برمجة التطبيقات.
• استبدِل PARAMETERS بالمعلَمات المطلوبة والاختيارية لوضع الخريطة.

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

لاستخدام واجهة برمجة تطبيقات تضمين الخرائط على صفحتك على الويب، قم بتعيين عنوان URL الذي أنشأته كقيمة لسمة src الخاصة بالإطار المضمن. يمكنك التحكم في حجم الخريطة باستخدام سمات height وwidth للإطار المتضمن، على سبيل المثال:

<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 مع الطلب حتى تتمكن قيود مفتاح واجهة برمجة التطبيقات من العمل بشكل صحيح.

يمكنك تغيير حجم الإطار المتضمّن ليناسب بنية وتصميم موقعك الإلكتروني، ولكن تبيّن لنا أنّ الزوّار يجدون عادةً سهولة أكبر في التفاعل مع الخرائط الأكبر حجمًا. يُرجى العِلم أنّ الخرائط المضمّنة لا تتوفّر بأقل من 200 بكسل في أي من البُعدَين.

القيود المفروضة على مفتاح واجهة برمجة التطبيقات

إذا كان الموقع الإلكتروني المضيف يتضمّن علامة وصفية referrer مضبوطة على no-referrer أو same-origin، لن يرسل المتصفّح العنوان Referer إلى Google. وقد يؤدي ذلك إلى رفض الطلبات بسبب القيود المفروضة على مفتاح واجهة برمجة التطبيقات. لكي يعمل هذا القيد بشكل صحيح، أضِف السمة referrerpolicy إلى إطار iframe، كما هو موضّح في المثال أعلاه، للسماح بشكل صريح بإرسال عناوين Referer إلى Google.

اختيار أوضاع الخريطة

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

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

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

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

وضع streetview

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

تقدّم كل بانوراما في "التجوّل الافتراضي" عرضًا كاملاً بزاوية 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). تعرض واجهة برمجة التطبيقات الصورة البانورامية التي تم التقاطها بالقرب من هذا الموقع الجغرافي. نظرًا لأن صور Street View يتم تحديثها بشكل دوري، وقد يتم التقاط الصور من مواضع مختلفة قليلاً في كل مرة، فمن المحتمل أن يتم التقاط موقعك في صورة بانورامية مختلفة عند تحديث الصور.

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

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

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

تقبل Maps Embed API معرّفات الأماكن لمعلمات عناوين URL التالية:

• q
• origin
• destination
• waypoints

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

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

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

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