وثائق المطور

جميع endpoints وحقول الاستجابة ورموز الخطأ وحدود المعدل — بالإضافة إلى أمثلة كود في 5 لغات.

بدء سريع

من الحساب إلى أول lookup في 60 ثانية.

1سجل مجاناً — بدون بطاقة ائتمان، يصل بريد التأكيد فوراً.
2بعد تسجيل الدخول، أنشئ مفتاح API في البوابة (نقرة واحدة).
3ضع المفتاح في X-API-Key header وأطلق أول lookup.

user@geoips:~$cat quickstart.sh

curl -H "X-API-Key: $KEY" https://api.geoips.info/v1/lookup/8.8.8.8

نصيحة

احفظ المفتاح كمتغير بيئة (export KEY=gi_...) — لا تحفر بشكل صلب في الـ repo!

المصادقة

كل endpoint lookup يتطلب مفتاح API في X-API-Key header. الـ endpoint المجهول /v1/public/lookup/:ip هو الاستثناء الوحيد.

تنسيق المفتاح

تتبع مفاتيح API تنسيق gi_<8-hex>_<48-base62>. مثال: gi_f3908360_TQWxoyfbY0nCVeCP83mV1oMjXwmyC51t. البلوك الأول (gi_<8-hex>) هو البادئة العامة (نستخدمه داخلياً للسجلات دون تخزين الجزء السري).

تدوير المفتاح

أنشئ مفتاحاً جديداً، انشره، ألغ القديم — كل ذلك في البوابة. المفاتيح الملغاة يتم حظرها فوراً (لا فترة سماح).

نصائح أمنية

لا تستخدم أبداً في JS متصفح أو تطبيقات عميل — المفتاح يصبح قابلاً للقراءة علناً.
لحالات الاستخدام الأمامية: قم بـ proxy لاستدعاءات API عبر backend الخاص بك، الذي يحتفظ بالمفتاح.
مفتاح واحد لكل بيئة (dev/staging/prod) — في حالة التسرب يتأثر واحد فقط.

حدود المعدل والحصص

لكل خطة حدّان: في الدقيقة (حماية burst) واليوم (حماية الحجم). كلاهما يحسب بشكل منفصل.

الحد لكل دقيقة

نافذة منزلقة: تحسب آخر 60 ثانية. Free 120/دقيقة، Starter 600/دقيقة، Business 3,000/دقيقة، Enterprise 10,000/دقيقة.

الحد اليومي

نافذة ثابتة مع UTC reset قابل للتكوين (افتراضي 00:00 UTC). Free 8,000/يوم، Starter 100,000/يوم، Business 1M/يوم، Enterprise غير محدود.

Batch يحسب N IP

POST /v1/lookup/batch بـ 50 IP يستهلك 50 من حصتك اليومية (لكن طلب HTTP واحد فقط لفحص حد الدقيقة). plan cap لـ IP لكل batch: Free 10، Starter 50، Business 100، Enterprise 100.

Headers الاستجابة

في 429 نضع Retry-After (ثواني حتى reset) و X-RateLimit-Remaining. ابن حلقة retry على ذلك — وليس على sleep ثابت.

Endpoints Whois تحسب حسب وضع الإعدادات: إما مقابل الحد اليومي، أو مقابل pot Whois مخصص (whois_limit_per_day لكل خطة).

GET/v1/lookup/{ip}X-API-Key مطلوب

Lookup فردي

احصل على بيانات geo لـ IPv4 أو IPv6 محدد. اختياريًا، يطلق هذا الاستدعاء pre-cache لـ Whois في الخلفية، حتى أن استدعاء /whois التالي يرد فوراً.

المعلمات

ip	عنوان IP (IPv4 منقط أو notation قياسي لـ IPv6). مثال: 8.8.8.8 أو 2606:4700:4700::1111.

أمثلة كود

user@geoips:~$cat example.sh

curl -H "X-API-Key: $KEY" https://api.geoips.info/v1/lookup/8.8.8.8

الاستجابة (200 OK)

