پایگاه API
همه درخواستها به صورت GET به آدرس زیر ارسال میشوند:
GET
https://www.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"
}
فیلدهای پاسخ
| فیلد | نوع | توضیحات |
|---|---|---|
ip | string | آیپی درخواستی |
country.name | string|null | نام کامل کشور به انگلیسی |
country.iso | string|null | کد دو حرفی کشور (ISO 3166-1 alpha-2) |
city | string|null | نام شهر |
location.latitude | float|null | عرض جغرافیایی |
location.longitude | float|null | طول جغرافیایی |
location.timezone | string|null | منطقه زمانی (مانند Asia/Tehran) |
subdivisions | string[] | آرایه استان/ایالتها |
postal | string|null | کد پستی |
asn.number | int|null | شماره ASN (Autonomous System Number) |
asn.organization | string|null | نام سازمان/ISP ثبتکننده ASN |
asn.network | string|null | محدوده CIDR مرتبط با ASN |
network | string|null | محدوده CIDR آیپی (از GeoLite2-City) |
Rate Limiting
| محدودیت | توضیحات |
|---|---|
| ۱۰ درخواست | حداکثر در هر ۶۰ ثانیه به ازای هر آیپی |
| کش هوشمند | درخواستهای تکراری از کش برگردانده میشوند و rate limit مصرف نمیکنند |
| انقضاء کش | هر ۷ روز یکبار کش منقضی میشود |
هدرهای Rate Limit
| هدر | توضیحات |
|---|---|
X-RateLimit-Limit | حداکثر درخواست مجاز در هر پنجره |
X-RateLimit-Remaining | تعداد درخواست باقیمانده |
X-RateLimit-Reset | Unix timestamp پایان پنجره جاری |
Retry-After | در صورت ۴۲۹، ثانیه تا بازیابی |
X-Cache | HIT یا MISS — وضعیت کش |
کدهای وضعیت
200
موفق
اطلاعات آیپی با موفقیت برگردانده شد
400
درخواست نامعتبر
فرمت آیپی اشتباه است (نه IPv4 و نه IPv6)
404
یافت نشد
آیپی در پایگاه داده GeoLite2 وجود ندارد
429
محدودیت درخواست
Rate limit تجاوز شده. هدر Retry-After را بررسی کنید
500
خطای سرور
فایل GeoLite2-City.mmdb روی سرور موجود نیست
مثالهای استفاده
bash — cURL
# آیپی خاص curl -X GET "https://www.apiip.ir.madata.ir/api.php?ip=8.8.8.8" # آیپی خودتان curl -X GET "https://www.apiip.ir.madata.ir/api.php" # با نمایش هدرها curl -i "https://www.apiip.ir.madata.ir/api.php?ip=8.8.8.8"
javascript — Fetch API
async function getIpInfo(ip = '') { const url = `https://www.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://www.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://www.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 را به حداقل برسانید.