يوضّح هذا الدليل كيفية تضمين خريطة تفاعلية في صفحة الويب.
إنشاء عنوان URL لواجهة برمجة التطبيقات لتضمين الخرائط
فيما يلي مثال على عنوان URL يحمِّل واجهة برمجة تطبيقات تضمين الخرائط:
https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS
استبدال:
- MAP_MODE باستخدام وضع الخريطة.
- 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"
لإزالة حدود الإطار المُدمَج العادي من حول الخريطة - السمة
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" إلى
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
¢er=-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 أو رموز الموقع المفتوح "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 |
اختياري | تحدّد الحدود والعناوين المناسبة للعرض استنادًا إلى الحساسيات الجغرافية والسياسية. | تقبل رمز منطقة محدّدًا على أنّه علامة فرعية لمنطقة يونيكود تتكون من حرفَين (غير رقميَين) وترتبط بقيم نطاقات المستوى الأعلى لرموز البلدان (ccTLD) المألوفة المكونة من حرفَين. اطّلِع على "منصة خرائط 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" تفاصيل التغطية للاطّلاع على المناطق التي تتوفّر فيها الخدمة. |
مَعلمات رقم تعريف المكان
تتيح واجهة برمجة التطبيقات 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 لأنّه غير معروف. سواء كانت داخلية أو في الهواء الطلق.
- يستخدم