user@geoips:~$cat response.json

{
  "ip": "8.8.8.8",
  "ip_version": 4,
  "country_code": "US",
  "country_name": "United States of America",
  "flag": "🇺🇸",
  "flag_url": "https://geoips.info/flags/us.svg",
  "region": "California",
  "city": "Mountain View",
  "latitude": 37.40599,
  "longitude": -122.07852,
  "zip": "94043",
  "timezone": "-08:00",
  "asn": 15169,
  "as": "Google LLC",
  "cidr": "8.8.8.0/24"
}

GET/v1/lookup/selfX-API-Key مطلوب

IP الخاص بك

متغير الراحة: يأخذ IP العميل للمضيف المتصل. مفيد لـ cron jobs التي تريد تسجيل IP egress الخاص بها.

أمثلة كود

user@geoips:~$cat example.sh

curl -H "X-API-Key: $KEY" https://api.geoips.info/v1/lookup/self

الاستجابة (200 OK)

user@geoips:~$cat response.json

{
  "ip": "8.8.8.8",
  "ip_version": 4,
  "country_code": "US",
  "country_name": "United States of America",
  "flag": "🇺🇸",
  "flag_url": "https://geoips.info/flags/us.svg",
  "region": "California",
  "city": "Mountain View",
  "latitude": 37.40599,
  "longitude": -122.07852,
  "zip": "94043",
  "timezone": "-08:00",
  "asn": 15169,
  "as": "Google LLC",
  "cidr": "8.8.8.0/24"
}

POST/v1/lookup/batchX-API-Key مطلوب

Lookup مجمع

حتى 100 IP في طلب واحد. تسلم الاستجابة results[] بنفس النمط مثل endpoint الفردي. كل IP يستهلك 1 من الحصة اليومية.

Body الطلب

JSON مع مصفوفة ips. الحد الأدنى 1، الحد الأقصى 100 إدخالات. كل واحد هو IPv4 أو IPv6 صالح.

user@geoips:~$cat request.json

{ "ips": ["1.1.1.1", "2606:4700:4700::1111"] }

أمثلة كود

user@geoips:~$cat example.sh

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"ips":["1.1.1.1","2606:4700:4700::1111"]}' \
  https://api.geoips.info/v1/lookup/batch

الاستجابة (200 OK)

user@geoips:~$cat response.json

{
  "results": [
    { "ip": "1.1.1.1", "country_code": "US", "flag": "🇺🇸", "flag_url": "https://geoips.info/flags/us.svg", "asn": 13335, "as": "Cloudflare, Inc.", "...": "..." },
    { "ip": "2606:4700:4700::1111", "ip_version": 6, "country_code": "US", "flag": "🇺🇸", "...": "..." }
  ]
}

cap لـ body الطلب: 64 KB. عند التجاوز: HTTP 413 مع error_code: body_too_large.

GET/v1/lookup/{ip}/whoisX-API-Key مطلوب

Whois / RDAP

بلوك CIDR و netname و منظمة و contact abuse مباشرة من 5 RIRs (RIPE/ARIN/APNIC/LACNIC/AFRINIC). Cached لمدة 30 يوماً — أول lookup لـ IP جديد يطلق RDAP sync (~200 ms)، الاستعلامات اللاحقة sub-millisecond.

أمثلة كود

user@geoips:~$cat example.sh

curl -H "X-API-Key: $KEY" https://api.geoips.info/v1/lookup/8.8.8.8/whois

الاستجابة (200 OK)

user@geoips:~$cat response.json

{
  "ip": "8.8.8.8",
  "cached": true,
  "whois": {
    "cidr": "8.8.8.0/24",
    "netname": "GOOGLE",
    "country": "US",
    "flag": "🇺🇸",
    "flag_url": "https://geoips.info/flags/us.svg",
    "org_name": "Google LLC",
    "abuse_email": "network-abuse@google.com",
    "source": "arin",
    "fetched_at": "2026-05-27T10:00:00Z"
  }
}

