مستندات API

راهنمای کامل استفاده از سرویس رایگان موقعیت‌یابی آی‌پی

پایگاه API

همه درخواست‌ها به صورت GET به آدرس زیر ارسال می‌شوند:

GET https://apiip.ir.madata.ir/api.php رایگان

پارامترها

پارامتر نوع اجباری توضیحات
ip string اختیاری آی‌پی مورد نظر (IPv4 یا IPv6). در صورت عدم ارسال، آی‌پی خود شما برگردانده می‌شود.

ساختار پاسخ

پاسخ به صورت JSON با ساختار زیر است:

JSON
{
    "ip": "8.8.8.8",
    "country": {
        "name": "United States",
        "iso":  "US"
    },
    "city": "Mountain View",
    "location": {
        "latitude":  37.4056,
        "longitude": -122.0775,
        "timezone":  "America/Los_Angeles"
    },
    "subdivisions": ["California"],
    "postal": "94043",
    "asn": {
        "number": 15169,
        "organization": "Google LLC",
        "network": "8.8.8.0/24"
    },
    "network": "8.8.8.0/24"
}

فیلدهای پاسخ

فیلدنوعتوضیحات
ipstringآی‌پی درخواستی
country.namestring|nullنام کامل کشور به انگلیسی
country.isostring|nullکد دو حرفی کشور (ISO 3166-1 alpha-2)
citystring|nullنام شهر
location.latitudefloat|nullعرض جغرافیایی
location.longitudefloat|nullطول جغرافیایی
location.timezonestring|nullمنطقه زمانی (مانند Asia/Tehran)
subdivisionsstring[]آرایه استان/ایالت‌ها
postalstring|nullکد پستی
asn.numberint|nullشماره ASN (Autonomous System Number)
asn.organizationstring|nullنام سازمان/ISP ثبت‌کننده ASN
asn.networkstring|nullمحدوده CIDR مرتبط با ASN
networkstring|nullمحدوده CIDR آی‌پی (از GeoLite2-City)

Rate Limiting

محدودیتتوضیحات
۱۰ درخواستحداکثر در هر ۶۰ ثانیه به ازای هر آی‌پی
کش هوشمنددرخواست‌های تکراری از کش برگردانده می‌شوند و rate limit مصرف نمی‌کنند
انقضاء کشهر ۷ روز یکبار کش منقضی می‌شود

هدرهای Rate Limit

هدرتوضیحات
X-RateLimit-Limitحداکثر درخواست مجاز در هر پنجره
X-RateLimit-Remainingتعداد درخواست باقی‌مانده
X-RateLimit-ResetUnix timestamp پایان پنجره جاری
Retry-Afterدر صورت ۴۲۹، ثانیه تا بازیابی
X-CacheHIT یا MISS — وضعیت کش

کدهای وضعیت

200
موفق اطلاعات آی‌پی با موفقیت برگردانده شد
400
درخواست نامعتبر فرمت آی‌پی اشتباه است (نه IPv4 و نه IPv6)
404
یافت نشد آی‌پی در پایگاه داده GeoLite2 وجود ندارد
429
محدودیت درخواست Rate limit تجاوز شده. هدر Retry-After را بررسی کنید
500
خطای سرور فایل GeoLite2-City.mmdb روی سرور موجود نیست

مثال‌های استفاده

bash — cURL
# آی‌پی خاص
curl -X GET "https://apiip.ir.madata.ir/api.php?ip=8.8.8.8"

# آی‌پی خودتان
curl -X GET "https://apiip.ir.madata.ir/api.php"

# با نمایش هدرها
curl -i "https://apiip.ir.madata.ir/api.php?ip=8.8.8.8"
javascript — Fetch API
async function getIpInfo(ip = '') {
    const url = `https://apiip.ir.madata.ir/api.php?ip=${ip}`;
    const res  = await fetch(url);

    if (!res.ok) throw new Error(`HTTP ${res.status}`);

    return res.json();
}

// استفاده
getIpInfo('8.8.8.8').then(data => {
    console.log(data.country.name);   // "United States"
    console.log(data.location.timezone); // "America/Los_Angeles"
}).catch(console.error);
python — requests
import requests

BASE_URL = "https://apiip.ir.madata.ir/api.php"

def get_ip_info(ip=""):
    response = requests.get(BASE_URL, params={"ip": ip})
    response.raise_for_status()
    return response.json()

# استفاده
data = get_ip_info("8.8.8.8")
print(data["country"]["name"])      # United States
print(data["location"]["timezone"])  # America/Los_Angeles
php
$baseUrl = "https://apiip.ir.madata.ir/api.php";

function getIpInfo(string $ip = ''): array
{
    global $baseUrl;
    $url      = $baseUrl . '?ip=' . urlencode($ip);
    $response = file_get_contents($url);
    return json_decode($response, true);
}

// استفاده
$data = getIpInfo('8.8.8.8');
echo $data['country']['name']; // United States

نکات مهم

  • آی‌پی‌های تکراری پس از اولین جستجو در کش SQLite ذخیره می‌شوند
  • درخواست‌های کش‌شده rate limit مصرف نمی‌کنند
  • کش هر ۷ روز منقضی می‌شود
  • هدر X-Cache: HIT نشان‌دهنده پاسخ از کش است
  • برای دریافت آی‌پی خودتان، پارامتر ip را خالی بگذارید یا ارسال نکنید
  • API از CORS پشتیبانی کامل می‌کند — از مرورگر مستقیم فراخوانی کنید
  • پایگاه داده از MaxMind GeoLite2-City + GeoLite2-ASN استفاده می‌کند
  • فیلد asn.number شماره ASN و asn.organization نام ISP/سازمان را نشان می‌دهد
  • برای به‌روزرسانی دیتابیس: php update-db.php
برای استفاده بهینه، IP های پرتکرار را در کش سمت کلاینت خودتان هم ذخیره کنید تا درخواست‌های API را به حداقل برسانید.