راقب استخدام مفتاحك قبل أن تبلغ الحد
متابعة ترويسات الحصة أولًا بأول تخبرك متى يقترب الحد، قبل وقت طويل من رفض أي طلب فعليًا.
تحديد موقع الزائر جغرافيًا عبر IP دون نص برمجي من طرف ثالث
معظم عمليات تحديد الموقع الجغرافي عبر IP على الويب تتم من خلال وسم JavaScript يتصل بطرف ثالث من متصفح الزائر. وهذا يعني نصًا برمجيًا إضافيًا يجب تحميله، وطلبًا إضافيًا على المتصفح انتظاره، وشيئًا إضافيًا قد يفشل بصمت إذا حظره الزائر.
استعلام من جهة الخادم بدلًا من ذلك
تأخذ نقطة النهاية /v1/ip عنوان IP وتُرجع بيانات الموقع مباشرة. وإذا استدعيتها من الواجهة الخلفية لديك، مستخدمًا عنوان IP الذي يراه خادم الويب لديك أصلًا في الاتصال الوارد، فلن يعمل أي نص برمجي في متصفح الزائر على الإطلاق.
GET /v1/ip?ip=203.0.113.42{
"status": "ok",
"ip": "203.0.113.42",
"version": 4,
"found": true,
"country": "France",
"country_code": "FR",
"region": "Ile-de-France",
"city": "Paris",
"postcode": "75001",
"lat": 48.8566,
"lon": 2.3522,
"timezone": "Europe/Paris",
"asn": 12345,
"org": "Example Networks"
}حذف معامل IP
إذا استدعيت نقطة النهاية هذه دون المعامل ip، فإنها تستعلم عن عنوان المستدعي نفسه، وهذا مناسب حين ترسل الواجهة الخلفية لديك الطلب نيابة عن الزائر المتصل بها حاليًا. أما تمرير المعامل ip صراحة فهو ما تحتاجه حين يكون العنوان مسجّلًا لديك مسبقًا وتستعلم عنه لاحقًا.
ما تحصل عليه
تغطي الدولة والمنطقة والمدينة معظم حالات استخدام التخصيص. ويعني حقل timezone أنك غالبًا لا تحتاج إلى استعلام ثانٍ لمجرد معرفة التوقيت المحلي لذلك الزائر. ويحدد حقلا asn وorg الشبكة التي ينتمي إليها العنوان، وهذا مفيد لأي شيء يتجاوز التخصيص البسيط، مثل التعرف على مزودي الاستضافة أو شبكات الشركات.
حالة حدّية تستحق المعالجة
ليس كل عنوان يُحدَّد له موقع. فقيمة الحقل found تكون false للنطاق المحجوز أو غير المخصص أو غير الموجود ببساطة في مجموعة البيانات، وتكون حقول الموقع غائبة أو فارغة في هذه الحالة. افحص found قبل قراءة country أو city، بدلًا من افتراض أن استجابة HTTP الناجحة تعني دائمًا موقعًا قابلًا للاستخدام، لأن الطلب الخاص بعنوان خاص أو محجوز سيظل يُرجع 200 مع ضبط found على false.
خطأ يستحق التجنب
استدعاء نقطة النهاية هذه عند كل عرض صفحة، بدلًا من مرة واحدة لكل جلسة، هو الطريقة الأكثر شيوعًا التي يستنزف بها موقع ما حصته دون فائدة حقيقية. فعنوان IP الخاص بالزائر، وبالتالي موقعه التقريبي، لا يتغير عادة بين صفحة وأخرى خلال الزيارة نفسها. استعلم عنه مرة واحدة عند بدء الجلسة، وخزّن النتيجة مرتبطة بالجلسة، واقرأ من تلك النسخة المخزّنة في كل صفحة لاحقة بدلًا من استدعاء نقطة النهاية مرة أخرى.
تكلفة الطلبات والحفظ المؤقت
كل استعلام عن IP يُحتسب طلبًا واحدًا. وبما أن موقع الزائر نادرًا ما يتغير خلال جلسة واحدة، استعلم عنه مرة واحدة وخزّن النتيجة طوال الجلسة بدلًا من استدعائه عند كل عرض صفحة. فهذا يُبقي الموقع المعتاد ضمن 2,500 طلب مجاني يوميًا المضمّنة مع كل مفتاح أو المتاحة من عنوان واحد دون مفتاح على الإطلاق، بهامش واسع.
استعلام ذو صلة
تعمل نقطة النهاية نفسها وبنية الاستجابة نفسها مع عناوين IPv6 دون أي تغيير في طلبك، ويخبرك حقل version في الاستجابة بنوع العنوان الذي حصلت عليه. راجع توثيق الاستعلام عن IPv6 إذا كانت زياراتك تتضمن حصة معتبرة من زوار IPv6.
تشغيل هذا من جهة الخادم يُبقي النصوص البرمجية للأطراف الثالثة خارج صفحتك تمامًا، وهذا مهم للسرعة والموثوقية معًا. راجع توثيق الاستعلام عن IPv4 للاطلاع على القائمة الكاملة للحقول.