وثائق الواجهة

أول طلب للواجهة

curl --get 'https://www.geoipy.com/api/IPsInfo' \
  --data-urlencode 'ip=8.8.8.8' \
  --header 'X-API-Key: YOUR_API_KEY'

استخدم HTTPS وX-API-Key. قد تظهر مفاتيح الرابط في السجلات. اختلاف مفتاح الترويسة والرابط يعيد HTTP 400.

أنشئ مفتاحًا من لوحة التحكم. يظهر كاملًا مرة واحدة. احفظه في إعدادات خادم خاصة، وليس في شيفرة المتصفح أو مستودعات عامة. الاستبدال يلغي المفتاح القديم فورًا. الإلغاء أو الانتهاء يمنع الطلبات الجديدة؛ وقد تكتمل المقبولة سابقًا.

الاستجابة وحداثة البيانات

يعيد HTTP 200 بيانات JSON. المثال مختصر وتوضيحي؛ الحقول المتاحة تعتمد على بيانات المزود.

{
  "ip": "8.8.8.8",
  "type": "ipv4",
  "country_code": "US"
}

حداثة التخزين المؤقت افتراضيًا 12 ساعة. تعرض X-Data-Fetched-At وقت الجلب بـUTC. لا تقدم البيانات المنتهية عند فشل التحديث؛ وقت الجلب لا يدل على عمر البيانات.

تحدد X-Request-ID الطلب للدعم. الموقع الجغرافي تقريبي للشبكة، وليس موقع الشخص الدقيق.

الاستخدام وإعادة المحاولة

الطلبات الناجحة، بما فيها المخزنة مؤقتًا، تستهلك الحصة. المعلقة تحجز منها والفاشلة تحررها. يتجدد الاستخدام أول كل شهر عند 00:00 UTC. تغيير الخطة أو المفتاح لا يصفره.

في HTTP 429 أو أخطاء 503/504 المؤقتة اتبع Retry-After وأعد المحاولة بعدد محدود وتأخير متزايد. أصلح المدخلات أو الاعتماد غير الصالح أولًا.

الأخطاء

تعيد الأخطاء application/json وحالة خطأ HTTP. تبقى معرّفات الواجهة والأمثلة بصيغتها الموثقة.

{
  "success": false,
  "error": {
    "code": 104,
    "type": "usage_limit_reached",
    "info": "The monthly API allowance has been reached."
  }
}

أمثلة من جهة الخادم

JavaScript · الخادم

const url = new URL('https://www.geoipy.com/api/IPsInfo');
url.searchParams.set('ip', '8.8.8.8');
const response = await fetch(url, {
  headers: { 'X-API-Key': process.env.GEOIPY_API_KEY }
});
const data = await response.json();
if (!response.ok) throw new Error(data.error.info);
console.log(data);

C#

using (var client = new System.Net.Http.HttpClient())
{
    client.DefaultRequestHeaders.Add("X-API-Key",
        System.Environment.GetEnvironmentVariable("GEOIPY_API_KEY"));
    var response = await client.GetAsync(
        "https://www.geoipy.com/api/IPsInfo?ip=8.8.8.8");
    var json = await response.Content.ReadAsStringAsync();
    // Inspect response.StatusCode and parse json before retrying.
}

Python

import os, requests
response = requests.get(
    'https://www.geoipy.com/api/IPsInfo',
    params={'ip': '8.8.8.8'},
    headers={'X-API-Key': os.environ['GEOIPY_API_KEY']},
    timeout=15)
data = response.json()
response.raise_for_status()

PHP

$url = 'https://www.geoipy.com/api/IPsInfo?' . http_build_query(['ip' => '8.8.8.8']);
$ch = curl_init($url);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('GEOIPY_API_KEY')]]);
$json = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($json === false) { throw new RuntimeException('The request failed.'); }
curl_close($ch);
$data = json_decode($json, true);
// Inspect $status and $data['error'] when the status is not 200.