كيف تبني store locator (محدد المتاجر) باستخدام Maps API

store locator هو تلك الخاصية الصغيرة التي ينتهي كل نشاط متعدد الفروع إلى الحاجة إليها: مربع «ابحث عن أقرب متجر» الذي يحوّل رمزًا بريديًا إلى قائمة قصيرة مرتبة بالمتاجر على خريطة. يبدو تافهًا من الخارج، والمسار السعيد بسيط فعلًا، لكن المحدد الجيد يؤدي ثلاث مهام بهدوء وإتقان: يفهم مُدخلات الموقع الفوضوية، ويرتّب الفروع بالقرب الحقيقي، ويعرض النتيجة على خريطة يستطيع الإنسان التصرف بناءً عليها.

يشرح هذا الدليل كيف يعمل store locator فعلًا، والخطوات الأربع لبنائه عبر واجهة خرائط، والتفاصيل التي تفصل بين نموذج تجريبي وشيء تطرحه في الإنتاج. كل خريطة في هذا المقال معروضة بواسطة واجهة MapAtlas API نفسها.

ما الذي يفعله store locator فعلًا

جرّد التنسيق وستجد أن store locator خط أنابيب من ثلاث مراحل:

1. الترميز الجغرافي لمُدخل الزائر. «1012 Amsterdam» أو «SW1A 1AA» أو موقع GPS مُشارَك، كلها يجب أن تصير خط عرض وخط طول واحدًا.
2. ترتيب المتاجر القريبة. بمعلومية تلك الإحداثية وقائمة مواقع فروعك، اعثر على الأقرب ضمن نطاق معقول.
3. العرض. ضع المتاجر المرتبة على خريطة كعلامات، لكل منها عنوانه وساعات عمله ورابط للاتجاهات.

الخريطة أدناه هي بالضبط تلك المرحلة الثالثة، معروضة بمربعات MapAtlas: ستة فروع في وسط أمستردام مثبتة حسب المسافة من الزائر. هنا هي متاجر سوبرماركت، لكن الخريطة واحدة سواء أتت العلامات من مجموعة بيانات POI أو من قائمة متاجرك الخاصة.

ترتيب الألوان هو الترتيب نفسه. بحث الزائر من مركز الخريطة، والعلامات هي أقرب الفروع بالترتيب، الأقرب أولًا.

الخطوة 1: ترميز مُدخل الزائر جغرافيًا

يكتب الزائر رمزًا بريديًا أو مدينة أو عنوانًا كاملًا، وأنت تحتاج إلى إحداثية. هذا هو الترميز الجغرافي الأمامي.

// Turn what the visitor types into a coordinate (autocomplete geocoding)
const res = await fetch(
  `https://gateway.mapmetrics-atlas.net/autocomplete/` +
  `?token=${API_TOKEN}&text=${encodeURIComponent(query)}` +
  `&focus.point.lat=52.37&focus.point.lon=4.89` // bias toward your service area
);
const { features } = await res.json();
const [lon, lat] = features[0].geometry.coordinates; // [lon, lat]
const label = features[0].properties.label;          // "Damrak, Amsterdam, North Holland, Netherlands"

تفصيلان مهمان هنا. مرّر focus.point قريبًا من منطقة خدمتك حتى تُحلّ «Cambridge» إلى المدينة الصحيحة، وتعامل مع الحالة التي يشارك فيها الزائر GPS الجهاز بدل الكتابة: عندها لديك الإحداثية سلفًا وتتخطى هذه الخطوة كليًا.

الخطوة 2: رتّب متاجرك حسب المسافة

الآن لديك إحداثية الزائر. أما المتاجر نفسها فهي بياناتك الخاصة: قائمة فروع، لكل منها خط عرض وخط طول، تعيش في قاعدة بياناتك. ترتيبها حساب مسافة مستقيمة (haversine)، دون أي استدعاء API:

// Your branches, each with a lat/lon. Rank by distance from the visitor.
const ranked = stores
  .map(s => ({ ...s, distance_m: haversine(lat, lon, s.lat, s.lon) }))
  .sort((a, b) => a.distance_m - b.distance_m)
  .slice(0, 6);

