راقب استخدام مفتاحك قبل أن تبلغ الحد
متابعة ترويسات الحصة أولًا بأول تخبرك متى يقترب الحد، قبل وقت طويل من رفض أي طلب فعليًا.
تحليل حقل عنوان نصي حر إلى مكونات منظمة
حقل العنوان النصي الحر الواحد سهل الجمع وصعب التعامل معه لاحقًا، خصوصًا عندما تحتاج إلى التصفية حسب المدينة أو التجميع حسب المنطقة. والترميز الجغرافي الأمامي يقوم بالتحليل نيابة عنك كأثر جانبي لتحويل العنوان إلى إحداثيات.
إرسال النص الحر
GET /v1/forward?q=1600 Pennsylvania Avenue, Washington, DC 20500&limit=1{
"status": "ok",
"query": "1600 Pennsylvania Avenue, Washington, DC 20500",
"results": [
{
"formatted": "1600 Pennsylvania Avenue NW, Washington, DC 20500",
"lat": 38.8977,
"lon": -77.0365,
"type": "address",
"precision": "house",
"confidence": 0.97,
"place_id": "def456",
"components": {"house_number": "1600", "street": "Pennsylvania Avenue NW", "city": "Washington", "region": "DC", "postcode": "20500", "country": "US"}
}
]
}تخزين المكونات بشكل منفصل
بمجرد حصولك على كائن components، اكتب كل حقل في عمود مستقل في قاعدة البيانات بدلًا من الاحتفاظ بالنص الحر الأصلي فقط. فهذا يتيح تصفية سجلات العملاء حسب المدينة أو المنطقة، وإنشاء تقارير إقليمية دقيقة، والتحقق من أن الرمز البريدي والمدينة ينتميان فعلًا إلى بعضهما، ولا شيء من ذلك عملي مع نص واحد غير منظم.
مثال ثانٍ: عنوان بتنسيق مختلف
بنية العناوين ليست واحدة في كل مكان. فقد يُحلّ عنوان في المملكة المتحدة مع مقاطعة (county) بدلًا من منطقة على الطراز الأمريكي، وقد يغيب مكوّن مثل house_number تمامًا في حالة مبنى له اسم. وإرسال الطلب بالأسلوب نفسه يعمل أيًّا كانت الدولة، لكن مفاتيح المكونات التي تعود إليك فعلًا قد تختلف، لذا صمّم مخطط التخزين لديك بحيث يتحمل غياب أحد المكونات بدلًا من افتراض أن كل دولة تملأ المجموعة نفسها تمامًا في كل مرة.
خطأ شائع يجب تجنبه
لا تثبّت في الكود افتراضًا بأن كل نتيجة ستحتوي على جميع الحقول house_number وstreet وcity وregion وpostcode، ثم تعامل أي عنوان يفتقد أحدها كخطأ في التحليل. فالعنوان الصحيح تمامًا، خصوصًا خارج الشبكات الحضرية المرقّمة بأرقام المنازل، قد يعود بشكل مشروع مع بعض الحقول فارغة. وبناء تحقق صارم حول مجموعة كاملة من المكونات سيرفض مدخلات عملاء حقيقية حللتها نقطة النهاية بشكل صحيح.
الاحتفاظ بالنص الأصلي أيضًا
خزّن المدخل النصي الحر الأصلي إلى جانب المكونات المحللة بدلًا من التخلص منه. فإذا عاد أحد المكونات ناقصًا أو احتاج عميل إلى تصحيح شيء لاحقًا، فإن توفر النص الأصلي يجعل إعادة التحليل أو التصحيح اليدوي أمرًا مباشرًا.
التعامل مع التحليل الجزئي
ليس كل عنوان يُحلّ مع ملء جميع مكوناته. فقد يعود عنوان ريفي دون house_number، وقد تعود بلدة صغيرة دون قيمة منطقة مميزة. تعامل مع حقول المكونات المفقودة على أنها فارغة بشكل مشروع لا كفشل في التحليل، وارجع إلى النص المنسق للعرض عندما لا يكون مكوّن معين أردته موجودًا.
التعامل مع أكثر من مطابقة محتملة
رفع قيمة limit إلى أكثر من 1 يعيد عدة نتائج مرشحة مرتبة حسب مدى مطابقة كل منها للنص الحر، وهذا مفيد عندما تريد أن تعرض على العميل قائمة اختيار قصيرة بدلًا من الاعتماد بصمت على أفضل نتيجة. وهو حل وسط معقول بين التحليل التلقائي الكامل ونموذج الإدخال اليدوي بالكامل، خاصة للعناوين التي كان حد الثقة لديك سيصنفها على أنها غير مؤكدة.
كم يكلف
تحليل حقل نص حر بهذه الطريقة يكلف طلبًا واحدًا لكل عنوان، مثل أي استعلام آخر للترميز الجغرافي الأمامي. ويمكن لمهمة ملء بأثر رجعي تنظف جدولًا قائمًا من العناوين النصية الحرة أن تمر على الجدول كله كطلب مجمّع، بطلب واحد لكل صف.
تحويل النص الحر إلى حقول منظمة نتيجة طبيعية للترميز الجغرافي لعنوان ما، وليس خطوة إضافية. ويسرد توثيق الترميز الجغرافي الأمامي كل مكوّن يمكن أن تعيده نقطة النهاية.