يوضح هذا الدليل كيفية تضمين خريطة تفاعلية في صفحة الويب.
إنشاء عنوان URL لواجهة برمجة التطبيقات لتضمين الخرائط
فيما يلي مثال على عنوان URL يُحمِّل Maps تضمين API:
https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS
استبدال:
- MAP_MODE باستخدام وضع الخريطة.
- YOUR_API_KEY باستخدام مفتاح واجهة برمجة التطبيقات. للمزيد من المعلومات، يُرجى الاطّلاع على مقالة الحصول على مفتاح واجهة برمجة التطبيقات.
- PARAMETERS بالمعلمات المطلوبة والاختيارية لوضع الخريطة.
إضافة عنوان URL إلى إطار iframe
لاستخدام واجهة Maps inline API على صفحتك على الويب، حدِّد عنوان 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 inline 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 |
مطلوب | لتحديد موقع محدِّد الخريطة | اسم المكان أو العنوان أو رمز الموقع المفتوح أو رقم تعريف المكان الذي يتضمن أحرف إلغاء.
تتوافق "واجهة برمجة التطبيقات لتضمين الخرائط" مع الترميزَين + و%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
لعرض المسار بين أوسلو
وتيليمارك في النرويج والمسافة ووقت السفر مع تجنب رسوم العبور والطرق السريعة.
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 |
اختياري | تحدد هذه السمة طريقة التنقّل. إذا لم يتم تحديد أي وضع، ستعرض واجهة Maps inline 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
تتيح لك "واجهة برمجة التطبيقات لتضمين الخرائط" عرض صور "التجوّل الافتراضي" كصور بانورامية تفاعلية من مواقع جغرافية محددة في جميع أنحاء منطقة التغطية. تتوفر أيضًا الصور البانورامية التي ساهم بها المستخدم، والمجموعات الخاصة لميزة "التجوّل الافتراضي".
توفر كل بانوراما في ميزة "التجوّل الافتراضي" عرضًا كاملاً بزاوية 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.
تقبل واجهة برمجة التطبيقات Maps inline API معرّفات الأماكن لمَعلمات عناوين URL التالية:
q
origin
destination
waypoints
لاستخدام معرّف مكان، يجب أولاً إضافة البادئة place_id:
. يحدد الرمز التالي قاعة مدينة نيويورك على أنها نقطة الانطلاق لطلب الاتجاهات: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8
.
يضبط
radius
نصف قطر محدد بالمتر، والذي يمكن البحث فيه عن بانوراما، في مركز على خط العرض وخط الطول المحدّدين. القيم الصالحة هي أعداد صحيحة غير سالبة. القيمة التلقائية هي 50.يعمل
source
على حصر عمليات البحث في "التجوّل الافتراضي" على المصادر المحدَّدة. القيم الصالحة هي:- يستخدم تطبيق
default
المصادر التلقائية لميزة "التجوّل الافتراضي"، ولا تقتصر عمليات البحث على مصادر محدَّدة. - تقتصر عمليات البحث على
outdoor
في المجموعات الخارجية. ولا يتم تضمين المجموعات الداخلية في نتائج البحث. لاحظ أن الصور البانورامية الخارجية قد لا تكون موجودة للموقع المحدد. لاحظ أيضًا أن البحث يعرض فقط الصور البانورامية حيث يمكن تحديد ما إذا كانت هذه الصور داخلية أو في الهواء الطلق. على سبيل المثال، لا يتم إرجاع الصور البانورامية لأنّها غير معروفة سواء كانت في الأماكن الداخلية أو الخارجية.
- يستخدم تطبيق