مرجع واجهة برمجة البحث المجمّع عن عناوين IP

POST/v1/lookup

النسخة المجمّعة (batch) من GET /v1/lookup/{ip} — تُحلِّل حتى 100 عنوان IPv4/IPv6 في طلب واحد من الخلفية (Backend)، وتُعاد بالترتيب نفسه الذي أُرسلت به.

المصادقة

قدِّم مفتاحًا سريًا عبر Authorization: Bearer YOUR_SECRET_KEY، وهو نوع المفتاح نفسه المستخدم في نقطة نهاية البحث عن عنوان IP واحد.

محتوى الطلب

ips: مصفوفة من 1 إلى 100 سلسلة نصية لعناوين IPv4/IPv6. يُتحقق من الدفعة بأكملها قبل تشغيل أي بحث — عنوان واحد غير صحيح التنسيق يُفشل الاستدعاء بأكمله.

الأخطاء

400: مصفوفة ips فارغة، أو أكثر من 100 عنوان IP، أو عنوان غير صحيح التنسيق في أي مكان ضمن المصفوفة.
401: مفتاح API مفقود أو غير صالح.
403: تم استخدام مفتاح قابل للنشر بدلًا من مفتاح سري.
429: تم تجاوز حد المعدل لنافذة الدقيقة الواحدة الحالية.

مثال

الطلب

curl https://api.watch-ip.com/v1/lookup \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["203.0.113.1", "2001:db8::1"]}'

الاستجابة

{
  "results": [
    { "ip": "203.0.113.1", "country": "US", "region": "TX", "city": "Austin", "postalCode": null, "latitude": 30.2672, "longitude": -97.7431, "continent": "NA", "timezone": null, "found": true },
    { "ip": "2001:db8::1", "country": null, "region": null, "city": null, "postalCode": null, "latitude": null, "longitude": null, "continent": null, "timezone": null, "found": false }
  ]
}

الحدود

يُفوتَر ويُسجَّل كل عنوان IP في الدفعة على حدة — فاستدعاء لـ 100 عنوان IP يُسجِّل 100 حدث استخدام من نوع lookup، لا حدثًا واحدًا. العنوان المُرسَل مرتين يُفوتَر مرتين. بالنسبة إلى حد المعدل في الدقيقة، يُحتسب الاستدعاء بأكمله طلبًا واحدًا. بيانات الموقع لهذه النقطة مُقدَّمة من DB-IP (IP Geolocation by DB-IP، db-ip.com — CC BY 4.0).