مستندات API عمومی ipmyp

این مستندات برای توسعه‌دهندگانی در نظر گرفته شده است که می‌خواهند از ipmyp برای دریافت داده های مرتبط با IP استفاده کنند. داده‌ها در قالب‌ JSON از طریق یک رابط کاربری ساده مبتنی بر URL از طریق HTTP ارائه میشود که به شما امکان می‌دهد از داده‌های ما مستقیماً از مرورگر یا از سرور و محیط CLI استفاده کنید.

اطلاعات کلی

• Base URL:
  https://api.ipmyp.ir
• Content-Type پیش‌فرض پاسخ‌ها:
  application/json
• وضعیت پاسخ (Status):
  • success : درخواست با موفقیت پردازش شده است.
  • fail : خطای منطقی رخ داده است (در برخی موارد با کد HTTP 200).

⚠️ توجه: کد وضعیت HTTP ممکن است در خطاهای منطقی همچنان 200 باشد. خطاهای سطح پروتکل (مانند Rate Limit یا بدنه نامعتبر) با کدهای مناسب HTTP بازگردانده می‌شوند.

ساختار پاسخ موفق

در تمام پاسخ‌های موفق، فیلد status برابر با success است.

{
  "status": "success",
  "continent": "Asia",
  "continentCode": "AS",
  "country": "Iran",
  "countryCode": "IR",
  "region": "07",
  "regionName": "Tehran",
  "city": "Tehran",
  "district": null,
  "zip": "1136953514",
  "lat": 35.6944,
  "lon": 51.4215,
  "timezone": "Asia/Tehran",
  "offset": null,
  "currency": null,
  "isp": "Example ISP",
  "org": "Example ISP",
  "as": "AS12345 Example ISP",
  "asname": "Example ISP",
  "reverse": null,
  "mobile": false,
  "proxy": false,
  "hosting": false,
  "query": "1.2.3.4"
}

ساختار خطا (Logical Error)

در صورت بروز خطای منطقی (مانند IP یا دامنه نامعتبر)، ساختار پاسخ به شکل زیر خواهد بود:

{
  "status": "fail",
  "message": "invalid query",
  "query": "not-an-ip"
}

تشخیص IP واقعی کلاینت

سرویس IP واقعی کاربر را با اولویت زیر استخراج می‌کند. در صورت استفاده از CDN یا Proxy، هدر مناسب را ارسال نمایید:

1. ar-real-ip (هدر اختصاصی ArvanCloud)
2. X-Real-IP
3. X-Forwarded-For (اولین IP معتبر در لیست)
4. آدرس اتصال TCP (Fallback)

Rate Limit و هدرهای کنترلی

پس از هر پاسخ (به‌جز خطاهای سطح شبکه)، هدرهای زیر برای اطلاع از وضعیت سهمیه ارسال می‌شوند:

• در صورت عبور از حد مجاز، پاسخ با HTTP 429 بازگردانده می‌شود.
• برای افزایش یا رفع محدودیت Rate Limit با info@ipmyp.ir تماس بگیرید.

خلاصه مسیرها (Endpoints)

جزئیات مسیرها

1) دریافت IP کلاینت

Endpoint:
GET /

توضیح:
IP تشخیص داده‌شده‌ی کاربر را به‌صورت متن ساده بازمی‌گرداند.

نمونه درخواست:

curl https://api.ipmyp.ir/

curl -L api.ipmyp.ir

پاسخ نمونه:

1.2.3.4

2) دریافت اطلاعات GeoIP

Endpoint:
GET /json/:query?

توضیح:
اطلاعات مکان‌یابی برای IP یا دامنه مشخص‌شده را بازمی‌گرداند. اگر query ارسال نشود، IP کلاینت استفاده می‌شود.

پارامتر مسیر:

• query (اختیاری): IP یا نام دامنه

Query Parameters اختیاری:

• fields : فهرست فیلدهای موردنیاز (جداشده با کاما)
• callback : فعال‌سازی JSONP

نمونه درخواست:

curl "https://api.ipmyp.ir/json/1.2.3.4?fields=status,country,city"

نمونه پاسخ:

{
  "status": "success",
  "country": "Iran",
  "city": "Tehran"
}

نمونه JSONP:

curl "https://api.ipmyp.ir/json/example.com?callback=handleIp"

handleIp({"status":"success","country":"United States","city":"Los Angeles","query":"example.com"});

3) درخواست گروهی (Batch)

Endpoint:
POST /batch

توضیح:
امکان ارسال چندین IP یا دامنه در یک درخواست و دریافت نتایج به‌صورت آرایه.

ساختار بدنه:

• آرایه‌ای از رشته‌ها (IP/دامنه)
• یا آبجکت‌ها به شکل { "query": "example.com" }

Query Parameters اختیاری:

• fields : محدودسازی فیلدهای خروجی هر آیتم

نمونه درخواست:

curl -X POST "https://api.ipmyp.ir/batch?fields=status,query,country,city" \
  -H "Content-Type: application/json" \
  -d '["8.8.8.8", {"query": "example.com"}, "bad"]'

پاسخ نمونه:

[
  {
    "status": "success",
    "country": "United States",
    "city": "Mountain View",
    "query": "8.8.8.8"
  },
  {
    "status": "success",
    "country": "United States",
    "city": "Los Angeles",
    "query": "example.com"
  },
  {
    "status": "fail",
    "message": "invalid query",
    "query": "bad"
  }
]

مثال‌های Curl برای سیستم‌عامل‌های مختلف

⚠️ توجه: نحوه ارسال بدنه JSON در دستور curl بسته به سیستم‌عامل و شِل متفاوت است. مثال‌های زیر را متناسب با محیط اجرای خود استفاده کنید.

Linux / macOS (Bash, Zsh)

curl -X POST "https://api.ipmyp.ir/batch?fields=status,query,country,city" \
  -H "Content-Type: application/json" \
  -d '["8.8.8.8", {"query": "example.com"}, "bad"]'

Windows PowerShell

curl -X POST "https://api.ipmyp.ir/batch?fields=status,query,country,city" `
  -H "Content-Type: application/json" `
  -d "[\"8.8.8.8\", {\"query\": \"example.com\"}, \"bad\"]"

Windows CMD

curl -X POST "https://api.ipmyp.ir/batch?fields=status,query,country,city" -H "Content-Type: application/json" -d "[\"8.8.8.8\", {\"query\": \"example.com\"}, \"bad\"]"

نکات نهایی

• برای کاهش حجم پاسخ و افزایش کارایی، از پارامتر fields استفاده کنید.
• در صورت استفاده از CDN یا Proxy، هدرهای IP را به‌درستی تنظیم نمایید.
• خطاهای 403 نشان‌دهنده عدم تطابق IP یا Origin با وایت‌لیست است.
• در مواجهه با 429، مقدار X-Ttl را بررسی کرده و پس از اتمام بازه مجدداً تلاش کنید.
• برای استفاده‌های پرترافیک، هماهنگی جهت افزایش Rate Limit توصیه می‌شود.

© IPMYP – API Documentation