مستندات API موقعیت‌یابی IP

API رایگان JSON برای موقعیت‌یابی IP، ASN و داده‌های ریسک. IPv4 و IPv6، HTTPS، با پشتیبانی از CORS.

شروع سریع

برای امتحان نیازی به ثبت‌نام نیست. نقطه پایانی زیر را بدون کلید فراخوانی کنید تا داده‌های IP خودتان را دریافت کنید (محدود به 100 درخواست در روز).

curl https://iplookinfo.com/json

احراز هویت

یک کلید API رایگان در داشبورد بسازید و آن را در هدر Authorization ارسال کنید. پارامتر token در کوئری هم برای تست سریع کار می‌کند، اما در محیط عملیاتی از آن پرهیز کنید چون URLها در لاگ‌ها ثبت می‌شوند.

Authorization: Bearer ipl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

نقاط پایانی

GET/api/v1/{ip}: جستجوی هر آدرس IPv4 یا IPv6.
GET/api/v1/me: جستجوی IP خود فراخواننده. در /json نیز در دسترس است.
POST/api/v1/batch: جستجوی حداکثر ۱۰٬۰۰۰ IP در یک درخواست (طرح‌های پولی). هر IP یک درخواست محسوب می‌شود.

پارامترهای کوئری

lang — زبان نام مکان‌ها: en، zh، es، pt، ru، ja. پیش‌فرض en.

پاسخ

شیء risk فقط در طرح‌های Pro و Business گنجانده می‌شود.

{
  "ip": "8.8.8.8",
  "version": "IPv4",
  "type": "unicast",
  "bogon": false,
  "network": "8.8.8.0/24",
  "continent": { "code": "NA", "name": "North America" },
  "country": { "code": "US", "name": "United States", "is_eu": false },
  "region": null,
  "city": null,
  "postal": null,
  "location": { "latitude": 37.751, "longitude": -97.822, "accuracy_radius_km": 1000, "time_zone": "America/Chicago" },
  "asn": { "asn": 15169, "name": "Google LLC", "domain": "google.com", "route": "8.8.8.0/24" },
  "isp": { "name": "Google", "organization": "Google", "is_mobile": false, "mobile_country_code": null, "mobile_network_code": null },
  "risk": { "score": 60, "is_tor": false, "is_vpn": false, "is_datacenter": true, "provider": "Google Cloud" }
}

محدودیت نرخ و خطاها

هر پاسخ شامل هدرهای X-RateLimit-Limit، X-RateLimit-Remaining و X-RateLimit-Reset است. سهمیه‌ها در ساعت 00:00 UTC بازنشانی می‌شوند.

خطاها ساختار JSON یکسانی همراه با کد وضعیت HTTP دارند:

HTTP/1.1 429 Too Many Requests

{ "error": { "code": "quota_exceeded", "message": "..." } }

400 invalid_ip / bad_request
401 invalid_key
403 plan_required
413 too_many
429 rate_limited / quota_exceeded

مازاد

طرح‌های پولی می‌توانند در داشبورد مازاد را فعال کنند. در این صورت درخواست‌های بیش از سهمیه روزانه پاسخ داده می‌شوند و به ازای هر ۱٬۰۰۰ درخواست محاسبه می‌شوند، تا سقف هزینه ماهانه‌ای که خودتان تعیین می‌کنید. این پاسخ‌ها هدر X-Overage-Units دارند.

نمونه کدها

cURL

curl -H "Authorization: Bearer $IPLOOKINFO_KEY" https://iplookinfo.com/api/v1/8.8.8.8

# Batch (paid plans)
curl -X POST -H "Authorization: Bearer $IPLOOKINFO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips":["8.8.8.8","1.1.1.1"]}' https://iplookinfo.com/api/v1/batch

JavaScript

const res = await fetch("https://iplookinfo.com/api/v1/8.8.8.8", {
  headers: { Authorization: `Bearer ${process.env.IPLOOKINFO_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();
console.log(data.country?.code, data.city);

Python

import os, requests

r = requests.get(
    "https://iplookinfo.com/api/v1/8.8.8.8",
    headers={"Authorization": f"Bearer {os.environ['IPLOOKINFO_KEY']}"},
    timeout=5,
)
r.raise_for_status()
data = r.json()
print(data["country"]["code"], data["asn"]["name"])

PHP

$ctx = stream_context_create(["http" => [
    "header" => "Authorization: Bearer " . getenv("IPLOOKINFO_KEY"),
]]);
$data = json_decode(file_get_contents("https://iplookinfo.com/api/v1/8.8.8.8", false, $ctx), true);
echo $data["country"]["code"];

Go

req, _ := http.NewRequest("GET", "https://iplookinfo.com/api/v1/8.8.8.8", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("IPLOOKINFO_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()
var data map[string]any
json.NewDecoder(resp.Body).Decode(&data)