تضمين خريطة

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

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

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

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

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

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

وضع streetview

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

تقدم كل صورة بانورامية 360 درجة عرضًا كاملاً بزاوية 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.

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

  • q
  • origin
  • destination
  • waypoints

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

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

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

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