تحديد موقع الزائر لموقعك

استدعِ GET /v1/geo مباشرة من متصفح الزائر للحصول على بلد ومدينة ومنطقة زمنية وسياق إقليمي متاح لهذا الاتصال. اضبط مصدرك المسموح به، وأضف مفتاحك القابل للنشر، وقرّر كيف يجب أن يتعامل تطبيقك مع الاستجابة.

احصل على مفتاح API مجاني للزائر اقرأ البدء السريع →

الطلب يأتي من متصفح الزائر

تصف GET /v1/geo دائمًا أي عميل يتصل بها. استدعها من متصفح الزائر لتحصل على بيانات موقع ذلك الاتصال؛ أما الطلب المرسَل من خادم تطبيقك فيصف اتصال الخادم نفسه، لا اتصال الزائر. إذا كان لديك بالفعل عنوان IP لمستخدم نهائي وتحتاج إلى حله من خلفيتك بدلًا من ذلك، استخدم واجهة برمجة البحث عن IP المنفصلة. مفتاح الزائر قابل للنشر — وهو مصمَّم للظهور في كود المتصفح — لذا فإن التحكم الحقيقي هو قائمة المصادر المسموح بها المُهيَّأة له، لا سرّية المفتاح نفسه.

صمّم اقتراحًا، لا إعادة توجيه إجبارية

قد يستخدم المسافر شبكة في بلد ما بينما يفضّل لغة أخرى، ويمكن لشبكة VPN أن تضع الاتصال في مكان مختلف تمامًا. امنح الزوار طريقة واضحة لتغيير اللغة أو البلد أو العملة المقترحة، واحتفظ بذلك الاختيار بدلًا من إعادة اشتقاقه من الموقع في كل زيارة.

سياق الأمان في الخطط المؤهلة فقط

في الخطط التي تتضمنه، يمكن أن تحمل الاستجابة مؤشرات VPN/Tor/تهديد قائمة على قوائم. عدم وجود كائن security يعني أن الحقل غير مُضمَّن في خطتك، لا أن الشبكة وُجدت آمنة؛ والقيمة السلبية تعني عدم وجود تطابق في بيانات المصدر المتاحة، وهو ما لا يعادل شهادة سلامة تامة. تختلف التغطية حسب المؤشر وإصدار IP — على سبيل المثال، لا يُنفَّذ حاليًا اكتشاف Tor عبر IPv6.

سياق مفيد في الاستجابة

country, region, city, latitude, longitude: موقع تقريبي للطلب المتصل. ليس موقع جهاز أو GPS، وليس دليلًا على مكان وجود شخص معيّن.
timezone, currency, callingCode: سياق إقليمي مشتق من الموقع الذي تم حله، مفيد كاقتراح أولي.
asn, asOrganization: الشبكة المتصلة ومشغّلها، عند توفرهما. اسم المنظمة ليس هوية شخص.
security: غير موجود بالكامل ما لم تتضمنه خطتك. عند وجوده: isVpn، isTor، isDatacenter، isThreat، isSanctionedNetwork — مؤشرات قائمة على قوائم، وليست ضمانًا للسلامة.

أضف الطلب الأول

جافاسكريبت المتصفح

async function loadVisitorLocation() {
  const response = await fetch('https://api.watch-ip.com/v1/geo', {
    headers: { 'X-Api-Key': 'YOUR_PUBLISHABLE_KEY' },
  });

  if (!response.ok) {
    throw new Error(`Visitor geolocation failed (${response.status})`);
  }

  const geo = await response.json();
  return { country: geo.country ?? null, city: geo.city ?? null, timezone: geo.timezone ?? null };
}

استبدل القيمة النائبة بمفتاح الزائر الخاص بك وشغّل الصفحة من مصدر مسموح به لذلك المفتاح. حافظ على توفر التجربة الافتراضية لموقعك إذا فشل الطلب أو كان أحد الحقول مفقودًا.

الأسئلة الشائعة

هل يطلب هذا إذن موقع الجهاز؟

لا. لا يستخدم الطلب المعتمد على IP واجهة برمجة تحديد موقع الجهاز في المتصفح — بل يقدّر الموقع من الاتصال بدلًا من طلب الإحداثيات المقدَّمة من الجهاز. تبقى التزاماتك الخاصة بالخصوصية والموافقة معتمدة على كيفية استخدام تطبيقك للنتيجة.

هل يمكنني تمرير عنوان IP إلى /v1/geo؟

لا. تصف نقطة النهاية دائمًا العميل المتصل. استخدم /v1/lookup/{ip} من خلفيتك عندما تريد تقديم عنوان.

لماذا يعرض طلب مُصيَّر من جانب الخادم موقع مزوّد الاستضافة الخاص بي؟

الخادم هو العميل المتصل لذلك الطلب. انقل طلب الزائر إلى كود المتصفح، أو استخدم نقطة نهاية البحث عن IP من خلفيتك بمصدر موثوق لعنوان IP الخاص بالمستخدم النهائي.

هل المدينة أو الإحداثيات دقيقة؟

لا. تحديد الموقع الجغرافي لعنوان IP تقدير مرتبط بالاتصال، وليس الموقع الدقيق لشخص ما.

هل يمكنني استخدام مفتاح سري في المتصفح؟

لا. استخدم مفتاح زائر قابلًا للنشر لهذه النقطة، واحتفظ بمفاتيح البحث السرية في بيئة خلفيتك فقط.