/api/v4/countriesعرض البلدان والولايات المدعومة
يُرجع كل بلد تدعمه Listings API، مع ولاياته أو مقاطعاته، ورموز ISO المستخدمة عند إنشاء المواقع أو تحديثها، وحقول العنوان التي يفرضها كل بلد أو يتحقق منها.
المعلمات
لا تأخذ نقطة النهاية هذه أي معلمات.
الاستجابات
200List of supported countries, each with its states and ISO codes. The live response is trimmed here to the United States, with three of its states.
{ "data": { "supportedCountries": [ { "databaseId": 233, "hasCity": true, "id": "Q291bnRyeToyMzM=", "iso": "US", "name": "United States", "hasPostalCode": true, "stateRequired": true, "states": [ { "countryId": 233, "id": "3542", "iso": "CA", "name": "California" }, { "countryId": 233, "id": "3537", "iso": "NY", "name": "New York" }, { "countryId": 233, "id": "3524", "iso": "TX", "name": "Texas" } ] } ] }}401Unauthenticated, missing or invalid API key.
500Internal server error.
يُرجع القائمة الكاملة للبلدان وتقسيماتها الإدارية (الولايات والمقاطعات والأقاليم) التي تدعمها Listings API لبيانات المواقع. يتضمن سجل كل بلد رمز ISO الخاص به (iso)، وid الخاص بـ Relay، وdatabaseId رقميًا، ومصفوفة states، وثلاث علامات تحدد كيفية التحقق من عنوان الموقع في ذلك البلد. تتضمن كل ولاية iso الخاص بها وid رقميًا. تُرجع البلدان التي لا توفر Listings API تقسيمات إدارية لها مصفوفة states فارغة.
قواعد العنوان لكل بلد
postalCode اختياري في كل بلد، لكن أرسله كلما كانت قيمة hasPostalCode هي true: إذ تحتاج إليه بعض منصات النشر لوضع دبوس الخريطة. تُفحص أي قيمة ترسلها للتأكد من مطابقتها لتنسيق البلد (SY10014). عند وجود hideAddress: true في بيانات الموقع، تُتخطّى عمليات التحقق من المدينة والولاية.
حالة استخدام: تعبئة القوائم المنسدلة للعنوان. اجلب هذه البيانات مرة واحدة عند بدء تشغيل التطبيق وخزّنها مؤقتًا. اعرض قائمة اختيار البلد باستخدام name/iso، وعند اختيار بلد، عبّئ قائمة اختيار الولاية من states الخاص بذلك البلد. تُستخدم قيم iso مباشرةً في الحقلين countryIso وstateIso في نقطتي النهاية create-location وupdate-location.
حالة استخدام: التحقق من صحة العنوان قبل إرساله. قبل استدعاء create-location، تحقق من وجود countryIso المستهدف في هذه القائمة، ومن ظهور stateIso ضمن ذلك البلد عندما تكون قيمة stateRequired هي true، ومن تعيين city عندما تكون قيمة hasCity هي true. يتيح اكتشاف رمز غير مدعوم هنا عرض رسالة واضحة من جانب العميل بدلًا من تلقي 400 من استدعاء الإنشاء. الاستجابة الكاملة كبيرة (تشمل كل بلد مدعوم)؛ وقد اختُصر المثال أعلاه إلى سجل واحد. لا توجد معاملات استعلام، وتُرجع نقطة النهاية دائمًا المجموعة الكاملة.
curl -X GET 'https://listingsapi.com/api/v4/countries' \ -H "Authorization: API $LISTINGSAPI_KEY"