التوثيق / مرجع الواجهة

الموقع الجغرافي للزائر

تُرجع الموقع والشبكة والمنطقة الزمنية والعملة والملف الأمني للزائر الذي يستدعي واجهتك.

نظرة عامة#

تجيب geoip عن سؤال "من الطرف الآخر من هذا الاتصال؟" دون أن تمرّر أي عنوان. تقرأ Gurdx عنوان IP الخاص بالطلب وتثريه بالجغرافيا (القارة والدولة والمنطقة والمدينة والإحداثيات والعلم والعاصمة واللغات) والشبكة المالكة (ASN) والوقت المحلي ومواعيد الشروق والغروب والعملة، إضافة إلى وحدتي الأمان والجهاز الاختياريتين.

متى تستخدمها#

استدعها من متصفح الزائر أو تطبيقه لتعبئة الدولة أو العملة تلقائيًا.
لتقييد مسار التسجيل أو توطينه حسب الموقع الفعلي للمستخدم.
لاكتشاف جلسة قادمة عبر بروكسي أو VPN أو Tor أو مزود استضافة.

إذا أردت فحص عنوان لا يخص المتصل، كعنوان مخزّن في قاعدة بياناتك أو مقروء من ترويسة على خادمك، فاستخدم فحص عنوان IP.

اختيار ما تستلمه#

تحصل افتراضيًا على الاستجابة الكاملة. مرّر params لتطلب الوحدات التي تحتاجها فقط: security وcurrency وtimezone وlocation وdevice. الاستجابة الأصغر أسرع؛ راجع تخصيص الوحدات. وحدة device تحلل user agent الطلب، لذا لا معنى لها إلا حين يأتي الطلب من جهاز المستخدم النهائي نفسه.

قراءة النتيجة#

security.isProxy تكون true لبنية إخفاء الهوية، وsecurity.proxyType يحدد نوعها (مثل VPN أو SOCKS أو بروكسي عام). اعتبرها إشارة لرفع مستوى التحقق لا دليلًا على الاحتيال، فكثير من المستخدمين الصادقين يستخدمون VPN.
security.isTor وsecurity.isBot وsecurity.isRelay وsecurity.isHosting تدل على عقد Tor والزيارات الآلية ومُرحِّلات الخصوصية ونطاقات مراكز البيانات.
security.blacklisted تكون true عند تطابق العنوان مع إحدى قوائمك السوداء.
bogon يعني عنوانًا خاصًا أو غير قابل للتوجيه، وغالبًا يعني أن خادمك رأى عنوان وسيط داخلي بدل عنوان الزائر.

ملاحظات#

تُحتسب طلبًا واحدًا. في mode=test أو بمفتاح gx_test_ تستلم بيانات وهمية ولا يُحتسب شيء.
متاحة في جميع الباقات. وحدتا الأمان والجهاز تتطلبان الميزتين security_module وdevice_module، وبدونهما يصلك الخطأ 114.
عند تفعيل القواعد المخصصة في باقتك يمكن لـالقواعد المخصصة إضافة العنوان إلى القائمة السوداء أو البيضاء، وتظهر النتيجة في custom_rules_applied.
يُطلَق حدث suspicious_ip عندما تبلغ درجة الخطورة 50 من 100، ويصل إلى الويب هوك.
خلف وكيل عكسي تأكد من وصول عنوان المتصل الحقيقي إلى Gurdx لا عنوان الوكيل.

الطلب#

GET https://gurdx.cretip.com/api/geoip

صادِق بمعامل key أو بترويسة Authorization: Bearer.
تُحتسب طلباً واحداً.
متاحة في: تجربة مجانية القياسية المميّزة الدفع حسب الاستخدام

المعاملات#

الاسم	النوع	الوصف
`params` اختياري استعلام	`string`	The params command can be used to specify the required modules you want to get in the response. Expected values: `security`, `currency`, `timezone`, `location`, and/or `device` Sample value: `security,timezone,currency` For more information please refer to Customize response modules.

تقبل كل خدمة أيضاً format, lang, mode, userID, callback. راجع الخيارات.

أمثلة برمجية#

curl -G "https://gurdx.cretip.com/api/geoip" \
  --data-urlencode "key=YOUR_API_KEY"

<?php

$response = file_get_contents('https://gurdx.cretip.com/api/geoip?'.http_build_query(['key' => 'YOUR_API_KEY']));
$result = json_decode($response, true);

if ($result['status'] === 'success') {
    print_r($result['data']);
} else {
    echo $result['code'].': '.$result['description'];
}

const params = new URLSearchParams({"key":"YOUR_API_KEY"});
const res = await fetch(`https://gurdx.cretip.com/api/geoip?${params}`);
const result = await res.json();

if (result.status === 'success') {
  console.log(result.data);
} else {
  console.error(result.code, result.description);
}

import requests

res = requests.get("https://gurdx.cretip.com/api/geoip", params={"key": "YOUR_API_KEY"})
result = res.json()

if result["status"] == "success":
    print(result["data"])
else:
    print(result["code"], result["description"])

الاستجابة#

نجاح#