هذا كل ما يحتاجه محدد أساسي. لشبكة كبيرة، ستُرشّح أولًا إلى صندوق حدود حول الزائر حتى لا تقيس المسافة إلى كل فرع في كل طلب، ثم ترتّب الناجين. المخرجات قائمة قصيرة بأقرب الفروع، لكل منها distance_m.

الخطوة 3: رتّب بالمسافة ثم اضبط بزمن السفر

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

لمحدد يعني فيه «الأقرب» حقًا «الأسرع وصولًا»، أعِد ترتيب أفضل بضعة مرشحين بزمن السفر الحقيقي عبر استدعاء directions أو matrix:

// Re-rank the closest stores by real drive time (MapAtlas Matrix API)
const res = await fetch(`https://gateway.mapmetrics-atlas.net/matrix/?token=${API_TOKEN}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sources: [{ lat, lon }],
    targets: top3.map(s => ({ lat: s.lat, lon: s.lon })),
    costing: 'auto', // 'auto' | 'bicycle' | 'pedestrian'
  }),
});
const { sources_to_targets } = await res.json();
const row = sources_to_targets[0]; // one entry per target, each with .time (seconds)
const byTime = top3
  .map((s, i) => ({ ...s, time: row[i].time }))
  .sort((a, b) => a.time - b.time);

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

الخطوة 4: اعرض المتاجر على خريطة

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

امنح كل علامة نافذة منبثقة بالأساسيات التي يحتاجها الزائر ليتصرف: الاسم، والعنوان، والمسافة، وساعات العمل، ورابط «الاتجاهات» الذي يُسلّم الإحداثية إلى محرك توجيه.

تفاصيل تفصل النموذج التجريبي عن الإنتاج

نتائج فارغة. يبحث أحدهم من منطقة ليس لديك فيها فروع. قرّر مسبقًا: هل توسّع النطاق تلقائيًا، أم تعرض أقرب متجر واحد مهما بَعُد، أم تقول بصراحة «لا توجد متاجر ضمن 50 كم».

ساعات العمل. المحدد الذي يعرض متجرًا كأقرب خيار وهو مغلق مُحبِط. رشّح أو علّم حسب ساعات العمل حتى يصير «مفتوح الآن» خيارًا من الدرجة الأولى.

مُدخل غامض. «Cambridge» موجودة في إنجلترا وماساتشوستس، و«Springfield» موجودة عشرات المرات. تحيّز الدولة في خطوة الترميز الجغرافي يزيل معظم هذا، وتقديم الإكمال التلقائي أثناء كتابة الزائر يزيل الباقي.

GPS الجوال والموافقة. على الجوال، أقوى تجربة هي زر «استخدم موقعي»، لكن قراءة GPS الجهاز بيانات موقع وتحتاج إلى موافقة. اسأل أولًا، وارجع إلى الإدخال النصي إن رفض الزائر.

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

بناء store locator مع MapAtlas

تمنحك MapAtlas خط الأنابيب كاملًا من واجهة واحدة ونظام إحداثيات واحد. Geocoding API تحوّل الرموز البريدية والمدن إلى إحداثيات مع تحيّز للدولة، ثم ترتّب أنت قائمة فروعك مقابل تلك الإحداثية، وتُعيد واجهتا Directions وMatrix ترتيب أفضل المرشحين بزمن السفر الحقيقي، وتعرض مربعات Dynamic Maps النتيجة، تمامًا كما هو موضّح في هذا المقال. ولأن كل ذلك يعمل داخل الاتحاد الأوروبي افتراضيًا، يبقى موقع الزائر داخل المنطقة الاقتصادية الأوروبية، ما يُبقي المحدد متوافقًا مع GDPR دون عمل إضافي.

صيغ الطلب والاستجابة الكاملة لكل نقطة نهاية موجودة في توثيق MapAtlas API. كما تستحق Search API نظرة إن أردت للمحدد أن يكتشف نقاط الاهتمام حول الزائر، لا فروعك وحدها.

store locator خاصية صغيرة تحمل داخلها قدرًا كبيرًا من التقدير الهادئ: فهم المُدخل الغامض، والترتيب بالقرب الحقيقي، واحترام حقيقة أن الموقع بيانات شخصية. اضبط هذه الثلاثة، ويكفّ مربع «ابحث عن أقرب متجر» عن كونه فكرة لاحقة ليصير من أكثر ما يُستخدَم في موقعك.