راقب استخدام مفتاحك قبل أن تبلغ الحد
متابعة ترويسات الحصة أولًا بأول تخبرك متى يقترب الحد، قبل وقت طويل من رفض أي طلب فعليًا.
اجمع بين الرمز البريدي والدولة لاستعلامات أسرع
صُمّم الترميز الجغرافي الأمامي للتعامل مع النص الحر غير المنظم، ما يعني أنه يؤدي عملًا خلف الكواليس لمعرفة نوع المُدخل الذي ينظر إليه. إذا كنت تعلم مسبقًا أن لديك رمزًا بريديًا سليمًا ودولة، فهناك طريق أكثر مباشرة.
الانتقال مباشرة إلى نقطة نهاية الرمز البريدي
بدلًا من تجميع سلسلة نصية حرة وإرسالها إلى /v1/forward، أرسل الرمز والدولة مباشرة إلى /v1/postcode.
GET /v1/postcode?code=90210&country=US{
"status": "ok",
"postcode": "90210",
"country_code": "US",
"results": [
{"lat": 34.0901, "lon": -118.4065, "components": {"city": "Beverly Hills", "region": "CA", "country": "US"}}
]
}لماذا هذا الخيار أنسب
الرمز البريدي مع الدولة مُدخل منظّم بالكامل أصلًا، فلا يوجد غموض على نقطة النهاية أن تحله كما قد يحدث مع سلسلة نصية حرة قد تطابق عدة أماكن متشابهة الصياغة. واستخدام نقطة النهاية المصممة لهذا الشكل من المُدخلات تحديدًا يمنحك تطابقًا أنظف مع خطر أقل للحصول على نتيجة غير متوقعة.
مثال ثانٍ: رمز بريدي يجمع بين الحروف والأرقام
يعمل الاستدعاء نفسه بالطريقة نفسها مع دولة تستخدم الحروف والأرقام معًا بدلًا من الأرقام وحدها.
GET /v1/postcode?code=K1A 0B1&country=CAتمرير معامل الدولة هو ما يجعل ذلك موثوقًا، لأن سلسلة الرمز وحدها ليست فريدة دائمًا بين الدول، ومعامل الدولة هو ما يخبر نقطة النهاية بالنظام البريدي الذي يجب أن تفسّر الرمز وفقه.
متى تظل بحاجة إلى الترميز الجغرافي الأمامي
إذا كنت تحتاج إلى تطابق محدد على مستوى الشارع بدلًا من المنطقة العامة التي يغطيها الرمز البريدي، فإن الترميز الجغرافي الأمامي بالعنوان الكامل يظل الأداة المناسبة، لأن الاستعلام عن الرمز البريدي يعيد المنطقة التي يغطيها الرمز، لا مبنى محددًا داخلها. استخدم /v1/postcode للاستعلامات على مستوى المنطقة مثل التحقق من منطقة شحن، و/v1/forward عندما تحتاج إلى دقة على مستوى المنزل.
خطأ شائع يجب تجنبه
لا تفترض أن الرمز البريدي يقابل دائمًا نقطة واحدة بالضبط تمثل كل عنوان داخله بدقة. الإحداثيات التي تعيدها /v1/postcode تمثل المنطقة التي يغطيها الرمز، والتي قد تكون مربعًا سكنيًا واحدًا في مدينة، أو منطقة أكبر بكثير في بعض الدول. ومعاملة النقطة المُعادة كما لو كانت الموقع الدقيق لمبنى عميل بعينه، بدلًا من نقطة تمثيلية للرمز كله، ستُدخل خطأً في أي شيء يعتمد على المسافة يُبنى فوقها.
الجمع بين الاثنين في سير عمل واحد
من الأنماط الشائعة التحقق أولًا من الرمز البريدي والدولة عبر /v1/postcode، ثم، بعد اجتياز ذلك، إرسال عنوان الشارع الكامل إلى /v1/forward للحصول على الإحداثيات الدقيقة. هذا يعني طلبين لكل إرسال، واحدًا لكل مرحلة، بدلًا من محاولة إجبار نقطة نهاية واحدة على أداء المهمتين.
حالة حدّية: رمز لا يعيد أي نتائج
تعني مصفوفة النتائج الفارغة أن الرمز لم يُتعرّف عليه للدولة المحددة، وهذا وضع يختلف عن استجابة الخطأ. تعامل معه كما تتعامل مع أي مُدخل آخر غير معروف، بأن تطلب من العميل مراجعة ما أدخله، بدلًا من عرضه كخطأ في النظام.
كم يكلف
كل استعلام عن رمز بريدي يُحتسب طلبًا واحدًا، بتكلفة الاستعلام نفسها في الترميز الجغرافي الأمامي. اختيار نقطة النهاية المناسبة للمُدخلات المنظمة لا يغيّر التكلفة، بل يغيّر مدى مباشرة وصولك إلى النتيجة الصحيحة.
اللجوء إلى نقطة نهاية الرمز البريدي حين يكون لديك مُدخل سليم ومنظم أصلًا يجنّبك الغموض الإضافي الناتج عن إعادة بناء سلسلة نصية حرة لمجرد تحليلها وتفكيكها من جديد. التفاصيل الكاملة متوفرة في توثيق الاستعلام عن الرمز البريدي.