{
    "data": {
        "ip": "165.227.149.217",
        "ipType": "IPv4",
        "IPNumber": 2783155673,
        "bogon": false,
        "continentName": "Europe",
        "continentCode": "EU",
        "countryCode": "DE",
        "continentGeoNameID": 6255148,
        "countryName": "Germany",
        "countryGeoNameID": 2921044,
        "regionName": "Hessen",
        "cityName": "Frankfurt am Main",
        "zipCode": "65931",
        "latitude": "50.115520",
        "longitude": "8.684170",
        "location": {
            "capital": "Berlin",
            "population": 83783942,
            "language": {
                "name": "German",
                "code": "de",
                "native": "Deutsch"
            },
            "flag": {
                "emoji": "🇩🇪",
                "unicode": "U+1F1E9 U+1F1EA",
                "png": {
                    "1000px": "https://gurdx.cretip.com/flags/png1000px/de.png",
                    "250px": "https://gurdx.cretip.com/flags/png250px/de.png",
                    "100px": "https://gurdx.cretip.com/flags/png100px/de.png"
                },
                "svg": "https://gurdx.cretip.com/flags/svg/de.svg"
            },
            "phoneCode": "49",
            "countryIsEU": true,
            "countryNeighbours": "CH,PL,NL,DK,BE,CZ,LU,FR,AT",
            "tld": ".de"
        },
        "currency": {
            "currencyName": "Euro",
            "currencyCode": "EUR",
            "currencySymbol": "€"
        },
        "asn": {
            "asn": "AS14061",
            "name": "DIGITALOCEAN-ASN",
            "org": "DigitalOcean, LLC",
            "phone": "+1-347-875-6044",
            "email": "noc@digitalocean.com",
            "domain": "digitalocean.com",
            "created": "2012-05-14",
            "type": "hosting"
        },
        "timezone": {
            "name": "Europe/Berlin",
            "abbreviation": "CET",
            "offset": 3600,
            "currentTime": "03:33:13",
            "currentTimestamp": 1709519593,
            "isDST": false,
            "sunInfo": {
                "sunset": "18:14:11",
                "sunrise": "06:59:29",
                "transit": "12:36:50",
                "civilTwilightBegin": "06:28:47",
                "civilTwilightEnd": "18:44:53",
                "nauticalTwilightBegin": "05:51:20",
                "nauticalTwilightEnd": "19:22:21",
                "astronomicalTwilightBegin": "05:13:27",
                "astronomicalTwilightEnd": "20:00:13",
                "dayLength": "11:14:42"
            }
        },
        "security": {
            "isProxy": true,
            "proxyType": "VPN",
            "isTor": false,
            "isBot": false,
            "isRelay": false,
            "isHosting": true,
            "blacklisted": false
        },
        "device": {
            "isMobile": false,
            "type": "desktop",
            "OS": {
                "type": "desktop",
                "name": "MacOS",
                "family": "macintosh",
                "version": "Big Sur",
                "title": "MacOS Big Sur",
                "64bits_mode": 1
            },
            "browser": {
                "name": "Safari",
                "version": 17.2,
                "versionMajor": 1,
                "title": "Safari 17.2"
            }
        },
        "custom_rules_applied": {
            "total": 0,
            "rules": []
        }
    },
    "status": "success",
    "executionTime": 4
}

خطأ#

تُسلَّم الأخطاء بحالة HTTP 200 — افحص دائماً حقل status.

{
    "status": "error",
    "code": 101,
    "type": "invalid_key",
    "description": "The API Key is missing or invalid."
}

حقول الاستجابة#

