في عالمنا اليوم الذي يعتمد على الموقع الجغرافي، يتوقّع المستخدمون الوصول بسلاسة إلى معلومات الأماكن والاتجاهات والتنقّل. سواء كان ذلك من خلال تطبيق مراسلة أو تطبيق لاكتشاف السياق المحلي أو منصة للخدمات اللوجستية والنقل أو أداة لتخطيط الرحلات أو منصة لعرض العقارات، يحتاج المستخدمون غالبًا إلى الاطّلاع بسرعة على تفاصيل الموقع الجغرافي أو العثور على أفضل طريق من النقطة "أ" إلى النقطة "ب". مع أنّ المطوّرين يمكنهم إنشاء تجربة داخل التطبيق، إلا أنّ الاستفادة من واجهة "خرائط Google" الشاملة والمألوفة تتيح تجربة أفضل.
يُعدّ عنوان URL المنظَّم جيدًا على "خرائط Google" أمرًا ضروريًا لتوفير تجربة سلسة للمستخدمين. تؤدي عناوين URL غير الصحيحة إلى إضعاف هذه التجربة، إذ توجّه المستخدمين إلى الموقع الجغرافي الخاطئ، أو تعرض عرضًا عامًا للخريطة بدلاً من التفاصيل المحددة، أو حتى تؤدي إلى رابط تالف. يؤدي ذلك إلى إحباط المستخدمين ومنعهم من تحقيق هدفهم. على سبيل المثال، حتى مع توفّر عنوان URL صالح على "خرائط Google"، قد ينتقل المستخدم الذي يتوقّع الحصول على تفاصيل حول نشاط تجاري معيّن إلى عرض عام للخريطة بدون أي معلومات ذات صلة. اطّلِع على المثال أدناه:
https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152
عنوان URL هذا صالح لفتح "خرائط Google" وعرض موقع جغرافي استنادًا إلى خطوط الطول والعرض. ومع ذلك، لا يقدّم للمستخدمين تفاصيل حول مكان معيّن.
ربط تطبيقك بسلاسة مع "خرائط Google" من خلال عناوين URL دقيقة
توفّر "منصة خرائط Google" (GMP) طريقتَين أساسيتَين لإنشاء عناوين URL دقيقة: Places API(الجديدة) التي تتطلّب مفتاح واجهة برمجة تطبيقات، وعناوين URL للخرائط التي تكون مجانية ولا تتطلّب مفتاحًا. تتناول الحلول التالية سيناريوهات وحالات استخدام مختلفة:
استخدام الحقل googleMapsUri أو googleMapsLinks في Places API(الجديدة) من GMP
تعرض واجهة برمجة التطبيقات Places API(الجديدة) من "منصة Google للتسويق" مجموعة شاملة من المعلومات حول مكان معيّن. عند طلب الحقل googleMapsUri أو googleMapsLinks (من خلال تحديده في قناع الحقل)، تتضمّن استجابة واجهة برمجة التطبيقات عنصر مكان.
يحتوي هذا العنصر على عناوين URL منسَّقة مسبقًا، ويمكن استخدامها لفتح العرض المقابل مباشرةً، مثل عرض تفاصيل المكان، في "خرائط Google".
مثال:
طلب تفاصيل المكان
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: YOUR_API_KEY" \ -H "X-Goog-FieldMask: googleMapsUri,googleMapsLinks" \ https://places.googleapis.com/v1/places/ChIJ3S-JXmauEmsRUcIaWtf4MzE
ردّ Place Details:
{
"googleMapsUri": "https://maps.google.com/?cid=3545450935484072529",
"googleMapsLinks": {
"directionsUri": "https://www.google.com/maps/dir//''/data=!4m7!4m6!1m1!4e2!1m2!1m1!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!3e0",
"placeUri": "https://maps.google.com/?cid=3545450935484072529",
"writeAReviewUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!12e1",
"reviewsUri": "https://www.google.com/maps/place//data=!4m4!3m3!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!9m1!1b1",
"photosUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!10e5"
}
}ChIJ3S-JXmauEmsRUcIaWtf4MzE في المثال أعلاه هو معرّف المكان الخاص بـ "دار أوبرا سيدني". معرّف المكان هو معرّف نصي يحدّد مكانًا بشكلٍ فريد في قاعدة بيانات "أماكن Google" وعلى "خرائط Google".
استرداد أرقام تعريف الأماكن بدون تكلفة
لاسترداد أرقام تعريف الأماكن آليًا، يمكنك استخدام وظيفة Places API: البحث النصي(المعرّف فقط). هذه طريقة مجانية للحصول على أرقام تعريف الأماكن. مزيد من المعلومات عن رقم تعريف المكان وطلب Place API(الجديد)
طلب البحث النصي في Places API(رقم التعريف فقط):
curl -X POST -d '{"textQuery" : "Sydney Opera House"}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'استجابة Places API Text Search(ID Only):
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}يمكن أيضًا استرداد أرقام تعريف الأماكن عندما ينقر المستخدم على نقطة اهتمام على الخرائط. مزيد من التفاصيل حول رموز نقاط الاهتمام القابلة للنقر(JavaScript وAndroid وiOS)
التنفيذ
عند استخدام Places API، يمكن للمطوّرين استخراج الحقل googleMapsUri أو googleMapsLinks من الردّ واستخدامه لتشغيل العرض المقابل في تطبيق "خرائط Google" أو في المتصفّح إذا لم يكن التطبيق مثبّتًا.
| الميزة | الوصف |
|---|---|
| directionsUri | رابط لفتح "خرائط Google" وعرض الاتجاهات من الموقع الجغرافي الحالي للمستخدم إلى هذا المكان |
| placeUri | رابط لفتح صفحة تفاصيل المكان في "خرائط Google" |
| writeAReviewUri | رابط لفتح صفحة كتابة المراجعات عن هذا المكان في "خرائط Google" |
| reviewsUri | رابط لفتح صفحة المراجعات الخاصة بهذا المكان على "خرائط Google" |
| photosUri | رابط لفتح صفحة الصور لهذا المكان على "خرائط Google" |
يمكنك الاطّلاع على إرشادات المطوّرين وتجربة الميزة اليوم.
الاستفادة من عناوين URL في "خرائط Google"
باستخدام عناوين URL في "خرائط Google"، يمكنك إنشاء عنوان URL عالمي متوافق مع جميع الأنظمة الأساسية لتشغيل "خرائط Google" وإجراء عمليات بحث والحصول على الاتجاهات والتنقّل وعرض طرق عرض الخريطة والصور البانورامية. يكون بناء جملة عنوان URL هو نفسه بغض النظر عن النظام الأساسي المستخدَم. لا تحتاج إلى مفتاح Google API لاستخدام عناوين URL في "خرائط Google".
الإجراءات المتاحة على الخريطة هي:
تُشغّل وظيفة البحث تطبيق "خرائط Google" أو في متصفّح إذا لم يكن التطبيق مثبّتًا، ويعرض التطبيق دبوسًا لمكان معيّن، أو يُجري عملية بحث عامة ويُشغّل خريطة لعرض النتائج.
تُطلق وظيفة "الاتجاهات" تطبيق "خرائط Google" أو في متصفح إذا لم يكن التطبيق مثبّتًا، وتعرض الاتجاهات بين النقاط أو تتيح التنقّل خطوة بخطوة على "خرائط Google" للأجهزة الجوّالة.
تتيح لك وظيفة بانوراما "التجوّل الافتراضي" تشغيل عارض لعرض صور "التجوّل الافتراضي" كبانورامات تفاعلية.
انتقِل إلى مستندات المطوّرين حول عناوين URL في "خرائط Google" لاستكشاف المزيد من الدوال والأمثلة.
في ما يلي، سنتناول وظيفتَين أساسيتَين من وظائف عناوين URL في "خرائط Google":
عرض تفاصيل الأماكن على "خرائط Google": يوضّح هذا القسم كيفية إنشاء عناوين URL تعرض تفاصيل موقع جغرافي معيّن على "خرائط Google". ويوضّح أيضًا كيفية التعامل مع الأماكن التي لها أسماء غير فريدة باستخدام معرّفات الأماكن والطلبات الدقيقة.
توفير الاتجاهات باستخدام عناوين URL في "خرائط Google": يوضّح هذا القسم كيفية إنشاء عناوين URL توفّر الاتجاهات بين المواقع الجغرافية، بما في ذلك الاتجاهات التي تتضمّن نقاط توقّف متعدّدة واتجاهات التنقّل المفصّلة.
عرض تفاصيل الأماكن على "خرائط Google"
تتطلّب دالة البحث مَعلمتَين لإكمال عملية البحث عن الأماكن، وهما query(مطلوبة) وquery_place_id(اختيارية).
المَعلمة query مطلوبة لجميع طلبات البحث. يقبل هذا الحقل اسم مكان أو إحداثيات خطوط الطول والعرض مفصولة بفواصل أو عبارة بحث عامة.
بنية عنوان URL الخاص بالبحث:
https://www.google.com/maps/search/?api=1¶meters
السيناريو 1: عرض تفاصيل مكان لاسم مكان فريد
https://www.google.com/maps/search/?api=1&query=Sydney%20Opera%20House
والآن، لنفترض أنّ هناك مكانًا يحمل اسمًا غير فريد. ماذا يحدث عندما تبحث فقط بهذا الاسم غير الفريد؟ اطّلِع على السيناريو التالي.
السيناريو 2: البحث عن أماكن باستخدام اسم مكان غير فريد
https://www.google.com/maps/search/?api=1&query=7-Eleven
بما أنّ اسم المكان ليس فريدًا، يفتح عنوان URL هذا قائمة بمواقع 7-Eleven القريبة ضمن إطار العرض. يمكن للمستخدمين بعد ذلك اختيار متجر معيّن للاطّلاع على تفاصيله.
لتجنُّب قائمة المواقع الجغرافية والوصول مباشرةً إلى صفحة تفاصيل معيّنة، يمكنك استخدام طريقة أكثر دقة. اطّلِع على المثال التالي.
السيناريو 3: عرض تفاصيل مكان يحمل اسمًا غير فريد
عند التعامل مع أسماء الأماكن الشائعة، غالبًا ما يؤدي البحث البسيط عن الاسم إلى عرض قائمة بالمواقع الجغرافية. لإنشاء رابط مباشر يؤدي إلى صفحة تفاصيل معيّنة، يمكنك استخدام إحدى الطريقتَين التاليتَين:
الطريقة 1: استخدام طلب بحث دقيق مع اسم المكان وعنوانه
https://www.google.com/maps/search/?api=1&query=7-Eleven%2C37%20Swanston%20St%2C%20Melbourne%20Australia
في عنوان URL هذا، يتم تنسيق المَعلمة query على النحو التالي: اسم المكان، العنوان. يساعد ذلك في تضييق نطاق البحث والربط مباشرةً بالموقع الجغرافي المقصود.
الطريقة 2: استخدام معرّف المكان
تحدِّد أرقام تعريف الأماكن مكانًا بشكلٍ فريد في قاعدة بيانات "أماكن Google" وعلى "خرائط Google".
https://www.google.com/maps/search/?api=1&query=7-Elevan&query_place_id=ChIJGcmcg7ZC1moRAOacd3HoEwM
في هذا المثال، ChIJGcmcg7ZC1moRAOacd3HoEwM هو معرّف المكان الفريد للمكان المحدّد. ستظل المَعلمة query مطلوبة، ولكن سيتم استخدامها فقط إذا لم تتمكّن "خرائط Google" من العثور على معرّف المكان.
السيناريو 4: عرض تفاصيل المكان باستخدام إحداثيات خطوط الطول والعرض بالإضافة إلى معرّف المكان
يضمن استخدام معرّف المكان أن تعرض "خرائط Google" معلومات مفصّلة عن المكان.
https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE
استرداد أرقام تعريف الأماكن بدون أي تكلفة
لاسترداد أرقام تعريف الأماكن آليًا، يمكنك استخدام وظيفة Places API: البحث النصي(المعرّف فقط). هذه طريقة مجانية للحصول على أرقام تعريف الأماكن. يمكنك الاطّلاع على مزيد من المعلومات عن معرّف المكان وطلب Place API(الجديدة).
طلب البحث النصي في Places API(رقم التعريف فقط):
curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'استجابة Places API Text Search(ID Only):
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}يمكن أيضًا استرداد أرقام تعريف الأماكن عندما ينقر المستخدم على نقطة اهتمام على الخرائط. مزيد من التفاصيل حول رموز نقاط الاهتمام القابلة للنقر(JavaScript وAndroid وiOS)
الخاتمة
يُعدّ تقديم تفاصيل دقيقة عن الأماكن أمرًا ضروريًا لتوفير تجربة إيجابية. لضمان وصول المستخدمين إلى صفحة تفاصيل المكان الصحيحة، أنشئ عناوين URL الخاصة بالبحث باستخدام أحد التنسيقات المقترَحة التالية:
query=PLACE_NAME, ADDRESSquery=PLACE_NAME&query_place_id=PLACE_ID
تجنَّب استخدام إحداثيات خطوط الطول والعرض فقط في المَعلمة query عندما يكون هدفك هو عرض تفاصيل مكان معيّن. لن تؤدي التنسيقات مثل query=latitude,longitude أو query=PLACE_NAME,latitude,longitude أو query=ADDRESS,latitude,longitude بشكل دائم إلى صفحة تفاصيل المكان المطلوبة. بدلاً من ذلك، سيتم عرض خطَّي الطول والعرض للموقع الجغرافي.
البحث حسب الفئة باستخدام عناوين URL على "خرائط Google"
في البحث حسب الفئة، يمكنك إدخال عبارة بحث عامة، وستحاول "خرائط Google" العثور على بيانات تتطابق مع المعايير التي تحدّدها بالقرب من الموقع الجغرافي الذي تحدّده. إذا لم يتم تحديد موقع جغرافي، ستحاول "خرائط Google" العثور على بيانات قريبة من موقعك الجغرافي الحالي.
السيناريو 1: البحث عن أماكن قريبة
https://www.google.com/maps/search/?api=1&query=Cafe%20near%20Sydney%20Opera%20House%20that%20are%20open%20now
توفير الاتجاهات باستخدام عناوين URL في "خرائط Google"
تعرض وظيفة "الاتجاهات" المسار بين نقطتين أو أكثر محدّدة على الخريطة، بالإضافة إلى المسافة ووقت السفر. تتيح هذه السمة للمطوّرين المزيد من التحكّم في الاتجاهات المقدَّمة. تقدّم مستندات إرشادات عناوين URL في "منصة Google للتسويق" تعليمات مفصّلة حول إنشاء عناوين URL للحصول على إرشادات مخصّصة.
بنية عنوان URL الخاص بالاتجاهات:
https://www.google.com/maps/dir/?api=1¶meters
السيناريو 1: العثور على أفضل مسار من الموقع الجغرافي الحالي للمستخدم إلى وجهة معيّنة
https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving
يفتح عنوان URL هذا "خرائط Google" ويعرض اتجاهات القيادة من الموقع الجغرافي الحالي للمستخدم.
في عنوان URL هذا، تم حذف origin. عند حذف origin، يتم ضبط المسار تلقائيًا على الموقع الجغرافي الأكثر صلة، مثل الموقع الجغرافي للجهاز، إذا كان متاحًا.
إذا لم يكن هناك أي منها، ستوفّر الخريطة الناتجة نموذجًا للسماح للمستخدم بإدخال المصدر.
يمكن أن تكون قيمة نقطة البداية ونقطة الوصول اسم مكان أو عنوانًا أو إحداثيات خطوط الطول والعرض مفصولة بفواصل.
travelmode هي مَعلمة اختيارية. تحدّد طريقة السفر.
يمكن ضبط هذه المَعلَمة على النحو التالي:
- القيادة
- المشي
- ركوب الدراجات
- درّاجة نارية
- النقل العام
في حال عدم تحديد travelmode، تعرض "خرائط Google" وسيلة واحدة أو أكثر من وسائل النقل الأكثر صلة بالمسار المحدّد و/أو الإعدادات المفضّلة للمستخدم.
يمكن للمطوّرين أيضًا تحديد أرقام تعريف الأماكن باستخدام المَعلمة origin_place_id وdestination_place_id. يُعدّ استخدام رقم تعريف المكان أفضل ضمان للحصول على رابط يؤدي إلى المكان الصحيح.
استرداد أرقام تعريف الأماكن بدون أي تكلفة
لاسترداد أرقام تعريف الأماكن آليًا، يمكنك استخدام وظيفة Places API: البحث النصي(المعرّف فقط). هذه طريقة مجانية للحصول على أرقام تعريف الأماكن. يمكنك الاطّلاع على مزيد من المعلومات عن معرّف المكان وطلب Place API(الجديدة).
طلب البحث النصي في Places API(رقم التعريف فقط):
curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'استجابة Places API Text Search(ID Only):
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}يمكن أيضًا استرداد أرقام تعريف الأماكن عندما ينقر المستخدم على نقطة اهتمام على الخرائط. مزيد من التفاصيل حول رموز نقاط الاهتمام القابلة للنقر(JavaScript وAndroid وiOS)
السيناريو 3: تقديم اتّجاهات مفصّلة للتنقّل
https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving&dir_action=navigate
سيؤدي ضبط dir_action=navigate في عنوان URL إلى تشغيل "خرائط Google" في وضع التنقّل خطوة بخطوة إذا كان الموقع الجغرافي الحالي للمستخدم(موقع الجهاز) متاحًا وتم استخدامه كموقع جغرافي للمغادرة (إما تم توفيره بشكل صريح أو تم استخدامه ضمنيًا عند حذف مَعلمة الموقع الجغرافي للمغادرة). وإلّا فستظهر معاينة للمسار.
يتم تشغيل الاتّجاهات المفصّلة عند ضبط dir_action=navigate و:
- تم تحديد المصدر وهو قريب من الموقع الجغرافي الحالي للمستخدم
- يتم حذف المصدر ويتوفّر الموقع الجغرافي الحالي للمستخدم
يتم تشغيل معاينة المسار في الحالات التالية:
- لم يتم ضبط
dir_action=navigate - تم ضبط
dir_action=navigateوتم تحديد المصدر، والمصدر ليس قريبًا من الموقع الجغرافي الحالي للمستخدم - تم ضبط
dir_action=navigateوتم حذف المصدر، ولم يتوفّر الموقع الجغرافي الحالي للمستخدم
يُرجى العِلم أنّ ميزة التنقّل غير متاحة على بعض منتجات "خرائط Google"، مثل "خرائط Google" على الويب، و/أو بين بعض الوجهات. وفي هذه الحالات، سيتم تجاهل هذه المَعلمة.
![]() |
![]() |
الخاتمة
من خلال إنشاء عناوين URL صحيحة لـ "خرائط Google"، يمكنك التأكّد من أنّ المستخدمين يحصلون على المعلومات التي يحتاجون إليها بسرعة وكفاءة.
حدِّد الوجهة دائمًا، واستخدِم رقم تعريف المكان كلما أمكن ذلك لضمان الدقة.
عندما يكون الهدف هو توفير تنقّل فوري، أدرِج المَعلمة dir_action=navigate لتفعيل التنقّل المفصّل. سيبدأ التنقّل من الموقع الجغرافي الحالي للمستخدم إذا كان الموقع الجغرافي للجهاز متاحًا وتم استخدامه كنقطة بداية (إما تم ضبطه بشكل صريح أو تم حذفه).
اختيار النهج المناسب لتطبيقك
يتوفّر لك خياران أساسيان: الاستفادة من عناوين URL المنسَّقة مسبقًا التي توفّرها Places API أو إنشاء عناوين URL في "خرائط Google" يدويًا في تطبيقك. ولكل نهج مجموعة من المزايا والعيوب.
Places API:
يوفّر الحقلان
googleMapsUriوgoogleMapsLinksفي استجابة "تفاصيل المكان" عناوين URL جاهزة للاستخدام، ما يقلّل من وقت التطوير ويحدّ من خطر حدوث أخطاء في تنسيق عناوين URL.يوفّر تحكّمًا أقل في إعدادات الاتجاهات. على الرغم من أنّ
googleMapsLinksيقدّم اتجاهات أساسية، إلا أنّه لا يتيح نقاط الطريق أو التخصيص المتقدّم. بالإضافة إلى ذلك، من الصعب نسبيًا بدء التنقّل خطوة بخطوة مباشرةً.
عناوين URL لـ "خرائط Google":
توفير مرونة وتحكّم أكبر يمكن للمطوّرين إنشاء عناوين URL لعرض تفاصيل الأماكن وإعداد جوانب مختلفة من الاتجاهات، بما في ذلك إضافة نقاط توقّف وتحديد وسائل النقل وبدء التنقّل خطوة بخطوة.
يتطلّب فهمًا أعمق لمعلَمات عناوين URL وبنيتها. يزيد الإنشاء اليدوي من احتمال حدوث أخطاء إذا لم يتم تنفيذه بعناية.
تحسين عناوين URL في "خرائط Google" باستخدام مَعلمات نظام مراقبة الزيارات من Urchin
لمساعدة Google في فهم كيفية دمج المطوّرين لعناوين URL الخاصة بـ "خرائط Google" ولضمان تحقيق أفضل أداء، ننصحك بتضمين مَعلمات تتبُّع نظام مراقبة الزيارات من Urchin في عملية إنشاء عناوين URL. من خلال إضافة المَعلمتَين utm_source وutm_campaign، يمكنك تقديم بيانات قيّمة تتيح لنا تحليل أنماط الاستخدام وتحسين منتج "عناوين URL في خرائط Google".
بالنسبة إلى المَعلمة utm_source، استخدِم اسم تطبيقك. يجب أن تعكس المَعلمة
utm_campaign إجراء المستخدم المقصود، مثل
"location_sharing" أو "place_details_search" أو "directions_request".
على سبيل المثال، قد يظهر عنوان URL يتضمّن مَعلمات نظام مراقبة الزيارات من Urchin على النحو التالي:
https://www.google.com/maps/search/?api=1&query=Sydney+Opera+House&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE&utm_source=YourAppName&utm_campaign=place_details_search
يساعدنا استخدام هذه المَعلمات باستمرار في تحديد مجالات التحسين، وتحديد المشاكل وحلّها بفعالية أكبر، وتقديم تجربة أفضل لجميع المستخدمين في النهاية.
الخطوات التالية
محتوى إضافي للقراءة:
المساهمون
المؤلفون الرئيسيون:
تيريزا تشين | مهندسة حلول في "منصة خرائط Google"

