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

معلومات الدولة

تُرجع معلومات مرجعية عن دولة انطلاقًا من رمزها المكوّن من حرفين حسب ISO.

نظرة عامة#

يستقبل lookup/country المعامل CountryCode بصيغة ISO 3166-1 alpha-2 مثل GB أو US، ويُرجع حقائق ثابتة عن الدولة: countryName والمعرّف الجغرافي الرقمي وcapital وpopulation ورمز الاتصال الدولي phoneCode وcurrency (الاسم والرمز والرمز المختصر) وlanguage الرئيسية ومعلومات timezone للدولة مع أوقات الشمس. هي بيانات مرجعية لا تقييم مخاطر، ولا علاقة لها بعنوان IP لأي زائر.

متى تستخدمه#

لتعبئة قوائم الدول والعملات ورموز الاتصال من مصدر واحد.
لعرض العملة أو اللغة المحلية بعد اختيار المستخدم دولته.
لتوحيد رمز دولة وصلك من نظام آخر قبل تخزينه أو مقارنته.

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

استخدم countryCode مفتاحًا معتمدًا وcountryName للعرض.
phoneCode هو بادئة الاتصال بدون علامة الزائد؛ ادمجه مع الرقم المحلي لبناء رقم دولي ثم تحقق منه عبر تقييم رقم الجوال.
currency.currencyCode هو رمز ISO 4217، ومناسب للتسعير ولمقارنته بـtransaction_currency الذي ترسله إلى كشف احتيال الدفع.
كتلة المنطقة الزمنية تصف منطقة واحدة ممثِّلة، فلا تعامل الدول متعددة المناطق كأن لها إزاحة واحدة.

ملاحظات#

تُحتسب طلبًا واحدًا. وضع الاختبار يُرجع بيانات وهمية مجانًا ولا يتصل بأي خدمة خارجية.
مشمولة في كل الباقات بما فيها القياسية.
لا تطلق أحداثًا ولا تدعم القواعد المخصصة أو القوائم السوداء.
الرمز المفقود أو الذي ليس رمز دولة alpha-2 صحيحًا يُرجع الخطأ 116 (invalid_country_code) مع HTTP 200.
لأن البيانات نادرًا ما تتغير، خزّن الاستجابة مؤقتًا عندك بدل استدعاء الدالة مع كل زيارة صفحة.

الطلب#

GET https://gurdx.cretip.com/api/lookup/country

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

المعاملات#

الاسم	النوع	الوصف
`CountryCode` مطلوب استعلام	`string`	The `ISO 3166-1 alpha-2` format of the country code. Learn more Sample value: `GB`
`params` اختياري استعلام	`string`	The params command is used to determine the data you need in the response. Expected values: `language`, `flag`, `currency`, and/or `timezone`. Sample value: `language,currency,timezone`

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

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

curl -G "https://gurdx.cretip.com/api/lookup/country" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "CountryCode=SA"

<?php

$response = file_get_contents('https://gurdx.cretip.com/api/lookup/country?'.http_build_query(['key' => 'YOUR_API_KEY', 'CountryCode' => 'SA']));
$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","CountryCode":"SA"});
const res = await fetch(`https://gurdx.cretip.com/api/lookup/country?${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/lookup/country", params={"key": "YOUR_API_KEY", "CountryCode": "SA"})
result = res.json()

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

الاستجابة#

نجاح#

{
    "data": {
        "countryCode": "US",
        "countryName": "United States",
        "countryGeoNameID": 6252001,
        "capital": "Washington, D.C.",
        "population": 331000000,
        "phoneCode": "1",
        "currency": {
            "currencyName": "United States Dollar",
            "currencyCode": "USD",
            "currencySymbol": "$"
        },
        "language": {
            "name": "Portuguese",
            "code": "pt",
            "native": "Português"
        },
        "timezone": {
            "name": "America/Adak",
            "abbreviation": "HST",
            "offset": -36000,
            "currentTime": "11:51:19",
            "currentTimestamp": 1643406679,
            "isDST": false,
            "sunInfo": {
                "sunset": "08:17:34",
                "sunrise": "20:08:16",
                "transit": "02:12:55",
                "civilTwilightBegin": "19:47:39",
                "civilTwilightEnd": "08:38:10",
                "nauticalTwilightBegin": "19:22:22",
                "nauticalTwilightEnd": "09:03:28",
                "astronomicalTwilightBegin": "18:57:01",
                "astronomicalTwilightEnd": "09:28:49",
                "dayLength": "11:50:42"
            }
        },
        "flag": {
            "emoji": "🇺🇸",
            "unicode": "U+1F1FA U+1F1F8",
            "png": {
                "1000px": "https://gurdx.cretip.com/flags/png1000px/us.png",
                "250px": "https://gurdx.cretip.com/flags/png250px/us.png",
                "100px": "https://gurdx.cretip.com/flags/png100px/us.png"
            },
            "svg": "https://gurdx.cretip.com/flags/svg/us.svg"
        },
        "countryIsEU": false,
        "countryNeighbours": "CA,MX,CU",
        "tld": ".us",
        "continentName": "North America",
        "continentCode": "NA",
        "continentGeoNameID": 6255149
    },
    "status": "success",
    "executionTime": 0
}

خطأ#

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

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

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