Plan gating: حسب إعدادات admin إما مضمن في كل خطة، أو من Starter فما فوق، أو مع pot يومي خاص به لكل خطة.

202 Accepted (cache miss + async)

عندما يفقد الـ cache ولم يقم background worker بمزامنة الإدخال بعد، نرد بـ HTTP 202 و Retry-After header (~5 ث) و whois: null. ببساطة أعد المحاولة بعد Retry-After.

GET/v1/healthمجهول (بدون مفتاح)

فحص الصحة

يرجع { status: "ok", version: "..." }. endpoint مجهول، مثالي لـ uptime monitoring (مثل UptimeRobot، Pingdom).

أمثلة كود

user@geoips:~$cat example.sh

curl https://api.geoips.info/v1/health

الاستجابة (200 OK)

user@geoips:~$cat response.json

{ "status": "ok", "version": "1.2.3" }

GET/v1/public/lookup/{ip}مجهول (بدون مفتاح)

مجهول (عام)

Endpoint خلف صفحة /check. يجمع geo+whois في استجابة واحدة، لا يتطلب مفتاحاً. حد IP rate صارم (10/ساعة لكل IP طالب) — لتطبيقات الحجم المناسبة يرجى استخدام مفتاح.

أمثلة كود

user@geoips:~$cat example.sh

curl https://api.geoips.info/v1/public/lookup/8.8.8.8

الاستجابة (200 OK)

user@geoips:~$cat response.json

{
  "ip": "8.8.8.8",
  "geo":   { "country_code": "US", "flag": "🇺🇸", "flag_url": "https://geoips.info/flags/us.svg", "city": "Mountain View", "...": "..." },
  "whois": { "cidr": "8.8.8.0/24", "org_name": "Google LLC", "abuse_email": "network-abuse@google.com", "...": "..." }
}

/v1/public/lookup/self له حد منفصل أكثر مرونة (60/ساعة لكل IP) بحيث لا تستنزف إعادة تحميل صفحة الهبوط الـ pot الرئيسي.

حقول الاستجابة بالتفصيل

جميع الحقول التي يمكن أن يرجعها lookup. Nullable يعني: الحقل مفقود تماماً من JSON إذا لم تتوفر بيانات (كل الحقول هي omitempty).

حقول GeoIP

