مرجع API

نقاط نهاية بسيطة ومتّسقة. CORS مفعّل. لا حاجة لمصادقة. متعدد اللغات بالكامل — تُترجم كل مفاتيح وقيم الحقول إلى أكثر من 10 لغات.

رابط القاعدة

https://ipto.to

البدء السريع

# Detect your own IP
curl https://ipto.to/v1/ip

# Look up any IP
curl https://ipto.to/v1/ip/8.8.8.8

# Bulk lookup (up to 100 IPs, Pro/Enterprise only)
curl -X POST https://ipto.to/v1/ip/bulk \
  -H "Content-Type: application/json" \
  --data '["1.1.1.1","8.8.8.8","9.9.9.9"]'

اختصار الطرفية: يعمل أيضاً كل من curl ipto.to أو curl ipto.to/8.8.8.8 (دون الحاجة إلى https:// أو /v1/ip/) عندما يصل الطلب من curl أو Wget أو HTTPie — يُكتشف ذلك عبر User-Agent. يُعيد هذا مجموعة حقول أقصر بأسلوب ipinfo.io (ip, country, city, asn, org, ...)، وليس المخطط الكامل أدناه — استخدم مسارات /v1/ip مباشرة للحصول على الاستجابة الكاملة الموثقة في هذه الصفحة.

عنوان IP فقط: يُعيد curl ipto.to/ip (أو فتحه في المتصفح) عنوان IP الخاص بك فقط كنص عادي — 73.9.114.155، دون JSON ودون أي عناصر واجهة للصفحة. مكافئ مباشر لـ ipinfo.io/ip. راجع GET /ip أدناه.

متعدد اللغات تلقائيًا: اضبط ?lang= على أي رمز مدعوم، وستعود كل مفاتيح وقيم JSON في الاستجابة مُترجمة — ليس فقط الدولة/القارة. راجع التوطين أدناه للحصول على قائمة اللغات الكاملة وخيار إلغاء التفعيل &localize=0.

curl "https://ipto.to/v1/ip/8.8.8.8?lang=de"
# "landesname":"Vereinigte Staaten","ist_vpn":false, ...
# every key & value comes back translated -- add &localize=0 for the legacy English-keys shape

Lookup Lab

ابنِ أي طلب إلى ipto، وانسخه كشيفرة جاهزة للتشغيل بلغتك، أو أرسله هنا مباشرة واقرأ الاستجابة الحية. لا تحتاج الخطة المجانية إلى مفتاح.

خادم MCP

يمكن الوصول إلى ipto أيضاً كخادم أدوات MCP (بروتوكول سياق النموذج) — وجّه Claude Desktop أو Cursor أو أي عميل يدعم MCP إلى نقطة النهاية أدناه، وستتاح لك 14 أداة قابلة للاستدعاء: ip_lookup، bulk_ip_lookup (Pro/Enterprise)، asn_lookup، country_lookup، reverse_dns_lookup، user_agent_parse، phone_lookup، email_lookup، fraud_score، language_detect، currency_convert، weather_lookup، trademark_lookup، وpatent_lookup. يعتمد على JSON-RPC 2.0 عبر Streamable HTTP — POST فقط، دون الحاجة إلى جلسة أو SSE. نفس مصادقة REST API: يمكن حذفها في الخطة المجانية (1,000 طلب/يوم حسب IP)، أو إضافة ?api_key= إلى رابط نقطة النهاية.

{
  "mcpServers": {
    "ipto": { "url": "https://ipto.to/mcp" }
  }
}

للعملاء الذين يدعمون stdio فقط، اربطه عبر: npx mcp-remote https://ipto.to/mcp

curl -X POST https://ipto.to/mcp \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ip_lookup","arguments":{"ip":"8.8.8.8"}}}'

نقاط النهاية

GET/ip

لا يُعيد شيئاً سوى عنوان IP العام الخاص بالعميل الطالب، كنص عادي (Content-Type: text/plain) — مثال: 73.9.114.155. مكافئ مباشر لـ ipinfo.io/ip: يعمل بنفس الطريقة من curl أو Wget أو HTTPie أو زيارة عادية عبر المتصفح (دون اكتشاف User-Agent، على عكس اختصار curl ipto.to أعلاه)، ويُعرض كعنوان IP مجرد دون أي عناصر واجهة للصفحة عند فتحه في المتصفح.

دون معاملات، ودون سلسلة استعلام. للحصول على كائن الموقع الجغرافي/الاستخبارات الأمنية الكامل، استخدم GET /v1/ip أدناه بدلاً من ذلك. يقرأ هذا المسار عنوان IP المتصل مباشرة (دون بحث في D1/KV) ولا يُحتسب ضمن ميزانية الطلبات اليومية — راجع حدود الطلبات.

curl https://ipto.to/ip
# 203.0.113.7

GET/v1/ip

يُعيد بيانات الموقع الجغرافي والاستخبارات الأمنية لعنوان IP الطالب، بما في ذلك بيانات على مستوى المدينة عبر كائن CF edge.

دون معاملات مطلوبة. يقبل ?lang= و?fields= و?format= — راجع التوطين وصيغ الإخراج أدناه.

curl https://ipto.to/v1/ip
# the lookup for the calling IP: same shape as /v1/ip/:ip below

GET/v1/ip/:ip

ابحث عن أي عنوان IPv4. تُملأ الحقول على مستوى المدينة (city, state, postal_code, latitude, longitude, timezone) عندما يقع عنوان IP ضمن أحد مجموعتي البيانات الجغرافية المدمجتين، IP2Location أو MaxMind — تحقق من geo_precision في الاستجابة لمعرفة ما إذا حصلت على بيانات على مستوى المدينة أو الدولة. تعتمد صيغة timezone على المصدر المطابق (سلسلة إزاحة UTC من IP2Location، أو اسم IANA من MaxMind). عمليات بحث IPv6 تُعيد حالياً بيانات على مستوى الدولة فقط.

Parameter	In	Description
`ip`	path	مطلوب. أي عنوان IPv4 أو IPv6 صالح.
`lang`	query	اختياري. يُوطّن country_name وcontinent: en (افتراضي)، pt, fr, de, zh-TW, ko, zh-CN, ja-JP, es-ES, ar-SA, hi-IN.
`fields`	query	اختياري. قائمة حقول مفصولة بفواصل لتضمينها. مثال: ?fields=ip,country_code,is_vpn
`format`	query	اختياري. صيغة الاستجابة: json (افتراضي)، csv، text، xml، yaml.

curl https://ipto.to/v1/ip/8.8.8.8

# only the fields you want:
curl "https://ipto.to/v1/ip/8.8.8.8?fields=ip,asn,country_code,city"
# {"ip":"8.8.8.8","asn":15169,"country_code":"US","city":"Mountain View"}

GET/v1/search/:query

نقطة نهاية البحث الموحدة خلف شريط البحث في الصفحة الرئيسية. تكتشف ما إذا كان :query عنوان IP، أو ASN (AS15169 أو 15169)، أو رمز دولة من حرفين، أو بريداً إلكترونياً، أو رقم هاتف، ثم تجمع كل فحص ذي صلة في استجابة واحدة. بالنسبة لاستعلام IP، يتوزع هذا — بالتوازي، من جانب الخادم — إلى بحث IP الأساسي بالإضافة إلى RPKI، وربط IP بالشركة، ومزود الشبكة الجوالة، والنطاقات المستضافة، والأماكن، بحيث يستهلك بحث واحد فقط طلباً واحداً من ميزانية حد الطلبات اليومية بدلاً من طلب لكل ميزة.

Parameter	In	Description
`query`	path	مطلوب. عنوان IP، أو ASN، أو رمز دولة، أو بريد إلكتروني، أو رقم هاتف.

Field	Type	Description
`query`	string	المدخل بعد فك ترميزه كما وصل.
`detected_type`	string	"ip" أو "asn" أو "country" أو "email" أو "phone".
`ip`	object\|null	موجود عندما تكون detected_type هي "ip" — بنفس شكل GET /v1/ip/:ip.
`rpki`	object\|null	موجود لاستعلامات IP — بنفس شكل GET /v1/ip/:ip/rpki.
`company`	object\|null	موجود لاستعلامات IP — بنفس شكل GET /v1/ip/:ip/company.
`whois`	object\|null	موجود لاستعلامات IP — بنفس شكل GET /v1/ip/:ip/whois.
`carrier`	object\|null	موجود لاستعلامات IP — بنفس شكل GET /v1/ip/:ip/carrier.
`asn / country / email / phone`	object\|null	موجود بدلاً من الحقول الستة أعلاه عندما تتطابق detected_type — بنفس شكل نقطة النهاية المخصصة لذلك النوع.

يتدهور كل حقل فرعي بشكل مستقل — أي تأخر أو فشل في مصدر خارجي (RIPEstat، خادم RDAP، crt.sh) يظهر كحقل واحد فقط يكون null، وليس كفشل للبحث بأكمله. فقط الاستعلام الأساسي غير الصالح (مثل عنوان IP مشوّه) يُعيد حالة خطأ للطلب ككل.

curl https://ipto.to/v1/search/8.8.8.8

GET/v1/ip/:ip/hostname

DNS العكسي — بحث PTR حي واحد عبر DNS-over-HTTPS، وليس قاعدة بيانات لتعداد النطاقات. يُعيد null إذا لم يكن لعنوان IP سجل PTR.

Parameter	In	Description
`ip`	path	مطلوب. أي عنوان IPv4 أو IPv6 صالح.

curl https://ipto.to/v1/ip/8.8.8.8/hostname
# {"ip":"8.8.8.8","hostname":"dns.google"}

GET/v1/ip/:ip/rpki

التحقق من صحة منشأ المسار عبر RPKI للمسار المُعلن حالياً لعنوان IP، ويُحل مباشرة عبر RIPEstat (دون استيعاب أو مزامنة قاعدة بيانات ROA محلياً). لا تكون status سوى "valid" أو "invalid" أو "unknown" — ولا تُشتق مطلقاً من أي إشارة أخرى؛ أي فشل أو انتهاء مهلة في RIPEstat يُعيد "unknown" مع سلسلة سبب، وليس خطأ.

Parameter	In	Description
`ip`	path	مطلوب. أي عنوان IPv4 أو IPv6 صالح.

Field	Type	Description
`asn`	integer\|null	رقم ASN المُعلن حالياً، ويُحل مباشرة — وليس مشتقاً من مجموعة بيانات ASN الخاصة بهذا الموقع.
`prefix`	string\|null	بادئة CIDR المُعلنة حالياً.
`status`	string	"valid" أو "invalid" أو "unknown".
`validating_roas`	array	سجل (سجلات) ROA المحددة التي طابقها RIPEstat، كل منها مع origin/prefix/max_length/validity.
`validator`	string\|null	أداة التحقق من RPKI التي استخدمها RIPEstat (مثال: "routinator").
`reason`	string\|null	يشرح نتيجة "unknown" — مثال: عدم وجود ROA مغطية، أو تعذر الوصول إلى RIPEstat.

curl https://ipto.to/v1/ip/8.8.8.8/rpki
# {"ip":"8.8.8.8","asn":15169,"prefix":"8.8.8.0/24","status":"valid",...}

GET/v1/rpki

التحقق الصريح من RPKI لـ (ASN، بادئة) — لعندما تعرف مسبقاً المسار الدقيق الذي تريد فحصه، بدلاً من الأداة المشتقة من IP أعلاه.

Parameter	In	Description
`asn`	query	مطلوب. رقم ASN، مع أو بدون بادئة AS. مثال: 15169 أو AS15169.
`prefix`	query	مطلوب. بادئة CIDR، مثال: 8.8.8.0/24.

curl "https://ipto.to/v1/rpki?asn=15169&prefix=8.8.8.0/24"

GET/v1/ip/:ip/company

يحدد المؤسسة المسجل لديها عنوان IP من خلال دمج بيانات المسجّل من RDAP (WHOIS منظم) مع اسم مؤسسة ASN نفسها في درجة ثقة تصنيفية، وليس درجة رقمية أبداً.

Parameter	In	Description
`ip`	path	مطلوب. أي عنوان IPv4 أو IPv6 صالح.

Field	Type	Description
`company_name`	string\|null	اسم الشركة الذي تم تحديده — يكون null عندما تكون confidence بقيمة "low" (المصدران مختلفان، فلا يُقدَّم أي منهما كمرجع موثوق) أو "none".
`rdap_org_name`	string\|null	اسم المسجّل من RDAP، بشكل مستقل عن company_name.
`asn_org_name`	string\|null	اسم مؤسسة ASN نفسها، بشكل مستقل عن company_name.
`confidence`	string	"high" (تتفق المصادر)، أو "medium" (مصدر واحد فقط متاح)، أو "low" (تختلف المصادر — يُعرض كلاهما)، أو "none".
`reason`	string	شرح واضح لمستوى الثقة.

curl https://ipto.to/v1/ip/1.1.1.1/company
# {"ip":"1.1.1.1","company_name":null,"rdap_org_name":"APNIC Research and Development","asn_org_name":"Cloudflare, Inc.","confidence":"low",...}

GET/v1/ip/:ip/whois

سجل تسجيل RDAP الأساسي نفسه — نطاق الشبكة، وتواريخ التسجيل/آخر تعديل، وكل جهة اتصال مسجلة لدى RDAP. يختلف عن /company أعلاه، التي توفّق بين بيانات المسجّل نفسها واسم مؤسسة ASN في إجابة واحدة بدرجة ثقة؛ تُعيد نقطة النهاية هذه السجل الخام كما هو، وهو أقرب إلى إخراج WHOIS التقليدي. عناوين IPv6 مدعومة أيضاً.

Parameter	In	Description
`ip`	path	مطلوب. أي عنوان IPv4 أو IPv6 صالح.

Field	Type	Description
`available`	boolean	false إذا تعذر حل أي سجل RDAP — راجع reason.
`reason`	string\|null	يشرح نتيجة available: false.
`startAddress / endAddress / cidr`	string\|null	نطاق الشبكة المسجل.
`netName / netHandle / parentHandle`	string\|null	معرّفات مخصصة من RIR لكائن الشبكة.
`country`	string\|null	دولة المسجِّل، وفق RDAP.
`allocationType`	string\|null	مثال: "direct allocation"، "reassigned".
`registeredDate / lastChangedDate`	string\|null	طوابع زمنية ISO من سجل RDAP.
`rir`	string\|null	أي سجل إقليمي (ARIN، RIPE، APNIC، LACNIC، AFRINIC) قدّم السجل.
`contacts`	array	كل جهة اتصال مسجلة لدى RDAP، مع الأدوار والاسم والبريد الإلكتروني والمعرّف لكل منها — وليس أول تطابق فقط.

curl https://ipto.to/v1/ip/8.8.8.8/whois
# {"ip":"8.8.8.8","available":true,"cidr":"8.8.8.0/24","netName":"LVLT-GOGL-8-8-8","rir":"ARIN","contacts":[...],...}

GET/v1/ip/:ip/carrier

تحديد أفضل جهد لمزود الشبكة الجوالة لعناوين IP المصنفة كشبكات جوالة، بالمقارنة مع دليل مشغلي MCC/MNC. لا يحتوي عمداً على حقل واحد للمشغل — راجع matched_carrier_entries وnote أدناه — لأن اسم مشغل مجرد سيُقرأ كادعاء حي لكل مشترك، وهو ما لا يمكن لهذه البيانات دعمه بأمانة.

Parameter	In	Description
`ip`	path	مطلوب. أي عنوان IPv4 أو IPv6 صالح.

Field	Type	Description
`is_mobile_network`	boolean	false يوقف البحث هنا بدليل فارغ — دون تخمين لـ ASN غير جوال.
`asn_organization`	string\|null	اسم مؤسسة ASN نفسها.
`matched_carrier_entries`	array	صفوف دليل MCC/MNC التي يتطابق اسم مشغلها تقريبياً مع asn_organization، ضمن نطاق دولة عنوان IP نفسه.
`note`	string	يشرح ما يمكن وما لا يمكن لهذا الحقل ادعاءه.

curl https://ipto.to/v1/ip/8.8.8.8/carrier
# {"ip":"8.8.8.8","is_mobile_network":false,"asn_organization":null,"matched_carrier_entries":[],...}

GET/v1/ip/:ip/hosted-domains

يجد النطاقات المرتبطة بعنوان IP عبر اسم مضيف DNS العكسي (PTR) الخاص به وسجلات شفافية الشهادات (crt.sh) — وليس بحث IP عكسي عام. يوضح حقل limitations في الاستجابة نفسها بدقة ما يمكن وما لا يمكن لهذا إيجاده.

Parameter	In	Description
`ip`	path	مطلوب. أي عنوان IPv4 أو IPv6 صالح.

Field	Type	Description
`ptr_hostname`	string\|null	اسم مضيف DNS العكسي لعنوان IP، أو null إذا لم يكن له سجل PTR.
`root_domain`	string\|null	النطاق القابل للتسجيل المشتق من ptr_hostname.
`subdomains_seen`	array\|null	نطاقات فرعية عُثر عليها عبر شفافية الشهادات. تعني null أن بحث crt.sh نفسه لم يكتمل — بخلاف مصفوفة فارغة، التي تعني أنه اكتمل ولم يجد شيئاً.
`limitations`	string	يشرح ما لا يمكن لهذه الميزة اكتشافه من حيث البنية (دون PTR، الاستضافة المشتركة، النطاقات غير الموثقة بشهادة).

curl https://ipto.to/v1/ip/8.8.8.8/hosted-domains
# {"ip":"8.8.8.8","ptr_hostname":"dns.google","root_domain":"dns.google","subdomains_seen":["dns.google","dns.google.com",...],...}

POST/v1/ip/bulk

بحث دفعي — حتى 100 عنوان IP لكل طلب، حصراً لخطتي Pro/Enterprise. يُعيد كائناً مفهرساً بكل عنوان IP كمفتاح. أسرع من الطلبات المتسلسلة بفضل قراءات متوازية للذاكرة المؤقتة وقاعدة البيانات. يُحتسب كل عنوان IP في الدفعة ضمن ميزانية طلباتك اليومية، تماماً كما لو بحثت عنه بشكل منفرد. طلبات الخطة المجانية تحصل على 403 — راجع الأسعار.

Parameter	In	Description
`body`	body (JSON)	مصفوفة JSON من سلاسل عناوين IP. مثال: ["1.1.1.1","8.8.8.8"]

curl -X POST https://ipto.to/v1/ip/bulk \
  -H "Content-Type: application/json" \
  --data '["1.1.1.1","8.8.8.8"]'

GET/v1/asn/:asn

ابحث عن نظام مستقل باستخدام رقمه. يُعيد اسم المؤسسة، والدولة، والقارة، وعدد نطاقات IP، ونوع التصنيف، وسعر الصرف، وبيانات مرجعية محلية (اللغات، النطاق، العاصمة، الحدود).

Parameter	In	Description
`asn`	path	رقم ASN دون بادئة AS. مثال: 15169 لجوجل.
`lang`	query	اختياري. يُوطّن country_name وcontinent: en (افتراضي)، pt, fr, de, zh-TW, ko, zh-CN, ja-JP, es-ES, ar-SA, hi-IN.
`format`	query	اختياري. صيغة الاستجابة: json (افتراضي)، csv، text، xml، yaml.

curl https://ipto.to/v1/asn/15169

GET/v1/places/:ip

يحدد الموقع الجغرافي العكسي للموقع الحالي على مستوى المدينة لعنوان IP، ثم يُعيد نقاط اهتمام قريبة (مطاعم، حدائق، مدارس، مواصلات، معالم بارزة)، وبيانات جريمة محلية حيثما توفر مصدر لها (المملكة المتحدة والولايات المتحدة فقط)، وتقديراً اختيارياً عند الطلب لمدة التنقل بالسيارة.

Parameter	In	Description
`ip`	path	مطلوب. أي عنوان IPv4 صالح. لا يُدعم IPv6 بعد.
`dest_lat`	query	اختياري. خط العرض للوجهة لتقدير مدة التنقل — يُستخدم مع dest_lon.
`dest_lon`	query	اختياري. خط الطول للوجهة لتقدير مدة التنقل — يُستخدم مع dest_lat.
`dest_address`	query	اختياري. عنوان الوجهة كنص حر لتقدير مدة التنقل، يُحوَّل تلقائياً إلى إحداثيات جغرافية. يُتجاهل إذا تم توفير dest_lat/dest_lon أيضاً.

Field	Type	Description
`geocode`	object\|null	country, countryCode, region, city, neighbourhood, displayName — تكون null إذا لم يكن لعنوان IP موقع على مستوى المدينة لتحويله إلى إحداثيات.
`locality.restaurants / .parks / .schools / .transit`	array	حتى 4 مدخلات أقرب لكل فئة، كل منها مع name وdistanceMeters.
`locality.notable`	array	معالم بارزة قريبة مع وصف مختصر، عبر Wikidata.
`locality.usCrime`	object\|null	إجماليات الجرائم العنيفة/ضد الممتلكات لأقرب جهة — الولايات المتحدة فقط، يتطلب FBI_CRIME_API_KEY على النشر. تكون null في كل مكان آخر.
`locality.ukCrime`	object\|null	ملخص حوادث على مستوى الشارع ضمن نطاق ميل واحد — بريطانيا فقط.
`locality.caCrime`	null	دائماً null — لا يوجد مصدر جرائم مفعّل على مستوى كندا (راجع docs/places.md).
`commute`	object\|null	durationMinutes وdistanceKm، فقط عند توفير وجهة وإرجاع OpenRouteService لمسار. تكون null خلاف ذلك — لا تُحسب تخمينياً أبداً.

curl https://ipto.to/v1/places/8.8.8.8
curl "https://ipto.to/v1/places/8.8.8.8?dest_address=Space+Needle,+Seattle"

GET/v1/country/:code

إحصاءات إجمالية على مستوى الدولة بالإضافة إلى بيانات مرجعية محلية (العملة، سعر الصرف، اللغات، النطاق، العاصمة، الحدود).

Parameter	In	Description
`code`	path	رمز دولة ISO 3166-1 alpha-2. مثال: US، DE، JP.
`lang`	query	اختياري. يُوطّن country_name وcontinent: en (افتراضي)، pt, fr, de, zh-TW, ko, zh-CN, ja-JP, es-ES, ar-SA, hi-IN.
`format`	query	اختياري. صيغة الاستجابة: json (افتراضي)، csv، text، xml، yaml.

curl https://ipto.to/v1/country/US
# {"country_code":"US","country_name":"United States","continent":"North America","currency_code":"USD",
#  "calling_code":"+1","languages":["English"],"tld":[".us"],"capital":"Washington D.C.","borders":["CA","MX"],
#  "is_eu":false,"ip_range_count":151633,"ip_range_count_v6":30329,"asn_count":18243, ...}

GET/v1/ua

يحلل سلسلة User-Agent. يُعيد المتصفح، ونظام التشغيل، ونوع الجهاز، واكتشاف البوتات. يقرأ رأس User-Agent الخاص بالطالب افتراضياً، أو مرّر أي سلسلة عبر ?ua=.

Parameter	In	Description
`ua`	query	اختياري. سلسلة User-Agent مشفرة بترميز URL لتحليلها. يفترض رأس User-Agent الخاص بالطلب افتراضياً.

curl "https://ipto.to/v1/ua?ua=Mozilla%2F5.0+%28iPhone%3B+CPU+iPhone+OS+17_0%29"

GET/v1/phone/:number

يتحقق من صحة رقم هاتف وينسّقه مجاناً دائماً: المنطقة، ونوع الخط، والتنسيق بصيغ E.164/الوطنية/الدولية عبر محلل مستضاف ذاتياً، دون أي استدعاء لمزوّد خارجي. عندما تتوفر ميزانية متقدمة شهرية لكل IP/مفتاح (100/شهرياً في الخطة المجانية، وأكثر في الخطط المدفوعة — راجع الأسعار)، يُعيد الطلب نفسه أيضاً اسم مشغل الشبكة الحالي، وحالة نقل الرقم، ونوع هاتف مصنّف من قِبل المزوّد، من خدمة بحث عن مشغلي الشبكات في الوقت الفعلي — راجع source والحقول أدناه. يُدرَج دائماً اسم دولة مُترجَم country_name مع lang/lang_source، بغضّ النظر عن المستوى — راجع التوطين. عند استنفاد الميزانية المتقدمة، أو حدوث أي مشكلة في المصدر الأعلى، يعود الطلب بسلاسة إلى الحقول المجانية أعلاه؛ ولا يفشل الطلب أبداً بسبب ذلك. للحصول على بيانات مرجعية لمشغلي الشبكات على مستوى الدولة بدلاً من البحث حسب الرقم، راجع GET /v1/carriers.

Parameter	In	Description
`number`	path	مطلوب. أي رقم هاتف، ويُفضّل بصيغة E.164 (مثال: +14155552671). يجب ترميز علامة + في بداية الرقم بترميز URL.
`country`	query	اختياري. تلميح برمز دولة من حرفين لتحليل الأرقام ذات الصيغة الوطنية الغامضة، مثال: ?country=US.
`mode`	query	اختياري. يطلب ?mode=current مشغل الشبكة الحالي في الوقت الفعلي للرقم (بدلاً من المُصدر عبر شريحة SIM)، عندما تكون الطبقة المتقدمة متاحة. يُتجاهل إذا رجع الطلب إلى الخطة المجانية.

Field	Type	Description
`valid`	boolean	true إذا كان الرقم يطابق نمطاً صالحاً لخطة الترقيم في منطقته.
`country_code`	string\|null	منطقة ISO 3166-1 alpha-2 التي ينتمي إليها الرقم.
`national_format`	string\|null	منسّق وفق الاصطلاح الوطني الخاص بالمنطقة.
`international_format`	string\|null	منسّق مع رمز الدولة والمسافات، مثال: "+1 415 555 2671".
`e164`	string\|null	الصيغة القياسية E.164، مثال: "+14155552671".
`line_type`	string\|null	FIXED_LINE أو MOBILE أو FIXED_LINE_OR_MOBILE أو VOIP أو TOLL_FREE أو PREMIUM_RATE أو ما شابه. لا يمكن لكثير من خطط الترقيم (بما فيها خطة أمريكا الشمالية) تمييز الخط الثابت عن الجوال من الرقم وحده.
`source`	string	"premium" إذا كانت هناك ميزانية بحث مباشر عن مشغل الشبكة متاحة لهذا الطلب، أو "local" إذا رجع إلى المحلل المجاني أعلاه. لا تُملأ carrier وphone_type وoriginal_carrier وis_ported وphone_region وcountry_prefix أدناه إلا عندما يكون source هو "premium" — أما country_name وlang/lang_source أدناه فتُملأ دائماً، بغضّ النظر عن المستوى.
`phone_type`	string\|null	إحدى فئات مزوّد البحث عن مشغلي الشبكات في الوقت الفعلي الخاصة به: mobile أو fixed_line أو voip أو toll_free أو premium_rate أو shared_cost أو personal_number أو pager أو uan أو voicemail أو unknown — وليست الفئات الأربع الأولى فقط، فهي مجرد الأمثلة الأكثر شيوعاً. تكون null عندما يكون source هو "local" — وتختلف عن line_type أعلاه، الذي يأتي من المحلل المحلي ويستخدم مجموعة فئات مختلفة.
`carrier`	string\|null	اسم مشغل الشبكة الحالي للرقم. تكون null عندما يكون source هو "local".
`original_carrier`	string\|null	مشغل الشبكة الذي صدر عليه الرقم أصلاً، إذا تم نقله منذ ذلك الحين. تكون null عندما يكون source هو "local" أو لم يتم نقل الرقم.
`is_ported`	boolean\|null	true إذا تم نقل الرقم خارج مشغل شبكته الأصلي. تكون null عندما يكون source هو "local".
`phone_region`	string\|null	تفاصيل على مستوى الموقع المحلي/الولاية للرقم (مثال: "California")، وهي أدق من country_code أعلاه. تكون null عندما يكون source هو "local".
`country_prefix`	string\|null	مفتاح الاتصال الدولي للرقم دون علامة "+" في البداية (مثال: "49" لألمانيا). تكون null عندما يكون source هو "local".
`country_name`	string\|null	اسم الدولة الكامل (مثال: "Germany") — بينما يكون country_code أعلاه بصيغة ISO alpha-2 فقط ("DE")، وليس اسماً معروضاً. خلافاً للحقول المتقدمة أعلاه، يُملأ هذا الحقل دائماً (متى تَوفَّر country_code)، ويُترجَم عبر `?lang=`/`Accept-Language` بنفس طريقة حقل `country_name` في أي نقطة نهاية أخرى — راجع `lang`/`lang_source` أدناه.
`lang`	string	اللغة التي طُبّقت فعلياً على country_name أعلاه — قيمة `?lang=` التي تمّ حلّها، أو "en" إذا لم يُطلب أي شيء أو كانت اللغة المطلوبة غير مدعومة.
`lang_source`	string	"param" إذا كان `?lang=` موجوداً في الطلب، أو "header" إذا استُخدم `Accept-Language` بدلاً منه، أو "default" إذا لم يكن أيّ منهما موجوداً واستُخدمت الإنجليزية. له نفس معنى الحقل المطابق في GET /v1/asn/:asn وGET /v1/country/:code.

curl "https://ipto.to/v1/phone/+14155552671"

POST/v1/phone/bulk

تحقق دفعي. تحصل كل الخطط على وصول جماعي (بخلاف /v1/ip/bulk) — الحد الأقصى للدفعة لكل خطة هو ما يبقي الخطة المجانية محدودة، وليس رمز 403. المجانية: 10/طلب، 100/يوم. Pro: 100/طلب، 1,000/يوم. Enterprise: 1,000/طلب، 10,000/يوم. هذه الميزانية منفصلة عن حد طلباتك اليومي العام — راجع حدود الطلبات.

Parameter	In	Description
`body`	body (JSON)	مصفوفة JSON من سلاسل أرقام هواتف.

curl -X POST https://ipto.to/v1/phone/bulk \
  -H "Content-Type: application/json" \
  --data '["+14155552671","+442071838750"]'

GET/v1/carriers

بحث مرجعي: أي مشغلي شبكات جوالة (MCC/MNC) معروفون لدولة معينة — غير مرتبط برقم هاتف محدد. مصدره تجميع MCC/MNC يحافظ عليه المجتمع (مرخص بموجب MIT، آخر مزامنة 2026 — راجع مستودع الوثائق للتفاصيل)؛ جدول مرجعي ثابت، وليس تغذية حية، لأن تخصيصات خطط الترقيم لا تتغير بوتيرة تستدعي ذلك.

Parameter	In	Description
`country`	query	مطلوب. رمز دولة من حرفين، مثال: ?country=US.

curl "https://ipto.to/v1/carriers?country=US"

GET/v1/email/:email

التحقق من صيغة البريد الإلكتروني، وفحص حي لسجل MX عبر DNS-over-HTTPS، واكتشاف النطاقات المؤقتة/القابلة للتصرف مقابل قائمة حظر يحافظ عليها المجتمع (مرخصة بموجب CC0، تُزامن يومياً). لا يتحقق من وجود صندوق البريد نفسه — يتطلب ذلك مصافحة SMTP لا تنفذها هذه الواجهة (راجع مرجع الحقول أدناه لمعرفة بالضبط ما يثبته has_mx وما لا يثبته).

Parameter	In	Description
`email`	path	مطلوب. أي عنوان بريد إلكتروني، مشفر بترميز URL (يجب ترميز @ كـ %40).

Field	Type	Description
`valid_syntax`	boolean	true إذا كان العنوان يطابق نمط صيغة بريد إلكتروني قياسية. لا يتحقق من وجود صندوق البريد.
`domain`	string\|null	جزء النطاق، بأحرف صغيرة. تكون null إذا كانت valid_syntax بقيمة false.
`has_mx`	boolean\|null	true إذا كان للنطاق سجل MX واحد على الأقل الآن. تكون null إذا كانت الصيغة غير صالحة أو فشل استعلام DNS نفسه أو انتهت مهلته — عامل null كقيمة غير معروفة، وليس كـ false.
`disposable`	boolean\|null	true إذا كان النطاق يطابق مزود بريد إلكتروني مؤقت/قابل للتصرف معروفاً. تكون null بنفس شروط has_mx.
`source`	"premium"\|"local"	"premium" إذا تم تشغيل فحص فوري لهذا الطلب، أو "local" إذا لم يتم ذلك (تم الوصول إلى الحد، أو الميزة غير مفعّلة) — الحقول أعلاه (من valid_syntax إلى disposable) تكون دائماً معبأة في كلتا الحالتين.
`is_reachable`	string\|null	الحكم الإجمالي من فحص فوري اختياري: "safe" (قابل للتسليم)، "invalid" (مرفوض)، "risky" (غير مؤكد)، أو "unknown" (غير حاسم — حاول مرة أخرى). تكون null عندما لا يتم تشغيل الفحص الفوري لهذا الطلب (راجع source أدناه).
`is_catch_all`	boolean\|null	true إذا كان النطاق يقبل البريد لأي عنوان، مما يعني أنه تعذر تأكيد وجود صندوق البريد المحدد هذا. تكون null عندما لا يتم تشغيل الفحص الفوري.
`mailbox_full`	boolean\|null	true إذا وجد الفحص الفوري أن صندوق البريد ممتلئ. تكون null عندما لا يتم تشغيل الفحص الفوري.
`is_role_account`	boolean\|null	true إذا بدا العنوان وكأنه حساب وظيفي (مثل support@، admin@) وليس صندوق بريد لفرد. تكون null عندما لا يتم تشغيل الفحص الفوري.
`is_disabled`	boolean\|null	true إذا وجد الفحص الفوري أن صندوق البريد معطّل صراحةً. تكون null عندما لا يتم تشغيل الفحص الفوري.

curl "https://ipto.to/v1/email/user%40example.com"
# When the live-verification budget allows, the same response also includes the
# source/is_reachable/is_catch_all/mailbox_full/is_role_account/is_disabled fields above:
# {"email":"user@example.com","valid_syntax":true,"domain":"example.com","has_mx":true,
#  "disposable":false,"source":"premium","is_reachable":"safe","is_catch_all":false,
#  "mailbox_full":false,"is_role_account":false,"is_disabled":false}

GET/v1/fraud-score

يجمع أياً مما تقدمه من IP والبريد الإلكتروني ورقم الهاتف وUser-Agent في درجة واحدة من 0–100 — وهو الأمر الوحيد الذي لا يقدمه أي من ip-api.com أو ipapi.co أو ipgeolocation.io أو ipify.org أو ipregistry.co أو ip2location.io أو AbstractAPI أو IPLocate.io أو BigDataCloud كإشارة مدمجة واحدة (تم التحقق من ذلك مباشرة). المدخلات الأربعة كلها اختيارية ومستقلة — مرّر أي مجموعة فرعية منها. يفترض ip عنوان IP الخاص بك وua رأس User-Agent الخاص بك إذا أُغفلا، بنفس اصطلاح GET /v1/ip وGET /v1/ua. أي إشارة لا تمررها تكون غائبة ببساطة عن الاستجابة، وليست مصنفة كنظيفة — يُعاد توزيع وزنها على الإشارات التي قدمتها فعلاً.

Parameter	In	Description
`ip`	query	اختياري. يفترض عنوان IP الخاص بك افتراضياً. لا يُقيَّم IPv6 بعد (نفس قيود بقية واجهة بيانات التهديدات).
`email`	query	اختياري. أي عنوان بريد إلكتروني.
`phone`	query	اختياري. أي رقم هاتف.
`ua`	query	اختياري. يفترض رأس User-Agent الخاص بك افتراضياً.

Field	Type	Description
`score`	integer	درجة مركبة موزونة من 0-100 عبر أي إشارات قُدمت.
`risk_tier`	string	"low" (<20)، أو "medium" (20-44)، أو "high" (45-69)، أو "critical" (70+).
`signals`	object	تفصيل لكل مدخل — تظهر فقط مفاتيح المدخلات التي قدمتها فعلاً: ip، email، phone، user_agent. يتضمن كل منها درجته الفرعية الخاصة بالإضافة إلى نفس الحقول التي تُعيدها بالفعل GET /v1/ip/:ip، وGET /v1/email/:email، وGET /v1/phone/:number، وGET /v1/ua لذلك المدخل.

curl "https://ipto.to/v1/fraud-score?ip=1.2.3.4&email=test%40mailinator.com"

GET/v1/screenshot

يُصيّر رابطاً في نسخة حقيقية من Chrome بدون واجهة رسومية (Cloudflare Browser Rendering، وليس مزود خارج لخدمة لقطات الشاشة) ويُعيد ملف PNG. تُرفض الأهداف الداخلية/الخاصة (localhost، نطاقات RFC 1918، عناوين link-local/بيانات تعريف السحابة) قبل تشغيل المتصفح أصلاً. يخضع لحدود منصة Browser Rendering الخاصة به، وهي أكثر صرامة بكثير من بقية هذه الواجهة — توقع أن يتوقف هذا مبكراً قبل أن تصل إلى ميزانية طلباتك اليومية المعتادة على خطط Cloudflare الأدنى.

Parameter	In	Description
`url`	query	مطلوب. يجب أن يكون http أو https.

curl "https://ipto.to/v1/screenshot?url=https://example.com" --output screenshot.png

GET/v1/language

يحدد لغة نص ما عبر تحليل محلي لتردد الثلاثيات الحرفية — دون استدعاء مزود خارجي، ودون استدلال بنموذج ذكاء اصطناعي، ودون تسجيل. المدخل الأقل من 10 أحرف يُعيد لغة null؛ الأقل من نحو 30 حرفاً قد يُعيد تخميناً أفضل لكنه سيكون reliable بقيمة false.

Parameter	In	Description
`text`	query	مطلوب. حتى 5,000 حرف — يُقتطع المدخل الأطول، ولا يُرفض.

Field	Type	Description
`language`	object\|null	code (ISO 639-1)، وiso639_3، وname، وlocal_name لأفضل تطابق. تكون null إذا كان النص قصيراً جداً أو غير معروف ("und").
`reliable`	boolean	false للمدخلات القصيرة — تعامل مع النتيجة كتخمين، وليس تطابقاً موثوقاً.
`candidates`	array	حتى 5 لغات مرشحة تالية بدرجات نسبية، للأزواج اللغوية المتقاربة.

curl "https://ipto.to/v1/language?text=Bonjour%2C+comment+allez-vous%3F"

GET/v1/currency/convert

يحوّل مبلغاً بين عملتين (154 عملة مدعومة) باستخدام نفس تغذية سعر الصرف المرجعي اليومي التي تُشغّل بالفعل currency_code/exchange_rate_usd في كل بحث عن IP وASN ودولة — مُتاحة هنا كنقطة نهاية تحويل مستقلة بدلاً من تضمينها داخل استجابة الموقع الجغرافي.

Parameter	In	Description
`from`	query	مطلوب. رمز عملة ISO 4217 من 3 أحرف.
`to`	query	مطلوب. رمز عملة ISO 4217 من 3 أحرف.
`amount`	query	اختياري. القيمة الافتراضية 1.

Field	Type	Description
`result`	number	المبلغ المحوّل.
`rate`	number	وحدات to لكل وحدة واحدة من from.
`updated`	string	الطابع الزمني بصيغة ISO لمزامنة سعر الصرف المرجعي المستخدم في هذا التحويل.

curl "https://ipto.to/v1/currency/convert?from=USD&to=EUR&amount=100"

GET/v1/currency/rates

جدول أسعار صرف كامل (154 عملة) مُعاد احتسابه مقابل أي عملة مدعومة، وليس USD فقط.

Parameter	In	Description
`base`	query	اختياري. القيمة الافتراضية USD.

Field	Type	Description
`rates`	object	خريطة من رمز العملة → سعر الصرف مقابل base.

curl "https://ipto.to/v1/currency/rates?base=EUR"

GET/v1/currency/history

سجل تاريخي لسعر الصرف المرجعي اليومي لزوج عملات واحد، حتى 90 يوماً إلى الوراء — البيانات وراء مخطط اتجاه السعر في أداة محول العملات. تُملأ مرة واحدة بأثر رجعي، ثم تُضاف يومياً بواسطة نفس المهمة المجدولة التي تحدّث GET /v1/currency/convert. هذا سعر مرجعي يومي واحد عبر الزمن، وليس فرق سعر عرض/طلب في التداول.

Parameter	In	Description
`target`	query	مطلوب. رمز عملة ISO 4217 من 3 أحرف لرسمه بيانياً.
`base`	query	اختياري. القيمة الافتراضية USD.
`days`	query	اختياري. واحدة من 30 أو 60 أو 90. القيمة الافتراضية 30.

Field	Type	Description
`series`	array	مصفوفة نقاط { date, rate } بترتيب تصاعدي حسب التاريخ.
`stats`	object	min وavg وmax وcurrent عبر السلسلة المُعادة.

curl "https://ipto.to/v1/currency/history?base=USD&target=EUR&days=90"

GET/v1/weather

الأحوال الحالية — ومع detail=1، توقعات بالساعة وتوقعات متعددة الأيام — لاسم مكان أو رمز بريدي أو زوج "lat,lon"، أو لـ lat + lon أو ip. تتولى هيئة الأرصاد الجوية الوطنية (National Weather Service) أماكن الولايات المتحدة، وتتولى MET Norway بقية العالم. أضف include= للحصول على الوثيقة الكاملة مع الوحدات وحتى 9 أيام والشمس والقمر والتحذيرات الرسمية وغيرها — راجع بطاقة include أدناه. تكتشف أداة weather-lookup أيضًا موقع المستدعي نفسه تلقائيًا في المتصفح قبل استدعاء هذه النقطة صراحةً.

Parameter	In	Description
`q`	query	اسم مدينة أو رمز بريدي أو "lat,lon" (بحد أقصى 100 حرف). أو مرّر lat وlon، أو ip، بدلًا منها. واحد من الثلاثة مطلوب.
`detail`	query	اختياري. تضيف "1" pressure_mb/visibility_km/dewpoint_c/sunrise/sunset/إلخ إلى weather، بالإضافة إلى كائن forecast (بالساعة + يومي). محذوفة افتراضياً.

Field	Type	Description
`condition`	string\|null	وصف نصي مختصر.
`temp_c / temp_f`	number\|null	درجة الحرارة الحالية.
`feels_like_c`	number\|null	درجة الحرارة "المحسوسة" بالسيليزيوس.
`humidity_pct`	number\|null	الرطوبة النسبية.
`wind_kmph / wind_dir`	number\|null / string\|null	سرعة الرياح واتجاه البوصلة بنقاطها الـ16.
`uv_index`	number\|null	مؤشر الأشعة فوق البنفسجية.
`location`	object\|null	الاسم والمنطقة والدولة وخط العرض/الطول المحلول للمكان المستعلم عنه — وليس المدخل الخام فقط.
`forecast.hourly[]`	array	detail=1 فقط. الساعات الـ24 القادمة بخطوات كل 3 ساعات: hour_label، temp_c/temp_f، weather_code، chance_of_rain_pct.
`forecast.daily[]`	array	detail=1 فقط. توقعات 3 أيام: date، day_label، weather_code، condition، chance_of_rain_pct، max/min temp_c/temp_f.

curl "https://ipto.to/v1/weather?q=Tokyo"

curl "https://ipto.to/v1/weather?q=Tokyo&detail=1"

GET/v1/trademark/:serial

وكيل حي لنظام USPTO للحالة والاسترجاع الخاص بالعلامات التجارية (TSDR) لحالة القضية عبر رقم تسلسلي من 8 أرقام — استدعاء مباشر لكل طلب، وليس نسخة مخزنة مؤقتاً أو مُعاد بيعها. بيانات حالة القضية عمل حكومي أمريكي وملكية عامة وفق شروط استخدام USPTO نفسها، لذا تحمل كل استجابة حقل source/attribution بدلاً من تخزينها أو إعادة بيعها بصمت. بيانات شعار/صورة العلامة التجارية خارج النطاق عمداً — تفصل شروط USPTO ترخيص الصور بشكل منفصل عن بيانات نص حالة القضية التي تُعيدها نقطة النهاية هذه. البحث برقم التسجيل غير مدعوم بعد؛ توثق USPTO اليوم مسار الرقم التسلسلي فقط. جرّبها في أداة البحث عن العلامات التجارية.

Parameter	In	Description
`serial`	path	مطلوب. 8 أرقام بالضبط، مثال: 98267877.

Field	Type	Description
`source`	string	دائماً "USPTO TSDR".
`attribution`	string	سطر إسناد مطلوب وفق شروط استخدام USPTO.
`data`	object	حمولة حالة القضية الخام كما أعادتها USPTO، تُمرر كما هي دون إعادة تشكيل — تم التأكد من عملها بشكل حي بتاريخ 2026-08-12. ضمن `data.trademarks[0]`: `status` (تواريخ الإيداع/التسجيل، و`markElement`، و`descOfMark`، و`tm5StatusDesc`)، و`parties.ownerGroups` (اسم/عنوان المالك حسب الدور)، و`gsList[]` (وصف السلع/الخدمات وفئاتها)، و`prosecutionHistory[]` (الجدول الزمني الكامل للقضية). يختلف وجود الحقول حسب حالة الطلب — مثلاً، الطلب المعلّق لا يملك بعد `usRegistrationNumber`.

curl "https://ipto.to/v1/trademark/98267877" # ANTHROPIC, Reg. No. 8296420

GET/v1/patent/:number

وكيل حي لواجهة USPTO لملف تتبع البراءات (بوابة البيانات المفتوحة) لحالة المنح عبر رقم براءة استخدام من 7-8 أرقام — استدعاء مباشر لكل طلب، وليس نسخة مخزنة مؤقتاً أو مُعاد بيعها. تم التأكد من إغلاق المصدر المستهدف أصلاً (واجهة بحث PatentsView) بتاريخ 2026-03-20؛ يُستخدم هذا كوكيل لخليفته الحي بدلاً منه. بيانات ملف تتبع البراءات عمل حكومي أمريكي وملكية عامة وفق شروط استخدام USPTO نفسها، لذا تحمل كل استجابة حقل source/attribution. النطاق يتمحور حول الطلب/التتبع — دون رسم بياني للاستشهادات، أو عائلة براءات، أو حقل الحالة القانونية، أو صور بالطريقة التي تعرضها Lens.org أو Espacenet أو Google Patents. تبدأ التغطية من الطلبات المودعة عام 2001. براءات التصميم والنباتات وإعادة الإصدار غير مدعومة بعد؛ براءات الاستخدام فقط برقم البراءة الممنوحة. جرّبها في أداة البحث عن البراءات.

Parameter	In	Description
`number`	path	مطلوب. 7-8 أرقام، مثال: 12393227. رقم براءة استخدام ممنوحة فقط، وليس رقم طلب.

Field	Type	Description
`source`	string	دائماً "USPTO Patent File Wrapper".
`attribution`	string	سطر إسناد مطلوب وفق شروط استخدام USPTO.
`data`	object	حمولة سجل التتبع الخام كما أعادتها USPTO، تُمرر كما هي دون إعادة تشكيل — تم التأكد من عملها بشكل حي بتاريخ 2026-08-12 مقابل براءات حقيقية (12393227، 9935534). الحقول الرئيسية: `applicationMetaData` (`inventionTitle`، و`filingDate`، و`applicationStatusDescriptionText`، و`applicationStatusDate`، و`patentNumber`، و`inventorBag[]`)، و`recordAttorney.attorneyBag[]`، و`applicationNumberText`، و`eventDataBag[]` (الجدول الزمني الكامل للتتبع). يُعيد `404` إذا لم يكن الرقم موجوداً، أو كان براءة تصميم/نباتات/إعادة إصدار، أو يسبق تغطية عام 2001.

curl "https://ipto.to/v1/patent/12393227" # WEARABLE COMPUTING DEVICE, granted 2025

GET/v1/feeds

تغذية مقسمة إلى صفحات لـ VPN وTor واستخبارات التهديدات. 200 مدخل لكل صفحة. يتضمن كل مدخل IP/CIDR، وإسناد المزود، ومزود خدمة الإنترنت، والدولة، ونوع التصنيف.

Parameter	In	Description
`page`	query	رقم صفحة يبدأ من 0. الافتراضي: 0.
`type`	query	تصفية حسب النوع: VPN، Tor Exit Node، Tor Node، High-Risk Threat Intel.
`q`	query	تصفية حسب جزء من نص IP أو CIDR.

curl "https://ipto.to/v1/feeds?page=0&type=VPN"
# {"metadata":{...},"pagination":{"page":0,"page_size":200,"total":11200,"total_pages":56,"has_next":true},
#  "ranges":[{"ip":"2.26.157.0/24","type":"VPN","provider":"Datacamp Limited","isp":"Datacamp Limited","country":"GB"}, ...]}

GET/v1/feeds/stats

بيانات وصفية فقط — إجمالي عدد المدخلات، والأعداد حسب المصدر، ووقت آخر مزامنة. لا يُعيد بيانات IP.

curl https://ipto.to/v1/feeds/stats
# {"total_tracked_ranges":34561,"last_updated":"2026-10-06T18:00:44.321Z",
#  "sources":[{"name":"X4BNet VPN Ranges","type":"VPN","count":11200}, ...]}

GET/v1/abuse

نطاقات شبكات مسيئة مقسمة إلى صفحات. مصنفة من 1 إلى 10 حسب توافق عدة تغذيات. مستويات الخطورة: critical (8-10)، high (5-7)، medium (3-4).

Parameter	In	Description
`page`	query	رقم صفحة يبدأ من 0. الافتراضي: 0.
`tier`	query	تصفية حسب مستوى الخطورة: critical، high، medium.
`q`	query	تصفية حسب جزء من نطاق الشبكة.
`source`	query	اختياري. يصفّي حسب اسم مصدر الخلاصة (feed) تماماً كما يُعاد في source_feed، مثال: 'Spamhaus DROP' أو 'IPsum Threat Intel'.

curl "https://ipto.to/v1/abuse?page=0&tier=critical&source=Spamhaus%20DROP"
# {"metadata":{...},"pagination":{"page":0,"page_size":200,"total":1640,"total_pages":9,"has_next":true},
#  "networks":[{"network_range":"1.10.16.0/20","abuse_score":10,"risk_tier":"critical","source_feed":"Spamhaus DROP"}, ...]}

GET/v1/abuse/stats

بيانات وصفية فقط — إجمالي عدد الشبكات، والأعداد حسب المصدر، وتوزيع مستويات الخطورة، ووقت آخر مزامنة.

curl https://ipto.to/v1/abuse/stats
# {"total_networks_tracked":18300,"last_updated":"2026-10-06T18:00:15.762Z",
#  "classification":{"ipsum_threat_intel":16660,"spamhaus_drop":1641,"spamhaus_edrop":0},
#  "sources":[{"name":"IPsum Threat Intel","count":16660}, ...]}

GET/v1/datasets/:kind

تصدير CSV قابل للتنزيل لمجموعات البيانات المفتوحة التي تعتمد عليها الواجهة أصلاً — نفس البيانات، دون ترخيص جديد. تتوفر asn وranges دائماً؛ تُعيد geo-city الرمز 503 حتى تُفعّل مجموعة بيانات ذلك المصدر على نشر معين. تُصدّر geo-city صفوف مصدر جغرافي واحد الخام في كل مرة، وليس عرضاً مدمجاً — مرّر ?source=primary (افتراضي) أو ?source=secondary.

Parameter	In	Description
`kind`	path	واحدة من: asn، ranges، geo-city.
`source`	query	لـ geo-city فقط. primary (افتراضي) أو secondary.

curl -OJ https://ipto.to/v1/datasets/asn
curl -OJ https://ipto.to/v1/datasets/ranges
curl -OJ "https://ipto.to/v1/datasets/geo-city?source=secondary"

POST/v1/keys

يصدر مفتاح API فوراً — دون بريد إلكتروني، ودون تسجيل. يبدأ كل مفتاح في الخطة المجانية (1,000 طلب/يوم؛ البحث الجماعي غير مشمول). تفتح مفاتيح Pro وEnterprise حدوداً يومية أعلى وبحثاً جماعياً (حتى 100 عنوان IP لكل طلب) — راجع الأسعار. احفظ المفتاح — لا يمكن استرجاعه لاحقاً.

curl -X POST https://ipto.to/v1/keys

GET/v1/keys/usage

تحقق من عدد الطلبات التي أجراها مفتاح ما. مرّر المفتاح في أي طلب /v1/* عبر رأس X-API-Key أو ?api_key= ليتم احتسابه.

Parameter	In	Description
`key`	query	مطلوب. مفتاح تم إرجاعه من POST /v1/keys.

curl "https://ipto.to/v1/keys/usage?key=ipto_xxxxxxxx"

GET/v1/ip/:ip/abuse

جهة الاتصال للإبلاغ عن إساءة الاستخدام الخاصة بالشبكة التي تملك عنوان IP، من RDAP: سجل RIR ومعرّف الشبكة وCIDR الذي يغطيها وصناديق بريد الإبلاغ عن الإساءة. استخدمه لمعرفة أين يجب إرسال البلاغ.

Parameter	In	Description
`ip`	path	عنوان IPv4 أو IPv6.

curl https://ipto.to/v1/ip/8.8.8.8/abuse
# {"available":true,"failure":null,"ip":"8.8.8.8","rir":"arin","network":"GOGL","cidr":"8.8.8.0/24",
#  "contacts":[{"name":"Abuse","email":"network-abuse@google.com","handle":"ABUSE5250-ARIN"}]}

تكون available بقيمة false (مع سبب في failure) عند تعذّر الوصول إلى السجل.

GET/v1/asn/:asn/ranges

نطاقات IP التي يعلن عنها نظام ASN فعلياً، مقسّمة إلى صفحات، ولكل نطاق دولته وعلامات الاستضافة / الجوال / السكني / الروبوت / القائمة السوداء.

Parameter	In	Description
`asn`	path	رقم ASN دون بادئة AS، مثال: 15169.
`limit`	query	عدد النطاقات في الصفحة. الافتراضي 50 والحد الأقصى 200.
`offset`	query	عدد النطاقات المراد تخطيها. الافتراضي 0.

curl "https://ipto.to/v1/asn/15169/ranges?limit=1&offset=0"
# {"asn":15169,"total":153,"limit":1,"offset":0,"ranges":[{"start_ip":"8.8.4.0","end_ip":"8.8.4.255",
#  "country_code":"US","is_hosting":false,"is_mobile":false,"is_residential":false,"is_bot":false,"is_blacklisted":false}]}

GET/v1/asn/:asn/whois

سجل (RDAP) الخاص بنظام ASN: المعرّف والاسم والدولة ونوع التخصيص وتواريخ التسجيل وسجل RIR وجهات الاتصال.

Parameter	In	Description
`asn`	path	رقم ASN دون بادئة AS، مثال: 15169.

curl https://ipto.to/v1/asn/15169/whois
# {"asn":15169,"available":true,"reason":null,"handle":"AS15169","name":"GOOGLE","country":"US",
#  "allocationType":"...","registeredDate":"...","lastChangedDate":"...","rir":"arin","contacts":[...]}

تكون available بقيمة false مع reason عندما يتعذّر الوصول إلى السجل.

GET/v1/asn/:asn/related

أنظمة ASN أخرى يُرجَّح ارتباطها بهذا النظام: أولاً المؤسسة المسجّلة نفسها، ثم الدولة والنوع نفسهما.

Parameter	In	Description
`asn`	path	رقم ASN دون بادئة AS، مثال: 15169.

curl https://ipto.to/v1/asn/15169/related
# {"asn":15169,"related":[{"asn":13949,"name":"SLIDE-INC","org":"Google LLC","country_code":"US","type":null},
#  {"asn":16550,"name":"GOOGLE-PRIVATE-CLOUD","org":"Google LLC","country_code":"US","type":"hosting"}, ...]}

GET/v1/asn/:asn/geo-sample

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

Parameter	In	Description
`asn`	path	رقم ASN دون بادئة AS، مثال: 15169.

curl https://ipto.to/v1/asn/15169/geo-sample
# {"asn":15169,"sampled":true,"sample_size":30,"points":[{"city":"Council Bluffs","state":"Iowa",
#  "country_code":"US","latitude":41.2591,"longitude":-95.8517}, ...],"top_cities":[...]}

عيّنة وليست القائمة الكاملة للنطاقات. استخدم /v1/asn/:asn/ranges للحصول على كل النطاقات.

GET/v1/asn/:asn/hosted-domains

النطاقات المستضافة في نظام ASN، يتم العثور عليها بالبحث العكسي في DNS (PTR) على عيّنة من عناوينه. يتضمن كل إدخال النطاق الجذري واسم المضيف PTR وعنوان IP الذي أُخذت منه العيّنة.

Parameter	In	Description
`asn`	path	رقم ASN دون بادئة AS، مثال: 15169.

curl https://ipto.to/v1/asn/15169/hosted-domains
# {"asn":15169,"sampled":true,"sample_size":5,"domains":[{"root_domain":"googleusercontent.com",
#  "ptr_hostname":"0.0.214.35.bc.googleusercontent.com","sample_ip":"35.214.0.0"}, ...]}

بيانات مأخوذة بالعيّنة، فهي مؤشر على ما يستضيفه نظام ASN وليست قائمة كاملة. لعنوان IP واحد استخدم /v1/ip/:ip/hosted-domains.

GET/v1/asn/:asn/relationships

علاقات BGP لنظام ASN: النظراء ومزودو الخدمة العلويون والعملاء السفليون، مع الأعداد.

Parameter	In	Description
`asn`	path	رقم ASN دون بادئة AS، مثال: 15169.

curl https://ipto.to/v1/asn/15169/relationships
# {"asn":15169,"available":true,"peers":[],"upstreams":[],"downstreams":[],
#  "peer_count":0,"upstream_count":0,"downstream_count":0}

تكون available بقيمة false عند تعذّر الوصول إلى مصدر بيانات BGP. المصفوفات الفارغة مع available: true تعني أنه لم يُبلَّغ عن أي علاقات لنظام ASN هذا.

GET/v1/ip-ranges

دليل لفضاء IPv4: إدخال واحد لكل كتلة /8 مع عدد النطاقات والدول وأنظمة ASN فيها وأبرز دولة. ابدأ من هنا ثم تعمّق عبر /v1/ip-ranges/:a و/v1/ip-ranges/:a/:b.

curl https://ipto.to/v1/ip-ranges
# {"blocks":[{"octet":1,"range_count":814,"country_count":15,"asn_count":182,"top_country":"KR",
#  "top_country_share":35,"top_country_name":"South Korea"}, ...],"data_version":"2026-10-06"}

GET/v1/ip-ranges/:a

كتل /16 داخل كتلة /8 واحدة (مثل 8.0.0.0/8)، مع أعداد النطاقات والدول وأنظمة ASN لكل كتلة.

Parameter	In	Description
`a`	path	الثمانية الأولى (octet)، من 0 إلى 255.

curl https://ipto.to/v1/ip-ranges/8
# {"octet1":8,"cidr":"8.0.0.0/8","blocks":[{"octet":8,"range_count":...,"country_count":...,"asn_count":...,
#  "top_country":"US", ...}, ...]}

GET/v1/ip-ranges/:a/:b

النطاقات المخصّصة داخل كتلة /16 واحدة (مثل 8.8.0.0/16)، لكل منها نظام ASN الذي تنتمي إليه، مع الأعداد لكل كتلة.

Parameter	In	Description
`a`	path	الثمانية الأولى (octet)، من 0 إلى 255.
`b`	path	الثمانية الثانية (octet)، من 0 إلى 255.

curl https://ipto.to/v1/ip-ranges/8/8
# {"octet1":8,"octet2":8,"cidr":"8.8.0.0/16","blocks":[{"octet":1,"range_count":1,"country_count":1,"asn_count":1,
#  "top_country":"US", ...}, ...],"ranges_total":30,"ranges":[...]}

GET/v1/nearby

جزء من حمولة Nearby لإحداثيات معيّنة، ليتمكن العميل من عرض كل جزء فور وصوله: الترميز الجغرافي العكسي أو نقاط الاهتمام أو إحصاءات الجريمة المحلية.

Parameter	In	Description
`lat`	query	خط العرض، مطلوب.
`lon`	query	خط الطول، مطلوب.
`part`	query	أي جزء: geocode أو poi أو crime. تُرجع القيمة غير المعروفة الخطأ 400.
`country`	query	مع part=crime فقط: رمز الدولة وفق ISO. تتوفر بيانات الجريمة لـ US وGB.
`region`	query	مع part=crime فقط: اسم الولاية أو المنطقة، مثال: Utah.
`city`	query	مع part=crime فقط: اسم المدينة، مثال: Orem.
`lang`	query	اختياري. يترجم تسميات الأماكن (الرموز نفسها الواردة في جدول التوطين أعلاه).

curl "https://ipto.to/v1/nearby?lat=40.2969&lon=-111.6948&part=geocode"
# {"geocode":{...reverse-geocoded place...}}

curl "https://ipto.to/v1/nearby?lat=40.2969&lon=-111.6948&part=poi"
# {"locality":{...nearby points of interest...}}

curl "https://ipto.to/v1/nearby?lat=40.2969&lon=-111.6948&part=crime&country=US&region=Utah&city=Orem"
# {"locality":{"ukCrime":null,"usCrime":{"agencyName":"Orem Police Department","agencyType":"City",
#  "distanceKm":4.4,"year":2025,"categories":[{"category":"violent-crime","label":"Violent crime","totalOffenses":129}, ...]}}}

GET/v1/commute

وقت القيادة والمسافة بين نقطتين. مسار سريع: يتخطى الترميز الجغرافي العكسي والبحث عن نقاط الاهتمام اللذين يجريهما /v1/places/:ip.

Parameter	In	Description
`from_lat`	query	خط عرض نقطة الانطلاق، مطلوب.
`from_lon`	query	خط طول نقطة الانطلاق، مطلوب.
`dest_lat`	query	خط عرض الوجهة. استخدمه مع dest_lon أو مرّر dest_address بدلاً منه.
`dest_lon`	query	خط طول الوجهة.
`dest_address`	query	الوجهة كنص حر، يُحدَّد موقعها جغرافياً نيابةً عنك. تُستخدم عند غياب dest_lat/dest_lon.

curl "https://ipto.to/v1/commute?from_lat=40.2969&from_lon=-111.6948&dest_lat=40.7608&dest_lon=-111.8910"
# {"from":{"lat":40.2969,"lon":-111.6948},"to":{"lat":40.7608,"lon":-111.891},
#  "commute":{"durationMinutes":44,"distanceKm":63.5}}

عندما يتعذّر تحديد أي وجهة تتضمن الاستجابة to: null وcommute: null وسلسلة reason.

GET/v1/address-lookup

حمولة /v1/places/:ip مرتبطة بعنوان شارع مكتوب بدلاً من IP: الترميز الجغرافي والمنطقة وتقدير اختياري لوقت التنقل.

Parameter	In	Description
`q`	query	عنوان بنص حر، مطلوب.
`dest_lat`	query	خط عرض الوجهة اختيارياً، لتضمين تقدير وقت التنقل (مع dest_lon).
`dest_lon`	query	خط طول الوجهة اختيارياً.
`dest_address`	query	وجهة اختيارية بنص حر، بدلاً من dest_lat/dest_lon.
`part`	query	يعيد part=geo التسمية والإحداثيات فقط، لعرض أول أسرع.
`lang`	query	اختياري. يترجم تسميات الأماكن (الرموز نفسها الواردة في جدول التوطين أعلاه).

curl "https://ipto.to/v1/address-lookup?q=1600+Pennsylvania+Ave+NW+Washington+DC"
# {"query":"1600 Pennsylvania Ave NW Washington DC","found":true,"label":"...","latitude":38.89,
#  "longitude":-77.03,"geocode":{...},"commute":null,"locality":{...}}

curl "https://ipto.to/v1/address-lookup?q=1600+Pennsylvania+Ave+NW+Washington+DC&part=geo"
# {"query":"...","found":true,"label":"...","latitude":38.89,"longitude":-77.03}

تكون found بقيمة false عند تعذّر الترميز الجغرافي للعنوان.

GET/v1/address-suggest

إكمال تلقائي للعناوين: عدد من الأماكن المطابقة لعنوان جزئي، مع إمكانية تفضيل نقطة معيّنة.

Parameter	In	Description
`q`	query	نص جزئي للعنوان، مطلوب.
`near_lat`	query	خط عرض اختياري لتفضيل النتائج القريبة منه.
`near_lon`	query	خط طول اختياري لتفضيل النتائج القريبة منه.

curl "https://ipto.to/v1/address-suggest?q=1600+Penn&near_lat=38.9&near_lon=-77.0"
# {"suggestions":[{"label":"Penn Quarter, Ward 2, Washington, District of Columbia, United States",
#  "lat":38.8949563,"lon":-77.0224592}, ...]}

GET/v1/weather?include=

وثيقة الطقس الكاملة لاسم مكان أو رمز بريدي أو إحداثيات أو عنوان IP. اختر الكتل التي تحتاجها عبر include: current وhourly وdaily وastro (الشمس والقمر) وsolar وindicators وalerts وmarine وair_quality وnowcast أو all. تأتي أماكن الولايات المتحدة من هيئة الأرصاد الجوية الوطنية (National Weather Service)، وبقية العالم من MET Norway؛ ويوضح meta.source المصدر. بدون include تحصل على الصيغة المبسطة { query, weather } الموضحة أعلاه.

Parameter	In	Description
`q / lat+lon / ip`	query	الموقع: q (مدينة أو رمز بريدي أو "lat,lon")، أو lat وlon، أو ip. واحد من الثلاثة مطلوب.
`country`	query	اختياري. رمز ISO أو اسم الدولة لحسم q الملتبس، مثل country=FR للرمز البريدي 75001.
`include`	query	مطلوب لهذه الصيغة. قيم مفصولة بفواصل: current وhourly وdaily وastro وsolar وindicators وalerts وmarine وair_quality وnowcast أو all.
`units`	query	metric (الافتراضي) أو imperial. تتبع أسماء الحقول الوحدة: يصبح temp_c هو temp_f، ويصبح wind_kmph هو wind_mph، ويصبح precip_mm هو precip_in.
`wind_unit`	query	kmh أو ms أو mph أو kn. يغيّر وحدة الرياح فقط.
`hours`	query	عدد المدخلات الساعية المطلوب إرجاعها، من 1 إلى 240. الافتراضي 48. القريبة ساعية واللاحقة كل 6 ساعات؛ ويوضح step_hours ذلك.
`days`	query	عدد المدخلات اليومية المطلوب إرجاعها، من 1 إلى 9. الافتراضي 7. تغطي بيانات الولايات المتحدة 7 أيام.

curl "https://ipto.to/v1/weather?lat=38.8977&lon=-77.0365&include=current,daily,alerts&days=1"
# {"query":"38.8977,-77.0365","place":{"name":"Washington","region":"DC","country":"United States","country_code":"US",
#  "lat":38.8977,"lon":-77.0365,"timezone":"America/New_York"},
#  "current":{"time":"2026-10-07T12:00-04:00","observed":false,"temp_c":18.9,"feels_like_c":18.9,"humidity_pct":52,"wind_kmph":12.9,
#   "wind_gust_kmph":24.1,"wind_dir":"S","uv_index":5.4,"condition":"Sunny","weather_code":113,"is_day":true, ...},
#  "daily":[{"date":"2026-10-07","tmax_c":22.2,"tmin_c":12.8,"precip_mm":0,"precip_prob_pct":1,"gust_max_kmph":25.9,"uv_index_max":5.4, ...}],
#  "alerts":{"available":true,"source":"NWS","official":true,"items":[]},
#  "meta":{"source":"NOAA National Weather Service","fallback_used":false,"coverage":{"precip_prob":true,"wind_gusts":true, ...},
#   "derived":["current.uv_index","current.wet_bulb", ...],"timezone":"America/New_York", ...}}

curl "https://ipto.to/v1/weather?q=Oslo&include=marine,air_quality,nowcast&units=imperial"
# Norway-only blocks come back with available: true there and available: false everywhere else

يوضح meta.coverage الحقول المتاحة للمكان: احتمال المطر والعواصف الرعدية وهبّات الرياح متاحة في الولايات المتحدة ودول الشمال الأوروبي فقط، وقيمتها null (وليست صفرًا) في غيرها. alerts هي تحذيرات رسمية للولايات المتحدة والنرويج؛ أما marine وair_quality وnowcast فتغطي النرويج والمياه القريبة فقط وتعرض available: false في غيرها. كل ما يظهر في meta.derived تقدير من ipto.to، وindicators علامات مشتقة وليست تحذيرات رسمية. احتفظ بـ meta.attribution عند عرض البيانات (بيانات MET Norway بترخيص CC BY 4.0).

GET/v1/weather/history

سجل ipto.to اليومي الخاص بالأماكن التي سبق الاستعلام عنها: أعلى قيمة عظمى وأدنى قيمة صغرى وأكبر كمية هطول ظهرت في لقطات التنبؤ لذلك اليوم. لا توجد بيانات إلا للأماكن التي سبق طلبها، وتتراكم مع الوقت.

Parameter	In	Description
`q / lat+lon / ip`	query	الموقع: q (مدينة أو رمز بريدي أو "lat,lon")، أو lat وlon، أو ip. واحد من الثلاثة مطلوب.
`days`	query	عدد الأيام الأخيرة المطلوب إرجاعها، من 1 إلى 400. الافتراضي 30.

curl "https://ipto.to/v1/weather/history?q=Tokyo&days=7"
# {"query":"Tokyo","place":{"name":"Tokyo","cc":"JP", ...},
#  "days":[{"date":"2026-10-06","tmax_c":24.1,"tmin_c":17.8,"precip_mm":1.2,"condition_code":296,"source":"metno","snapshots":4}, ...],
#  "note":"Daily envelope of day-0 forecast snapshots (highest high, lowest low, largest precipitation seen), not station observations."}

هذه لقطات تنبؤ وليست مشاهدات محطات ولا إعادة تحليل، فلا تستخدمها كسجل مرصود. تعني 404 أنه لم تُسجَّل أي لقطات لهذا المكان بعد.

GET/v1/weather/radar/frames

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

curl https://ipto.to/v1/weather/radar/frames
# {"frames":[{"time":1791316200,"id":"fdc753dba723"},{"time":1791316800,"id":"2314000028f2"}, ...]}

GET/v1/weather/radar/:frame/:z/:x/:y.png

بلاطة خريطة رادار (PNG) لإطار واحد عند موضع z/x/y قياسي لخرائط الويب. تُقدَّم من المصدر نفسه ليتمكن التطبيق من تحميلها دون طلب إلى طرف ثالث.

Parameter	In	Description
`frame`	path	معرّف الإطار من /v1/weather/radar/frames (سداسي عشري بأحرف صغيرة).
`z`	path	مستوى التكبير.
`x`	path	عمود البلاطة.
`y`	path	صف البلاطة.

# 1. pick the latest frame id
FRAME=$(curl -s https://ipto.to/v1/weather/radar/frames | python3 -c "import sys,json;print(json.load(sys.stdin)['frames'][-1]['id'])")

# 2. fetch a tile (image/png)
curl -o radar.png "https://ipto.to/v1/weather/radar/$FRAME/5/6/12.png"

GET/v1/weather/satellite/:z/:x/:y.png

بلاطة خريطة صور أقمار صناعية عند موضع z/x/y قياسي لخرائط الويب، تُقدَّم من المصدر نفسه.

Parameter	In	Description
`z`	path	مستوى التكبير.
`x`	path	عمود البلاطة.
`y`	path	صف البلاطة.

curl -o satellite.jpg "https://ipto.to/v1/weather/satellite/5/6/12.png"
# the response body is the tile image (served as image/jpeg despite the .png path)

GET/v1/openapi/email.json

عقد OpenAPI 3.1 قابل للقراءة آلياً لـ /v1/email/:email، كُتب ليتمكن وكلاء LLM وMCP من استدعاء نقطة نهاية البريد الإلكتروني دون قراءة هذا التوثيق.

curl https://ipto.to/v1/openapi/email.json
# {"openapi":"3.1.0","info":{...},"servers":[{"url":"https://ipto.to"}],"paths":{"/v1/email/{email}":{...}}}

مرجع حقول البحث عن IP

Field	Type	Description
`ip`	string	عنوان IP المستعلم عنه.
`version`	string	"v4" أو "v6".
`bogon`	boolean	true إذا كان هذا عنواناً خاصاً أو محجوزاً أو غير قابل للتوجيه.
`bogon_type`	string\|null	رمز السبب إذا كان bogon: "loopback"، "private"، "link-local"، "multicast"، "reserved"، "documentation"، "unspecified".
`asn`	integer\|null	رقم النظام المستقل الذي يُعلن عن عنوان IP هذا.
`asn_name`	string\|null	الاسم المختصر لـ ASN (مثال: "GOOGLE").
`asn_org`	string\|null	المؤسسة المسجلة لدى ASN (مثال: "Google LLC").
`asn_type`	string\|null	فئة ASN: "hosting"، "isp"، "business"، "education"، "government"، "mobile"، "residential".
`continent`	string\|null	اسم القارة الكامل (مثال: "North America").
`continent_code`	string\|null	رمز القارة من حرفين: AF AS EU NA SA OC AN.
`country_code`	string\|null	رمز دولة ISO 3166-1 alpha-2 (مثال: "US") للدولة التي يقع فيها عنوان IP، من بيانات تحديد الموقع الجغرافي نفسها المستخدمة للمدينة وخطوط الطول والعرض. وعند عدم وجود تطابق في تحديد الموقع تُستخدم دولة تسجيل ASN (asn_country_code)، وتُشتق منها أيضاً اسم الدولة والعلم والعملة وغيرها.
`country_name`	string\|null	اسم الدولة الكامل بالإنجليزية (مثال: "United States").
`country_flag`	string\|null	رمز علم الدولة التعبيري (مثال: "🇺🇸").
`is_eu`	boolean	true إذا كانت الدولة عضواً في الاتحاد الأوروبي (27 عضواً).
`city`	string\|null	اسم المدينة. يُملأ عند البحث الذاتي، وعند عمليات البحث الصريحة حيث يوجد تطابق في أحد مصدري البيانات الجغرافية المدمجين (IP2Location أو MaxMind) — راجع geo_precision.
`state`	string\|null	المنطقة/التقسيم الإداري. نفس توفر city.
`postal_code`	string\|null	الرمز البريدي. يُملأ عند البحث الذاتي، وعند عمليات البحث الصريحة حيث يوجد تطابق في IP2Location (مفضل) أو MaxMind — نفس توفر city.
`latitude`	number\|null	خط العرض العشري. نفس توفر city.
`longitude`	number\|null	خط الطول العشري. نفس توفر city.
`timezone`	string\|null	المنطقة الزمنية — نفس توفر city. معرّف IANA (مثال: "America/New_York") عند البحث الذاتي. في عمليات البحث الصريحة تعتمد الصيغة على المصدر المطابق: سلسلة إزاحة UTC مثل "-08:00" من IP2Location، أو اسم IANA من MaxMind.
`geo_precision`	string	مدى دقة بيانات الموقع: "city"، أو "country" (لم يجد البحث على مستوى المدينة تطابقاً)، أو "none".
`geo_country_code`	string\|null	الدولة التي يقع فيها عنوان IP وفق بيانات تحديد الموقع الجغرافي (ISO 3166-1 alpha-2). تساوي country_code متى كانت محددة. تكون null عند عدم وجود تطابق في تحديد الموقع.
`asn_country_code`	string\|null	دولة تسجيل مالك ASN (ISO 3166-1 alpha-2). قد تختلف عن country_code في شبكات CDN أو VPN أو الاستضافة أو anycast التي يُعلن عنها من دولة غير التي سُجّل فيها المالك. تكون null عندما لا يكون لعنوان IP إدخال ASN.
`currency_code`	string\|null	رمز عملة ISO 4217 للدولة (مثال: "USD").
`exchange_rate_usd`	number\|null	وحدات العملة المحلية مقابل دولار أمريكي واحد، من تغذية سعر صرف مرجعي تُزامن يومياً وتغطي 154 عملة. تكون null للعملات خارج تلك المجموعة.
`calling_code`	string\|null	رمز الاتصال الدولي للدولة متضمناً بادئة + (مثال: "+1").
`languages`	string[]	اللغات الرسمية/المعترف بها للدولة، بالإنجليزية.
`tld`	string[]	نطاق (نطاقات) المستوى الأعلى الخاص بالدولة، مثال: [".us"].
`capital`	string\|null	اسم العاصمة.
`borders`	string[]	رموز ISO alpha-2 للدول المجاورة.
`is_datacenter`	boolean	true إذا كان عنوان IP يعود لمزود استضافة أو سحابة.
`is_mobile`	boolean	true إذا كان عنوان IP مسجلاً لدى مشغل شبكة جوالة.
`is_residential`	boolean	true إذا كان عنوان IP مصنفاً كنطاق سكني عريض النطاق.
`connection_type`	string	"mobile" أو "datacenter" أو "unknown" — مشتق من نفس تصنيف is_mobile/is_datacenter. لا يحاول عمداً التمييز بين سكني ومؤسسي: فذلك لا يمكن اشتقاقه بشكل موثوق من نص اسم مؤسسة ASN وحده، لذا يبقى أي ASN لا يُصنف بثقة كجوال أو مركز بيانات "unknown" بدلاً من التخمين.
`is_bot`	boolean	true إذا كان عنوان IP مرتبطاً ببنية تحتية معروفة للبوتات.
`is_proxy`	boolean	true إذا كان عنوان IP نقطة خروج بروكسي معروفة.
`is_vpn`	boolean	true إذا كان عنوان IP ضمن نطاق خادم VPN معروف من تغذية التهديدات.
`is_tor`	boolean	true إذا كان عنوان IP عقدة خروج Tor مؤكدة.
`is_abuser`	boolean	true إذا كان عنوان IP ضمن نطاق شبكة مُعلَّم من عدة تغذيات استخبارات إساءة استخدام.
`abuse_score`	integer\|null	درجة خطورة من 1-10 عندما تكون is_abuser بقيمة true، من توافق عدة تغذيات. تكون null خلاف ذلك.
`risk_tier`	string\|null	"critical" (8-10)، أو "high" (5-7)، أو "medium" (3-4) — مشتقة من abuse_score. تكون null إذا لم تُعلَّم.
`threat_type`	string\|null	الفئة الأكثر قابلية للتصرف بين المتطابقات عند تداخل is_tor/is_vpn/is_abuser: "tor_exit" > "abuser" > "vpn". تكون null إذا لم يتطابق أي منها.
`flags`	object	كائن متوافق مع الإصدارات السابقة يعكس حقول is_*. المفاتيح: hosting، mobile، residential، bot، blacklisted، vpn، tor، abuser.
`meta.data_version`	string	تاريخ مجموعة البيانات المستخدمة في البحث (YYYY-MM-DD). "cf-edge" للبحث الذاتي. "bogon" للنطاقات الخاصة.
`meta.cached`	boolean	true إذا كانت الاستجابة قد قُدمت من طبقة التخزين المؤقت.
`meta.lang`	string	اللغة المستخدمة فعليًا في هذه الاستجابة — تطابق ?lang= عند تمريرها، أو القيمة المُستنتَجة من Accept-Language، أو "en".
`meta.lang_source`	"param"\|"header"\|"default"	كيف تم تحديد lang: "param" (تم تمرير ?lang=)، أو "header" (تم الاستنتاج من Accept-Language)، أو "default" (لم يكن أي منهما موجودًا).

صيغ الإخراج

تدعم جميع عمليات البحث عن IP وASN والدولة ?format=.

Format	Content-Type	Usage
`json`	`application/json`	الافتراضي. استجابة منظمة كاملة.
`csv`	`text/csv`	أزواج مفتاح,قيمة مسطحة. تُحذف الكائنات المتداخلة.
`text`	`text/plain`	أسطر بصيغة key: value. حقل واحد لكل سطر.
`xml`	`application/xml`	بنية متداخلة كاملة، تتكرر المصفوفات بنفس الوسم.
`yaml`	`application/x-yaml`	بنية متداخلة كاملة.

curl "https://ipto.to/v1/ip/8.8.8.8?format=csv"
curl "https://ipto.to/v1/ip/8.8.8.8?format=xml"
curl "https://ipto.to/v1/ip/8.8.8.8?format=yaml"
curl "https://ipto.to/v1/ip/8.8.8.8?fields=ip,country_code,is_vpn,is_tor"

التوطين

مرّر ?lang= على /v1/ip، أو /v1/asn/:asn، أو /v1/country/:code لتوطين country_name وcontinent. يبقى كل شيء آخر (أسماء مؤسسات ASN، وأسماء المدن، ورموز العملات) بصيغته الأصلية — فهذه معرّفات وأسماء علم، وليست نص واجهة مستخدم. الرموز غير المدعومة تعود إلى الإنجليزية بدلاً من إظهار خطأ.

Code	Language
`en`	English (default)
`pt`	Português
`fr`	Français
`de`	Deutsch
`zh-TW`	繁體中文
`ko`	한국어
`zh-CN`	简体中文
`ja-JP`	日本語
`es-ES`	Español
`ar-SA`	العربية
`hi-IN`	हिन्दी

curl "https://ipto.to/v1/ip/8.8.8.8?lang=de"
# "landesname":"Vereinigte Staaten","kontinent":"Nordamerika","ist_vpn":false, ...
# every key is renamed and every enum value translated -- this is the default for any non-English lang

لا تملك ?lang=؟ أرسل ترويسة Accept-Language بدلاً من ذلك — تقرأ نفس النقاط الطرفية هذه الترويسة أيضًا، لذا فإن curl -H "Accept-Language: es" https://ipto.to/v1/ip/8.8.8.8 وحدها تُوطّن الاستجابة دون الحاجة إلى سلسلة استعلام. يفوز ?lang= الصريح دائمًا عند وجود كليهما. ملاحظة: متغيّر بيئة الصدفة LANG/LC_ALL (مثل LANG=es_ES.UTF-8 curl ...) يضبط فقط لغة curl نفسها — لا يقرأه curl أبدًا ولا يحوّله إلى ترويسة، لذا ليس له أي تأثير على لغة الاستجابة. Accept-Language أو ?lang= هما الطريقتان الوحيدتان اللتان تعملان بالفعل.

curl -H "Accept-Language: es" https://ipto.to/v1/ip/8.8.8.8
# "nombre_país":"Estados Unidos","continente":"Norteamérica" -- full key+value localization, same as ?lang=es

# equivalent, explicit form:
curl "https://ipto.to/v1/ip/8.8.8.8?lang=es"

# does NOT work -- LANG only sets curl's own locale, never a header:
LANG=es_ES.UTF-8 curl https://ipto.to/v1/ip/8.8.8.8

تتضمن كل استجابة من /v1/ip و/v1/asn/:asn و/v1/country/:code الحقلين lang وlang_source (متداخلان داخل meta في /v1/ip؛ وعلى المستوى الأعلى في الاثنين الآخرين)، حتى تعرف دائمًا بالضبط أي لغة تم تطبيقها وكيف تم اختيارها — "param" أو "header" أو "default" — دون الحاجة إلى التخمين من الطلب الذي أرسلته.

curl -s -H "Accept-Language: es" https://ipto.to/v1/ip/8.8.8.8 | python3 -m json.tool
# "meta": { "data_version": "...", "cached": true, "lang": "es-ES", "lang_source": "header" }

أصبح توطين المفاتيح والقيم بالكامل هو السلوك الافتراضي بمجرد ضبط lang بغير الإنجليزية — يعود كل حقل، بما في ذلك المفاتيح المتداخلة flags وmeta، مُعاد تسميته إلى اللغة المستهدفة، وتُترجم أيضًا القيم الثابتة للتعداد (risk_tier، threat_type، connection_type، geo_precision، bogon_type، asn_type). تحتاج الشكل القديم بمفاتيح إنجليزية؟ أضف &localize=0 إلى /v1/ip لإلغاء التفعيل.

curl -s "https://ipto.to/v1/ip/8.8.8.8?lang=de&localize=0" | python3 -m json.tool
# opts back out to the legacy English-keys shape:
# "country_name": "Vereinigte Staaten", "geo_precision": "country", "is_vpn": false,
# "flags": { "hosting": false, "mobile": false, ... },
# "meta": { "lang": "de", "lang_source": "param", ... }

أمثلة برمجية

JavaScript

const res = await fetch("https://ipto.to/v1/ip/8.8.8.8");
const data = await res.json();
console.log(data.country_name, data.asn_org, data.is_vpn);

Python

import requests
r = requests.get("https://ipto.to/v1/ip/8.8.8.8")
print(r.json()["country_name"], r.json()["is_vpn"])

PHP

$data = json_decode(file_get_contents("https://ipto.to/v1/ip/8.8.8.8"), true);
echo $data["country_name"] . " " . $data["asn_org"];

resp, _ := http.Get("https://ipto.to/v1/ip/8.8.8.8")
var data map[string]interface{}
json.NewDecoder(resp.Body).Decode(&data)

حدود الطلبات

تُطبَّق الحدود يومياً (بتوقيت UTC)، وتُحتسب حسب عنوان IP في الخطة المجانية أو حسب المفتاح في خطتي Pro/Enterprise. تجاوز حدك يُعيد HTTP 429 مع رأس Retry-After. لأعباء العمل الإنتاجية، راجع الأسعار.

يُطبَّق على كل نقطة نهاية /v1/*، وخادم /mcp، واختصارات curl ipto.to / curl ipto.to/:ip. الاستثناء الوحيد هو GET /ip — مجرد ترديد لرأس دون أي تكلفة بحث، لذا لا يستهلك من أي ميزانية إطلاقاً.

Tier	Requests / day	Auth
Free	1,000	لا شيء
Pro	100,000	مفتاح API (رأس)
Enterprise	Unlimited	مفتاح API + نقاط نهاية مخصصة

رموز الأخطاء

Status	Meaning
`200`	تم. تتضمن الاستجابة البيانات.
`202`	بيانات التغذية قيد المزامنة. أعد المحاولة خلال 45 ثانية.
`400`	طلب غير صالح. عنوان IP أو ASN أو رمز دولة غير صالح.
`404`	لم يُعثر على ASN أو الدولة في مجموعة البيانات.
`503`	مجموعة البيانات غير متاحة بعد. قد يكون الاستيعاب الأولي قيد التشغيل.