راقب استخدام مفتاحك قبل أن تبلغ الحد
متابعة ترويسات الحصة أولًا بأول تخبرك متى يقترب الحد، قبل وقت طويل من رفض أي طلب فعليًا.
التعامل مع عناوين بلا رقم منزل
ليس لكل عنوان رقم منزل. فالطرق الريفية وبعض المشروعات السكنية الجديدة والمعالم المعروفة كثيرًا ما يُشار إليها دون رقم، وطلب الترميز الجغرافي المبني على توقع وجود رقم منزل في كل مرة سيسيء فهم الشكل الذي تبدو عليه النتيجة الصالحة لهذه الحالات.
شكل الاستجابة عند غياب رقم المنزل
GET /v1/forward?q=Golden Gate Bridge, San Francisco&limit=1{
"status": "ok",
"query": "Golden Gate Bridge, San Francisco",
"results": [
{
"formatted": "Golden Gate Bridge, San Francisco, CA",
"lat": 37.8199,
"lon": -122.4783,
"type": "address",
"precision": "street",
"confidence": 0.9,
"place_id": "gb567",
"components": {"city": "San Francisco", "region": "CA", "country": "US"}
}
]
}لاحظ أنه لا يوجد حقل house_number في components هنا، وأن قيمة precision هي "street" وليست "house". وكلا الأمرين متوقع لعنوان لا يحتوي فعلًا على رقم منزل، وليسا علامة على استعلام فاشل أو جزئي.
قراءة الدقة بشكل صحيح
تعامل مع precision على أنها وصف لمدى تحديد المطابقة، لا مؤشر على خطأ. فالدقة "house" تعني أن المطابقة حُددت على مبنى بعينه. والدقة "street" تعني أنها حُددت على شارع أو نقطة على امتداده، دون تحديد مبنى بدقة، وهذا صحيح تمامًا لمعلم أو لعنوان يفتقر فعلًا إلى رقم منزل.
مثال ثانٍ: مكان عام معروف
GET /v1/forward?q=Central Park, New York&limit=1المكان العام المسمّى كهذا يُحدَّد عادةً مع قيمة type أوسع من "address" ودقة تعكس منطقة بدلًا من نقطة واحدة، إلى جانب كائن components قد لا يتضمن سوى المدينة والمنطقة. وهذا هو النمط نفسه في مثال الجسر: نتيجة حقيقية ومفيدة توصف بصدق بأنها تغطي منطقة بدلًا من مبنى بعينه، لأن هذا ما كان الاستعلام يشير إليه فعلًا.
تعديل منطق التحقق وفقًا لذلك
إذا كان التحقق في نموذجك يشترط حاليًا وجود حقل house_number قبل قبول العنوان على أنه مكتمل، فإن هذا الفحص سيرفض خطأً عناوين ريفية ومعالم مشروعة. اجعل معايير القبول قائمة على توافق confidence وprecision مع ما تحتاجه فعلًا، بدلًا من اشتراط ملء كل مكوّن بعينه.
خطأ شائع يجب تجنبه
لا تعامل كائن components فارغًا، أو كائنًا تنقصه عدة حقول، على أنه مكافئ لطلب فاشل. فالطلب الفاشل يعود بحالة خطأ ورمز خطأ، كما هو موضح في توثيق الأخطاء. أما النتيجة الناجحة ذات المكوّنات القليلة فهي نتيجة مختلفة وطبيعية تمامًا، والخلط بين الاثنين في معالجة الأخطاء لديك سيؤدي إلى تسجيل عناوين صالحة ومعاملتها على أنها إخفاقات.
السماح للعملاء بالتأكيد بدلًا من الرفض
بالنسبة إلى العنوان الذي لا يحتوي على رقم منزل، فإن عرض النتيجة المنسّقة على العميل لتأكيدها أفضل من رفض الإرسال مباشرة. فهذا يُبقي العنوان الحقيقي قابلًا للاستخدام مع الاستمرار في اكتشاف المُدخلات السيئة فعلًا في مواضع أخرى.
الاتجاه العكسي له النمط نفسه
الترميز الجغرافي العكسي لإحداثية تقع في ريف مفتوح أو في الماء قد يعود كذلك بدقة أقل تفصيلًا ومكوّنات مملوءة أقل من إحداثية تقع على مساحة مبنى بعينه. ويصف توثيق الترميز الجغرافي العكسي قيم الدقة نفسها من ذلك الاتجاه.
التكلفة تبقى كما هي
العنوان الذي لا يحتوي على رقم منزل يكلّف الطلب الواحد نفسه الذي يكلّفه أي استعلام ترميز جغرافي أمامي آخر. ولا شيء في غياب المكوّنات يغيّر طريقة احتساب الطلب من حصتك اليومية أو رصيدك.
التعامل الصحيح مع هذا يتعلق في الغالب بقراءة precision وconfidence كما هو مقصود منهما، بدلًا من افتراض أن كل عنوان صالح يجب أن يملأ كل مكوّن بالكامل. ويشرح توثيق الترميز الجغرافي الأمامي كل حقل بالتفصيل.