Watch-IP

مرجع واجهة برمجة تحديد الموقع الجغرافي للزائر

GET/v1/geo

تُعيد بيانات الموقع والإثراء المتاحة للعميل المتصل. استدعِها من متصفح الزائر لوصف اتصال ذلك الزائر — أما الطلب من خادم تطبيقك فيصف اتصال الخادم نفسه بدلًا من ذلك.

المصادقة

قدِّم مفتاحًا قابلًا للنشر ومقيَّدًا بالمصدر عبر ترويسة X-Api-Key، أو عبر معامل الاستعلام key كبديل. يأتي التحكم في الوصول من قائمة النطاقات المسموح بها المُهيَّأة للمفتاح، والتي يُتحقق منها مقابل ترويسة Origin/Referer في الطلب — لا من إبقاء المفتاح سريًا، لأنه مصمَّم للظهور في مصدر المتصفح.

حقول الاستجابة

ip
عنوان IP الخاص بالعميل المتصل.
country, region, regionCode, city, postalCode, continent
موقع تقريبي، قابل لأن يكون فارغًا (null) عندما لا تُحدِّده بيانات الحافة (edge) الأساسية.
latitude, longitude
إحداثيات تقريبية للموقع المُحدَّد، وليست موقع جهاز أو GPS.
timezone
اسم المنطقة الزمنية وفق معيار IANA، أو null عند عدم توفرها.
isEUCountry
قيمة منطقية (Boolean)؛ إشارة جغرافية، لا تحديد قانوني.
asn, asOrganization
الشبكة المتصلة ومشغِّلها، عندما تُوفِّرهما البيانات الأساسية؛ وإلا فـ null.
currency, callingCode
سياق إقليمي مُشتق من الدولة المُحدَّدة، أو null.
locale, holidays, compliance, tax, ageVerification
مجموعات إثراء مُشتقة اختيارية، كل منها قابل لأن يكون فارغًا (null) بشكل مستقل. لا تُمثل أي منها تحديدًا قانونيًا أو ضريبيًا أو تحديدًا للهوية.
hostname
لا يظهر إلا عند طلبه عبر ?include=hostname؛ وهو نتيجة بحث DNS عكسي، وتكون null في حال فشله.
security
يُحذف بالكامل في الخطط التي لا تتضمنه. وعند وجوده: isTor وisVpn وisDatacenter وisThreat وisSanctionedNetwork — وهي مؤشرات قائمة على قوائم. لم يُنفَّذ حاليًا كشف Tor عبر IPv6؛ وتعني القيمة false عدم وجود تطابق في البيانات المتاحة، لا غياب المخاطر.

الأخطاء

401
مفتاح API مفقود أو غير صالح.
403
لا يوجد Origin/Referer الخاص بالطلب ضمن قائمة النطاقات المسموح بها للمفتاح. لا يتم تعيين أي ترويسة CORS على هذه الاستجابة، لذا يحظرها المتصفح بصرف النظر عن محتوى JSON.
429
تم تجاوز حد المعدل لنافذة الدقيقة الواحدة الثابتة الحالية.

مثال

الطلب

curl https://api.watch-ip.com/v1/geo \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY"

الاستجابة — على سبيل التوضيح؛ تختلف الحقول حسب الخطة والبيانات المتاحة

{
  "ip": "203.0.113.1",
  "country": "US",
  "region": "Texas",
  "regionCode": "TX",
  "city": "Austin",
  "postalCode": "78701",
  "latitude": 30.2672,
  "longitude": -97.7431,
  "continent": "NA",
  "timezone": "America/Chicago",
  "isEUCountry": false,
  "asn": 12345,
  "asOrganization": "Example ISP",
  "currency": { "code": "USD", "name": "US Dollar", "symbol": "$" },
  "callingCode": "+1"
}

الحدود

يخضع لسقف الطلبات الشهري وحد المعدل لكل دقيقة في خطتك — راجع صفحة التسعير. يُسجَّل كل استدعاء ناجح كحدث استخدام واحد من نوع geo.

صفحات ذات صلة