يوضح هذا الدليل كيفية تضمين خريطة تفاعلية في صفحة الويب الخاصة بك.
إنشاء عنوان 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"
لإزالة حد 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 |
اختيارية | تحدد الحدود والتصنيفات المناسبة لعرضها استنادًا إلى الحساسيات الجغرافية السياسية. | يتم قبول رمز منطقة يتم تحديده على أنّه علامة فرعية لمنطقة مكوّنة من حرفَين (غير رقمية) يتم ربطها بقيم مكوّنة من حرفَين معروفَين في نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد ("نطاق المستوى الأعلى") ccTLD. يمكنك الاطّلاع على تفاصيل تغطية "منصة خرائط 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 |
اختيارية | تحدد الحدود والتصنيفات المناسبة لعرضها استنادًا إلى الحساسيات الجغرافية السياسية. | يتم قبول رمز منطقة يتم تحديده على أنّه علامة فرعية لمنطقة مكوّنة من حرفَين (غير رقمية) يتم ربطها بقيم مكوّنة من حرفَين معروفَين في نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد ("نطاق المستوى الأعلى") 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 |
مطلوب | تحدد نقطة البداية التي يجب عرض الاتجاهات منها. | اسم المكان أو العنوان الذي يتضمن عنوان URL بالإضافة إلى رمز الموقع الجغرافي أو إحداثيات خط العرض/خط الطول
أو رقم تعريف المكان بدون عنوان URL.
تتوافق واجهة برمجة التطبيقات Maps Embed API مع كل من + و%20
عند الخروج من المساحات. على سبيل المثال، يمكنك تحويل "مجلس المدينة، نيويورك، نيويورك" إلى City+Hall,New+York,NY ، أو رموز المواقع المفتوحة "849VCWC8+R9" إلى 849VCWC8%2BR9 . |
destination |
مطلوب | تحدد نقطة نهاية الاتجاهات. | اسم المكان أو العنوان الذي يتضمن عنوان URL بالإضافة إلى رمز الموقع الجغرافي أو إحداثيات خط العرض/خط الطول
أو رقم تعريف المكان بدون عنوان URL.
تتوافق واجهة برمجة التطبيقات Maps Embed API مع كل من + و%20
عند الخروج من المساحات. على سبيل المثال، يمكنك تحويل "مجلس المدينة، نيويورك، نيويورك" إلى City+Hall,New+York,NY ، أو رموز المواقع المفتوحة "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 درجة من موقع واحد. تحتوي الصور على عرض أفقي بزاوية 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 Places API.
تقبل واجهة برمجة تطبيقات تضمين الخرائط معرّفات الأماكن لمعلمات عناوين URL التالية:
q
origin
destination
waypoints
لاستخدام معرّف مكان، يجب أولاً إضافة البادئة place_id:
. يحدّد الرمز التالي قاعة مدينة نيويورك على أنها مصدر طلب الاتجاهات: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8
.
تحدّد
radius
نطاقًا جغرافيًا، يتم تحديده بالأمتار، للبحث عن بانوراما، في مركز خط العرض وخط الطول المحدَّدَين. القيم الصالحة هي أعداد صحيحة غير سالبة. القيمة التلقائية هي 50.يعمل
source
على حصر عمليات بحث "التجوّل الافتراضي" بالمصادر المحدّدة. القيم الصالحة هي:- يستخدم
default
المصادر التلقائية لميزة "التجوّل الافتراضي"، ولا تقتصر عمليات البحث على مصادر معيّنة. - تقتصر عمليات البحث على المجموعات في الأماكن الخارجية من خلال "
outdoor
". لا يتم تضمين المجموعات الداخلية في نتائج البحث. يُرجى العِلم أنّ الصور البانورامية الخارجية قد لا تتوفّر في الموقع الجغرافي المحدّد. لاحظ أيضًا أن البحث يعرض فقط صور بانورامية حيث يمكن تحديد ما إذا كانت داخلية أم في الهواء الطلق. على سبيل المثال، لا يتم عرض صور بانوراما 360 درجة لأنّه غير معروف سواء كانت داخلية أو خارجية.
- يستخدم