الاسم	النوع	الوصف
`data.ip`	`string`	IP address you're looking up.
`data.ipType`	`string`	Type of IP address (`IPv4`, or `IPv6`).
`data.IPNumber`	`integer`	Numeric representation of the IP address.
`data.bogon`	`boolean`	Indicates if the IP address is a bogon.
`data.continentName`	`string`	Name of the continent where the IP address is.
`data.continentCode`	`string`	Code representation of the continent.
`data.countryCode`	`string`	Code representation of the country in `ISO-3166` format.
`data.continentGeoNameID`	`integer`	GeoName ID of the continent.
`data.countryName`	`string`	Name of the country.
`data.countryGeoNameID`	`integer`	GeoName ID of the country.
`data.regionName`	`string`	Name of the region.
`data.cityName`	`string`	Name of the city.
`data.zipCode`	`string`	ZIP code of the location where the IP address belong.
`data.latitude`	`string`	Latitude coordinate of the location.
`data.longitude`	`string`	Longitude coordinate of the location.
`data.location.capital`	`string`	Capital city of the country.
`data.location.population`	`integer`	Population of the country.
`data.location.language.name`	`string`	Official language of the country.
`data.location.language.code`	`string`	Language code in `ISO-639` format.
`data.location.language.native`	`string`	Native name of the language.
`data.location.language`	`object`	—
`data.location.flag.emoji`	`string`	Flag emoji representation.
`data.location.flag.unicode`	`string`	Flag Unicode representation.
`data.location.flag.png.1000px`	`string`	URL to 1000px PNG flag.
`data.location.flag.png.250px`	`string`	URL to 250px PNG flag.
`data.location.flag.png.100px`	`string`	URL to 100px PNG flag.
`data.location.flag.png`	`object`	—
`data.location.flag.svg`	`string`	URL to SVG flag.
`data.location.flag`	`object`	—
`data.location.phoneCode`	`string`	International dialing code for the country.
`data.location.countryIsEU`	`boolean`	Indicates if the country is in the EU.
`data.location.countryNeighbours`	`string`	List of neighboring countries' codes.
`data.location.tld`	`string`	Top-level domain of the country.
`data.location`	`object`	—
`data.currency.currencyName`	`string`	Name of the currency.
`data.currency.currencyCode`	`string`	Currency code in `ISO-4217` format.
`data.currency.currencySymbol`	`string`	Symbol of the currency.
`data.currency`	`object`	—
`data.asn.asn`	`string`	Autonomous System Number.
`data.asn.name`	`string`	Name of the ASN.
`data.asn.org`	`string`	Organization associated with the ASN.
`data.asn.phone`	`string`	Phone contact for the ASN.
`data.asn.email`	`string`	Email contact for the ASN.
`data.asn.domain`	`string`	Domain associated with the ASN.
`data.asn.created`	`string`	Date of ASN creation.
`data.asn.type`	`string`	Type of organization ("isp", "hosting", "business", "education", or "government").
`data.asn`	`object`	—
`data.timezone.name`	`string`	Timezone name.
`data.timezone.abbreviation`	`string`	Timezone abbreviation.
`data.timezone.offset`	`integer`	Timezone offset from UTC.
`data.timezone.currentTime`	`string`	Current time in the timezone.
`data.timezone.currentTimestamp`	`integer`	Current timestamp in the timezone.
`data.timezone.isDST`	`boolean`	Indicates if Daylight Saving Time is active.
`data.timezone.sunInfo.sunset`	`string`	Sunset time.
`data.timezone.sunInfo.sunrise`	`string`	Sunrise time.
`data.timezone.sunInfo.transit`	`string`	Solar transit time.
`data.timezone.sunInfo.civilTwilightBegin`	`string`	Civil twilight begin time.
`data.timezone.sunInfo.civilTwilightEnd`	`string`	Civil twilight end time.
`data.timezone.sunInfo.nauticalTwilightBegin`	`string`	Nautical twilight begin time.
`data.timezone.sunInfo.nauticalTwilightEnd`	`string`	Nautical twilight end time.
`data.timezone.sunInfo.astronomicalTwilightBegin`	`string`	Astronomical twilight begin time.
`data.timezone.sunInfo.astronomicalTwilightEnd`	`string`	Astronomical twilight end time.
`data.timezone.sunInfo.dayLength`	`string`	Length of the day.
`data.timezone.sunInfo`	`object`	—
`data.timezone`	`object`	—
`data.security.isProxy`	`boolean`	Indicates if the IP address is a proxy service.
`data.security.proxyType`	`string`	Type of proxy used.
`data.security.isTor`	`boolean`	Indicates if accessed through Tor network.
`data.security.isBot`	`boolean`	Indicates if the user is a bot.
`data.security.isRelay`	`boolean`	Indicates if it's a Apple's Private Relay connection.
`data.security.isHosting`	`boolean`	Indicates if the IP address belong to a hosting provider.
`data.security.blacklisted`	`boolean`	Indicates if the IP address is blacklisted due to applying custom rules or were found in one of your blacklists.
`data.security`	`object`	—
`data.device.isMobile`	`boolean`	Indicates if the device is a mobile device.
`data.device.type`	`string`	Type of device.
`data.device.OS.type`	`string`	Type of operating system.
`data.device.OS.name`	`string`	Name of the operating system.
`data.device.OS.family`	`string`	Family of the operating system.
`data.device.OS.version`	`string`	Version of the operating system.
`data.device.OS.title`	`string`	Title of the operating system.
`data.device.OS.64bits_mode`	`integer`	Indicates 64-bit mode (1 for true, 0 for false).
`data.device.OS`	`object`	—
`data.device.browser.name`	`string`	Name of the browser.
`data.device.browser.version`	`number`	Version of the browser.
`data.device.browser.versionMajor`	`integer`	Major version of the browser.
`data.device.browser.title`	`string`	Title of the browser.
`data.device.browser.userAgent`	`string`	The user-agent of the browser.
`data.device.browser`	`object`	—
`data.device`	`object`	—
`data.custom_rules_applied.total`	`integer`	The total number of custom rules applied to this request.
`data.custom_rules_applied.rules.id`	`string`	The rule ID as shown in the dashboard (e.g: `CR104`).
`data.custom_rules_applied.rules.title`	`string`	The rule title you set when creating the rule.
`data.custom_rules_applied.rules`	`object`	The custom rules applied to this request, learn more.
`data.custom_rules_applied`	`object`	The custom rules applied to this request, learn more.
`data.status`	`string`	Response status (success/error).
`data.executionTime`	`integer`	Time taken to process the data (in milliseconds).
`data`	`object`	—

وجدت خطأ؟ أخبرنا عبر صفحة التواصل. تواصل معنا