راقب استخدام مفتاحك قبل أن تبلغ الحد
متابعة ترويسات الحصة أولًا بأول تخبرك متى يقترب الحد، قبل وقت طويل من رفض أي طلب فعليًا.
حساب المسافة بين نقطتين مرمّزتين جغرافيًا
المسافة بين عنوانين ليست شيئًا تعيده API الترميز الجغرافي مباشرة، لأن حساب المسافة لا يحتاج إلا إلى الإحداثيات، وهي ما تمنحك إياه نقطة النهاية الأمامية أصلًا لأي عنوان ترسله إليها.
الحصول على إحداثيات العنوانين
رمّز كل عنوان جغرافيًا على حدة، أو كليهما معًا في طلب مجمّع واحد، للحصول على زوج من خط العرض وخط الطول لكل منهما.
POST /v1/forward
Content-Type: application/json
["221B Baker Street, London", "10 Downing Street, London"]{
"status": "ok",
"results": [
{"formatted": "221B Baker Street, London, UK", "lat": 51.5237, "lon": -0.1585, "type": "address", "precision": "house", "confidence": 0.95, "place_id": "abc123", "components": {}},
{"formatted": "10 Downing Street, London, UK", "lat": 51.5033, "lon": -0.1276, "type": "address", "precision": "house", "confidence": 0.96, "place_id": "op678", "components": {}}
]
}حساب المسافة
بعد الحصول على زوجي الإحداثيات، طبّق صيغة هافرساين القياسية، التي تحوّل الفرق في خط العرض وخط الطول إلى مسافة بخط مستقيم على سطح الأرض. وتتوفر في معظم لغات البرمجة تطبيقات صغيرة ومختبرة جيدًا لصيغة هافرساين على شكل دالة قصيرة أو مكتبة شائعة، فلا حاجة إلى كتابة حسابات المثلثات من الصفر.
distance_km = haversine(51.5237, -0.1585, 51.5033, -0.1276)خطأ شائع يجب تجنبه
تتوقع صيغة هافرساين خط العرض وخط الطول بالراديان، لكن الإحداثيات في استجابة API تكون دائمًا بالدرجات. وإدخال قيم بالدرجات مباشرة في صيغة مكتوبة للراديان سينتج مسافة تبدو معقولة للوهلة الأولى لكنها خاطئة بصمت بمعامل كبير. حوّل الدرجات إلى راديان أولًا، أو استخدم دالة مكتبة توضح في توثيقها الوحدة التي تتوقعها، وقارن النتيجة بمسافة تعرفها مسبقًا قبل أن تعتمد عليها في بيئة الإنتاج.
مثال ثانٍ: الطول الإجمالي لمسار متعدد المحطات
يمتد الحساب نفسه بشكل طبيعي إلى أكثر من نقطتين. رمّز كل محطة في المسار جغرافيًا في طلب مجمّع واحد، ثم اجمع مسافة هافرساين بين كل زوج متتالٍ من الإحداثيات للحصول على طول تقريبي إجمالي للمسار، وهو مفيد لتقدير سريع لمسار توصيل حتى قبل أن يتوفر لديك توجيه فعلي خطوة بخطوة.
total_km = haversine(a, b) + haversine(b, c) + haversine(c, d)المسافة بخط مستقيم مقابل مسافة التنقل
يعطي حساب هافرساين المسافة بخط مستقيم، لا مسافة القيادة أو المشي على الطرق الفعلية. وفي معظم الاستخدامات، مثل ترتيب المواقع القريبة أو تقدير القرب التقريبي، تكفي المسافة بخط مستقيم ولا تحتاج إلى أكثر من الإحداثيات المتوفرة لديك أصلًا. أما إذا كنت تحتاج تحديدًا إلى مسافة التنقل عبر مسار فعلي، فذلك نوع مختلف من الحساب يقع خارج ما يقدمه استعلام الترميز الجغرافي.
حالة حدّية تستحق المعرفة
قد تُربك نقطتان على جانبين متقابلين من خط الزوال المقابل، أو قريبتان جدًا من أحد القطبين، صيغة مسافة بسيطة لا تراعي التفاف خط الطول من 180 إلى سالب 180. وهذا نادر في عمليات فحص المسافة المعتادة بين عنوانين، لكنه يستحق الاختبار إذا كان تطبيقك يغطي فعلًا ذلك الجزء من الكرة الأرضية.
تكلفة الطلبات
الترميز الجغرافي لعنوانين يكلف طلبين، سواء أُرسلا في استدعاءين منفصلين أم في استدعاء مجمّع واحد. أما حساب المسافة نفسه، بعد الحصول على زوجي الإحداثيات، فيتم بالكامل في شيفرتك الخاصة ولا يكلف شيئًا إضافيًا من حصتك.
إعادة استخدام الإحداثيات المتوفرة لديك
إذا كان أحد العنوانين قد رمّزته جغرافيًا من قبل وخزّنته مؤقتًا، فلا يحتاج إلى طلب جديد إلا العنوان الجديد، مما يخفض تكلفة ذلك الحساب تحديدًا إلى طلب واحد بدلًا من طلبين.
حسابات المسافة لا تبعد سوى طلب ترميز جغرافي واحد لأي عنوان لم تحوّله بعد إلى إحداثيات. راجع توثيق الترميز الجغرافي الأمامي للاطلاع على بنية الاستجابة الكاملة.