مرجع واجهة برمجة البحث عن عنوان IP
GET/v1/lookup/{ip}
تُحلِّل عنوان IPv4 أو IPv6 واحدًا تُقدِّمه، باستخدام قاعدة بيانات جهة خارجية لتحديد المواقع الجغرافية وأرقام الأنظمة المستقلة (ASN) — وهي مصدر بيانات وشكل استجابة مختلفان عن GET /v1/geo. للاستخدام من خادم إلى خادم فقط؛ استدعِها من الخلفية (Backend) الخاصة بك، ولا تستدعِها أبدًا من متصفح.
المصادقة
قدِّم مفتاحًا سريًا عبر Authorization: Bearer YOUR_SECRET_KEY. وخلافًا للمفتاح القابل للنشر الذي تستخدمه GET /v1/geo، يجب أن يبقى هذا المفتاح على خادمك — استخدام مفتاح قابل للنشر هنا يُعيد 403.
حقول الاستجابة
- ip
- عنوان IP الذي قدَّمته، مُعاد كما هو.
- country, city, continent
- موقع تقريبي من قاعدة البيانات المصدر، أو null عند عدم توفره.
- region
- رمز تقسيم فرعي (مثل "TX")، وليس اسم منطقة — وهو شكل مختلف عن حقل region في GET /v1/geo.
- postalCode, timezone
- لا يُملأ هذا الحقل من قاعدة البيانات المصدر الحالية — تكون قيمته null دائمًا.
- latitude, longitude
- إحداثيات تقريبية، أو null عند عدم توفرها.
- found
- تكون false عندما لا يوجد سجل مطابق لعنوان IP أو عندما تكون قاعدة البيانات الأساسية غير متاحة مؤقتًا — ولا يُميّز هذا الحقل بين الحالتين.
الأخطاء
- 400
- عنوان IP المُقدَّم ليس عنوان IPv4 أو IPv6 صالحًا.
- 401
- مفتاح API مفقود أو غير صالح.
- 403
- تم استخدام مفتاح قابل للنشر بدلًا من مفتاح سري.
- 429
- تم تجاوز حد المعدل لنافذة الدقيقة الواحدة الحالية.
مثال
الطلب
curl https://api.watch-ip.com/v1/lookup/203.0.113.1 \
-H "Authorization: Bearer YOUR_SECRET_KEY"الاستجابة
{
"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 يُبحث عنه، بمعزل عن حجم طلبات خطة تحديد موقع الزائر لديك — راجع صفحة منتج البحث عن عنوان IP لمعرفة التسعير والإتاحة. تحتاج إلى أكثر من عنوان IP واحد في كل استدعاء؟ استخدم نقطة النهاية المجمّعة بدلًا من ذلك. بيانات الموقع لهذه النقطة مُقدَّمة من DB-IP (IP Geolocation by DB-IP، db-ip.com — CC BY 4.0).