حقل	النوع	Nullable	الوصف
ip	string	always	Die abgefragte IP, normalisiert.
ip_version	int	always	4 oder 6.
country_code	string	nullable	ISO 3166-1 alpha-2 uppercase ("US", "DE").
country_name	string	nullable	Vollstaendiger Englischer Laendername.
flag	string	nullable	Country-Flag-Emoji (z.B. 🇩🇪) — abgeleitet aus country_code.
flag_url	string	nullable	Absolute URL zur SVG-Flagge (z.B. https://geoips.info/flags/de.svg).
region	string	nullable	Region/Bundesland (z.B. "California").
city	string	nullable	Stadt.
latitude	float	nullable	WGS84.
longitude	float	nullable	WGS84.
zip	string	nullable	Postleitzahl (Format land-abhaengig).
timezone	string	nullable	UTC-Offset oder TZ-Name (z.B. "-08:00").
asn	int	nullable	Autonomous System Number.
as	string	nullable	AS-Name (z.B. "Google LLC").
cidr	string	nullable	CIDR-Block der IP (z.B. "8.8.8.0/24").

حقول Whois

حقل	النوع	Nullable	الوصف
cidr	string	always	RDAP-Inetnum als CIDR.
netname	string	nullable	Netzwerk-Bezeichnung beim RIR.
country	string	nullable	RIR-registriertes Land (kann von GeoIP-country_code abweichen).
flag	string	nullable	Country-Flag-Emoji aus country.
flag_url	string	nullable	Absolute URL zur SVG-Flagge.
org_name	string	nullable	Organisations-Name (Betreiber).
abuse_email	string	nullable	Abuse-Kontakt-Email.
asn	int	nullable	ASN — aus dem RDAP-Response wo verfuegbar.
as_name	string	nullable	AS-Name.
source	string	always	Welches RIR — "ripe"/"arin"/"apnic"/"lacnic"/"afrinic".
fetched_at	datetime	always	ISO-8601-Zeitstempel des letzten RDAP-Fetch.

أصول أعلام الدول

كل استجابة مع country_code تحتوي بالإضافة على flag (إيموجي) و flag_url (SVG مستضاف). مجاني للاستخدام في الـ UI الخاص بك.

نمط URL

أحرف صغيرة ISO 3166-1 alpha-2. 271 دولة متاحة. cache header يوم واحد.

user@geoips:~$cat flag-urls.txt

https://geoips.info/flags/<iso-lowercase>.svg

# Beispiele:
https://geoips.info/flags/de.svg
https://geoips.info/flags/us.svg
https://geoips.info/flags/jp.svg

CORS

تُقدم SVGs مع Access-Control-Allow-Origin: * — embed مباشر cross-origin يعمل.

Live-Preview

رموز الخطأ

جميع الأخطاء ترجع body JSON مع error (قابل للقراءة من قبل الإنسان)، error_code (قابل للقراءة من قبل الآلة)، وحسب الرمز حقول إضافية. قيمة code مستقرة — يمكن كتابة if/else ضدها.

HTTP	error_code	المعنى	كيف نتفاعل؟
400	invalid_ip	IP-Adresse konnte nicht geparst werden.	Vor dem Call lokal validieren (`net.ParseIP`, `ipaddress` etc.).
400	private_ip	IP ist in einer privaten/reservierten Range (10.x, 192.168.x, fc00::/7, ...).	Diese IPs sind nicht route-bar — vorher filtern.
400	invalid_body	Batch-Request-Body ist kein gueltiges JSON oder schema-falsch.	Schema pruefen: `{ "ips": ["...", "..."] }`, 1-100 Eintraege.
400	batch_too_large	Batch enthaelt mehr IPs als dein Plan erlaubt.	In kleinere Batches splitten oder Plan upgraden.
401	missing_api_key	Header `X-API-Key` fehlt.	Header setzen. Auch case-insensitive zulaessig.
401	invalid_api_key	Key existiert nicht oder ist widerrufen.	Im Portal pruefen ob Key noch aktiv ist.
403	whois_plan_required	Dein Plan beinhaltet keinen Whois-Zugriff (gating_mode=starter_plus + Free-Plan).	Upgrade auf Starter oder hoeher.
413	body_too_large	Request-Body groesser als 64 KB.	Batch splitten (100 IPv6-Adressen passen problemlos in 64 KB).
429	rate_limit_per_minute	Per-Minute-Quote erschoepft.	`Retry-After` Header respektieren, dann erneut.
429	rate_limit_per_day	Tageskontingent erschoepft.	`Retry-After` zeigt Sekunden bis UTC-Reset, oder Plan upgraden.
429	whois_quota_exhausted	Whois-Tagestopf erschoepft (nur bei gating_mode=per_plan_limit).	Bis UTC-Reset warten oder Plan-Whois-Limit erhoehen.
429	rate_limit_public	Anon-Endpoint /v1/public/lookup: pro Requester-IP > 10/h.	Mit API-Key auf /v1/lookup wechseln (10 000x hoeheres Limit).
202	pending	Whois noch nicht im Cache, async-Fetch laeuft.	Nach `Retry-After` Sekunden (~5 s) erneut anfragen.
503	maintenance_mode	Plattform im Wartungsmodus.	`Retry-After` respektieren, der Header sagt wann wieder verfuegbar.
503	whois_disabled	Whois-Feature global deaktiviert (Admin-Setting).	Nur Geo-Endpoints verwenden bis das Feature wieder aktiv ist.
500	internal_error	Unerwarteter Server-Fehler.	Mit exponential backoff retry; falls persistent: Support kontaktieren mit Request-ID.

أفضل الممارسات

توصيات من ممارسة الإنتاج. اتبع = القليل من المتاعب؛ تجاهل = على الأرجح حادثة ما في مرحلة ما.

Retry مع backoff أسي

في 429 (rate limit)، 502/503 أو أخطاء شبكة: لا تطرق، أعد المحاولة بتأخير متزايد. القاعدة: 1 ث، 2 ث، 4 ث، 8 ث — ثم أوقف. في 429 احترم دائماً Retry-After header (ثواني حتى reset)؛ إذا كان header مفقوداً، ينطبق backoff الافتراضي.

لا retries على 4xx (باستثناء 429) — هي دائمة (invalid_ip، missing_api_key الخ) و retry فقط يحرق الحصة.

Cache lookups الخاصة بك

بيانات GeoIP نادراً ما تتغير (IP يغير الدولة مرة كل بضع سنوات، المدينة تقريباً أبداً). cache محلي معقول: TTL 24 ساعة، LRU eviction. يوفر الحصة بشكل كبير. نحن نخزن بيانات Whois داخلياً بالفعل لمدة 30 يوماً — لا حاجة لـ cache مرة أخرى.

Cache key: الـ IP نفسه. لـ IPv6 قم بالتطبيع أولاً (lowercase، بدون أصفار بادئة) وإلا cache miss في كل متغير كتابة.

نمط التعامل مع الأخطاء

تحقق دائماً من حالة HTTP أولاً، ثم error_code. القاعدة: 4xx = خطأك (إدخال غير صحيح)؛ 429 = rate limit، retry مع backoff؛ 5xx = خطؤنا، retry مع backoff؛ 200 = OK، استمر في الكود.

سجل 5xx + 429 مع قيمة Retry-After + error_code — هذا يساعدنا بشكل كبير عند الاتصال بالدعم.

Batch بدلاً من N lookups فردية

إذا كان لديك أكثر من 5 IP للتحقق: استخدم POST /v1/lookup/batch بدلاً من N GETs متوازية. يوفر roundtrips، يستهلك الحصة اليومية بنفس القدر، أسرع بكثير (طلب واحد بدلاً من N).

لـ >100 IP: قسم إلى chunks (cap per batch = 100). أرسل بالتتابع أو مع concurrency limit صغير (3-5 batches متوازية كافية) — وإلا ستصطدم بـ per-minute limit.

التعامل مع مفاتيح API

لا تحفر أبداً. لا تستخدم أبداً في frontend JS. لا تقم بـ commit أبداً إلى Git. دائماً عبر متغير ENV، vault/secrets manager أو CI/CD secret. في حالة الاشتباه بتسرب: ألغ فوراً في البوابة + أنشئ مفتاحاً جديداً.

الأداء والكمون

أي أوقات استجابة يجب توقعها وكيف نحقق هذه الأرقام.

أوقات استجابة نموذجية

P50 أقل من 30 ms من datacenters الاتحاد الأوروبي لـ lookups فردية.
P99 أقل من 100 ms — الذرات عادة GC pauses أو Whois async pre-cache، وليس وقت انتظار حقيقي.
Batch مع 100 IP: أقل من 100 ms P50 (متوازي داخلياً، DB roundtrip واحد).
أول lookup Whois لـ IP جديد: ~200-400 ms (RDAP roundtrip إلى RIR). من الاستدعاء الثاني: sub-millisecond (cache 30 يوماً).

البنية التحتية

خوادم في ألمانيا + النمسا (استضافة الاتحاد الأوروبي لـ GDPR). فهرس binary range in-memory بدلاً من استعلامات DB كلاسيكية — لذلك لا cold start، لا ضغط على connection pool.

Headers cache الاستجابة

Geo lookups: Cache-Control: private, no-cache (قد تتغير النتيجة عندما نحدث GeoLite2). Whois: Cache-Control: max-age=86400 (cache backend 30 يوماً، cache client يوم واحد OK). /flags/*.svg: Cache-Control: public, max-age=86400, immutable.

وصفات التكامل

copy-paste ملموس جاهز. ثلاث setups شائعة في الممارسة.

Cloudflare Worker — إثراء IP في edge

كل طلب يحصل في Worker على دولة IP الزائر مضمنة. يوفر القيام بذلك في كود تطبيق origin.

user@geoips:~$cat worker.js

// Cloudflare Worker — IP-Enrichment am Edge
export default {
  async fetch(req, env) {
    const ip = req.headers.get("cf-connecting-ip");
    const r = await fetch(`https://api.geoips.info/v1/lookup/${ip}`, {
      headers: { "X-API-Key": env.GEOIPS_KEY },
    });
    const geo = await r.json();
    const next = await fetch(req);
    const res = new Response(next.body, next);
    res.headers.set("x-geo-country", geo.country_code || "");
    res.headers.set("x-geo-city", geo.city || "");
    return res;
  },
};

Nginx — الدولة في access log

عبر وحدة Lua lookup واحد لكل طلب، ثم في تنسيق log مخصص. Async fetch عبر lua-resty-http.

user@geoips:~$cat nginx-geo.lua

# nginx.conf — Country in jedem Access-Log
log_format with_geo '$remote_addr [$geo_country] "$request" $status';

location / {
    access_by_lua_block {
        local http = require "resty.http"
        local h = http.new()
        local res = h:request_uri("https://api.geoips.info/v1/lookup/" .. ngx.var.remote_addr, {
            headers = { ["X-API-Key"] = os.getenv("GEOIPS_KEY") },
        })
        if res and res.status == 200 then
            local cjson = require "cjson.safe"
            local data = cjson.decode(res.body)
            ngx.var.geo_country = data and data.country_code or "??"
        end
    }
    access_log /var/log/nginx/access.log with_geo;
}

WordPress — shortcode "أين أنا؟"

Plugin snippet يسجل shortcode [where_am_i]. يرجع دولة + علم الزائر الحالي. Cache لكل session.

user@geoips:~$cat wp-geo-shortcode.php

<?php
// functions.php — [where_am_i] Shortcode
add_shortcode('where_am_i', function () {
    $ip = $_SERVER['HTTP_X_FORWARDED_FOR'] ?? $_SERVER['REMOTE_ADDR'];
    $cache_key = 'geo_' . md5($ip);
    $data = get_transient($cache_key);
    if (!$data) {
        $resp = wp_remote_get("https://api.geoips.info/v1/lookup/$ip", [
            'headers' => ['X-API-Key' => getenv('GEOIPS_KEY')],
            'timeout' => 3,
        ]);
        if (is_wp_error($resp)) return '';
        $data = json_decode(wp_remote_retrieve_body($resp), true);
        set_transient($cache_key, $data, 6 * HOUR_IN_SECONDS);
    }
    if (empty($data['country_code'])) return '';
    return sprintf(
        '<img src="https://geoips.info/flags/%s.svg" width="20" alt=""> %s, %s',
        strtolower($data['country_code']),
        esc_html($data['city'] ?? ''),
        esc_html($data['country_name'] ?? '')
    );
});

AWS Lambda / Vercel — edge function

نمط Serverless: مفتاح API من env، fetch في function، response مُعاد توجيهه. يعمل في أي cloud لأنه لا شيء خاص بـ AWS.

user@geoips:~$cat lambda-handler.js

// AWS Lambda (Node 20) — eingebettete Geo-Enrichment-Function
export const handler = async (event) => {
  const ip = event.headers["x-forwarded-for"]?.split(",")[0] ?? event.requestContext.identity.sourceIp;
  const r = await fetch(`https://api.geoips.info/v1/lookup/${ip}`, {
    headers: { "X-API-Key": process.env.GEOIPS_KEY },
  });
  const geo = await r.json();
  return {
    statusCode: 200,
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ source_country: geo.country_code, ...geo }),
  };
};

الترحيل من APIs المنافسة

قادم من MaxMind، ipinfo.io أو ipstack؟ إليك كيف تتطابق الحقول.

حقلنا	MaxMind GeoLite2 / GeoIP2	ipinfo.io	ipstack
country_code	country.iso_code	country	country_code
country_name	country.names.en	country_name	country_name
flag	—	country_flag.emoji	—
flag_url	—	country_flag_url	location.country_flag
region	subdivisions[0].names.en	region	region_name
city	city.names.en	city	city
zip	postal.code	postal	zip
latitude	location.latitude	loc (split)	latitude
longitude	location.longitude	loc (split)	longitude
timezone	location.time_zone	timezone	time_zone.id
asn	traits.autonomous_system_number	org (parsed)	connection.asn
as	traits.autonomous_system_organization	org (parsed)	connection.isp
cidr	traits.network	—	—
whois.org_name	—	abuse.name (premium)	—
whois.abuse_email	—	abuse.email (premium)	—

اختلافات مهمة

نقدم Whois + إيموجي/SVGs أعلام بدون تكلفة إضافية — لدى الآخرين كلاهما يكلف إضافياً أو غير متاح إطلاقاً.
country_code لدينا دائماً ISO 3166-1 alpha-2 أحرف كبيرة. MaxMind يستخدم جزئياً أكواداً خاصة، نحن لا.
Batch endpoint يأخذ 100 IP في طلب واحد. MaxMind لا يعرف هذا؛ ipinfo cap عند 1000 (لكن فقط في الخطط الأغلى).
خطتنا المجانية: 8,000 lookup/يوم. MaxMind/ipinfo/ipstack مجاناً: عادة 1,000/يوم أو أقل.

المصطلحات

موضح بإيجاز، ما نستخدمه أين.

RDAP: Registration Data Access Protocol — خليفة WHOIS (port 43). REST API مبني على JSON. جميع 5 RIRs (RIPE/ARIN/...) ينفذونه. نحن نخزن الردود لمدة 30 يوماً.
RIR (Regional Internet Registry): 5 منظمات تخصص بلوكات IP: RIPE (أوروبا+الشرق الأوسط)، ARIN (أمريكا الشمالية)، APNIC (آسيا والمحيط الهادئ)، LACNIC (أمريكا اللاتينية)، AFRINIC (أفريقيا).
CIDR (Classless Inter-Domain Routing): Notation لبلوكات IP: 8.8.8.0/24 = 256 عنواناً من 8.8.8.0 إلى 8.8.8.255. /24 يقول: 24 bit هي الشبكة، الباقي هو host space.
ASN (Autonomous System Number): رقم فريد لمشغل شبكة (ISP، cloud provider). عدد صحيح 32-bit، في الممارسة مكتوب مع بادئة AS (AS15169 = Google). عدة بلوكات CIDR غالباً ما تتشارك ASN واحد.
MaxMind GeoLite2: tier مجاني من قاعدة بيانات MaxMind لـ mapping IP-إلى-geo. تحديثات أسبوعية، دقة الدولة ~99.8%، المدينة ~75% ضمن 50 كم.
IP خاص: بلوكات محجوزة غير routable: 10.0.0.0/8، 172.16.0.0/12، 192.168.0.0/16 (IPv4)، fc00::/7 (IPv6). Loopback 127.0.0.0/8 و ::1. نرفض lookups على هذه النطاقات بـ 400/private_ip.
Idempotency: استدعاءات متعددة لها نفس التأثير كاستدعاء واحد. جميع endpoints GET لدينا idempotent. POST /v1/lookup/batch أيضاً (لا يعدل server state، فقط read-only).
Sliding window (rate limit): يحسب الطلبات في آخر N ثوانٍ — ينزلق باستمرار مع الوقت. على عكس fixed window (مثل "في هذه الساعة") لا توجد ذرى burst في انتقالات الساعة.
Fixed window (limit يومي): Counter يُعاد تعيينه في نقطة زمنية ثابتة (افتراضي 00:00 UTC). قابل للتنبؤ للفوترة. عيب: قبل reset ببضع ثوان يمكن استخدام الـ limit الكامل، بعد reset ببضع ثوان مرة أخرى — burst قصير ممكن.
Anycast: IP واحد يُعلن في وقت واحد من مواقع متعددة في العالم (BGP). الزائر يصل دائماً إلى الأقرب جغرافياً. IPs anycast معروفة: 8.8.8.8 (Google DNS)، 1.1.1.1 (Cloudflare). ردود GeoIP لـ IPs anycast هي مجرد تعيين "الأكثر احتمالاً".

الحالة، SLA والدعم

كيفية الاتصال بنا عندما لا يعمل شيء.

Uptime monitoring

GET /v1/health يرجع {status:"ok", version:"..."} بدون auth. اربط endpoint بـ UptimeRobot / Pingdom / monitoring الخاص بك (التردد: كل 60 ث كافٍ). في status != ok أو خطأ HTTP: قم بتشغيل alert.

SLA

Free/Starter/Business ليس لديها SLA رسمي — نقدم best-effort 99.5%+ uptime (انظر endpoint health). خطة Enterprise يمكن الاتفاق عليها بشكل فردي بعقد (مثل 99.95% مع credit مسطح عند عدم الاستيفاء).

اتصال

المستخدمون المسجلون: عبر نموذج الدعم في البوابة (محفوظ داخلياً كـ ticket، لا يضيع بريد إلكتروني). غير مسجلين: support@geoips.info. وقت الاستجابة عادة أقل من 4 ساعات (يوم عمل).

الحوادث

في الانقطاعات الأكبر نقوم بتفعيل وضع الصيانة (جميع استدعاءات API ترجع 503 مع error_code maintenance_mode + Retry-After). صفحة حالة مع uptime تاريخي في roadmap لعام 2026.

أسئلة المطورين الشائعة

كم IP يمكن أن يحتوي POST /v1/lookup/batch؟▾

الحد الأقصى 100، يعتمد على الخطة. hard cap الملزم هو 100، plan cap الخاص بك قد يكون أقل (Free: 10، Starter: 50، Business+: 100). عند التجاوز: HTTP 400 مع batch_too_large.

كم يكلف lookup Whois؟▾

حسب إعداد admin (whois.gating_mode): إما Whois يستهلك 1 من الحصة اليومية، أو له pot مخصص (whois_limit_per_day لكل خطة)، أو هو plan-gated (مثل Starter+ فقط).

خادمي خلف reverse proxy. هل لا يزال /v1/lookup/self يعمل؟▾

نعم، طالما يقوم الـ proxy بضبط X-Forwarded-For بشكل صحيح. نقرأ الإدخال الأخير (= الموثوق) من السلسلة، وليس الأول — defense in depth ضد spoofing.

هل يمكنني الاستعلام عن 1000 IP في وقت واحد؟▾

ليس في batch واحد (cap 100). لكن: ببساطة أرسل 10 batches من 100 بالتتابع — sliding minute limiter يسمح بذلك بسهولة طالما تبقى في الميزانية اليومية.

كيف أتحقق من أن الاستجابة تأتي منكم فعلاً؟▾

شهادة TLS عبر Cloudflare. إذا كانت لديك متطلبات أكثر صرامة (مثل للامتثال): اتصل بنا، يمكننا تنفيذ توقيعات body الاستجابة عبر HMAC بمفتاحك.

هل يتم lookup لـ IPs خاصة (10.x، 192.168.x)؟▾

لا — هذه ترجع HTTP 400 مع private_ip. صفي في الكود (فحوصات private range جاهزة لـ IPv4/IPv6 موجودة في كل لغة) — كما يمنع IPs خاصة من الانتهاء بالخطأ في السجلات.

ماذا عن Whois لأسماء domain (وليس IPs)؟▾

حالياً فقط IP whois (RDAP). Domain whois بروتوكول مختلف (قاعدة بيانات registrar). على roadmap لعام 2026.

هل لديكم SDK رسمي؟▾

لا، عمداً لا — الـ API صغير بما يكفي بحيث fetch/requests/http في أي لغة كافية. أمثلة الكود أعلاه جاهزة copy-paste.