البحث عن البلدان والولايات والفئات

اجلب البلدان المدعومة ورموز الولايات، وحدّد المعرّف الرقمي لفئة نشاط تجاري، وتعرّف على منصات النشر التي تشملها خطتك قبل إنشاء موقع.

يتطلب إنشاء موقع ثلاث قيم يجب الحصول عليها من API: قيمتَي countryIso وstateIso يقبلهما API، وقيمة رقمية لـ subCategoryId، ومعرّفات منصات النشر المشمولة في خطتك إذا أردت حصر منصات النشر. توفّر هذه القيم ثلاث نقاط نهاية للكتالوجات. وتُرجع كل منها مصفوفة بسيطة دون تقسيم إلى صفحات.

1. عرض البلدان ورموز الولايات

تُرجع GET /countries كل بلد مدعوم مع رمز ISO الخاص به، وعلامة hasCity، ومصفوفة states. تُستخدم قيم iso لتعبئة countryIso وstateIso عند الإنشاء والتحديث. توفّر حزمة Python SDK هذه الوظيفة عبر client.countries()، وتوفّرها حزمة Node SDK عبر client.fetchCountries().

Countries

curl https://listingsapi.com/api/v4/countries \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "supportedCountries": [      {        "databaseId": 13,        "iso": "AU",        "name": "Australia",        "hasCity": true,        "states": [          { "id": "139", "iso": "VIC", "name": "Victoria" },          { "id": "142", "iso": "NSW", "name": "New South Wales" }        ]      },      {        "databaseId": 17,        "iso": "BE",        "name": "Belgium",        "hasCity": true,        "states": []      }    ]  }}

تعني hasCity: true أن city مطلوب عند الإنشاء؛ وعند false، تُحذف المدينة التي ترسلها. تعني stateRequired: true أن stateIso مطلوب ويجب أن يكون إحدى قيم states الخاصة بالبلد؛ وعند false، لا تُدرجه. تعني hasPostalCode: true أن البلد يستخدم الرموز البريدية، لذا أرسل postalCode مع العنوان. يشرح توثيق نقطة نهاية البلدان كل علامة.

2. العثور على معرّف فئة

تُرجع GET /sub-categories كتالوج الفئات كاملًا. القيمة التي ترسلها في subCategoryId هي databaseId، أي العدد الصحيح، وليست id المرمّزة بصيغة base64. ففئة المطاعم، مثلًا، معرّفها 1432. صفِّ القائمة حسب الاسم في التعليمات البرمجية الخاصة بك؛ فلا يوجد معامل بحث من جانب الخادم.

Find a category

curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.subcategories[] | select(.name | test("restaurant"; "i")) | {databaseId, name, primary}'

JSON

{  "data": {    "subcategories": [      {        "databaseId": 1432,        "id": "U3ViQ2F0ZWdvcnk6MTQzMg==",        "key": "restaurants",        "name": "Restaurants",        "primary": true      }    ]  }}

الحقل	استخدامه
`databaseId`	العدد الصحيح الذي يُرسل في `subCategoryId`، أو ضمن `additionalCategoryIds` لما يصل إلى 9 فئات ثانوية.
`name`	التسمية المقروءة للمستخدم التي تُعرض في أداة الاختيار وتُستخدم للمطابقة.
`key`	صيغة مختصرة من الاسم ملائمة لعناوين URL، تظل ثابتة عند تغيير الاسم.
`primary`	ما إذا كان يمكن استخدام الفئة بوصفها الفئة الفرعية الأساسية لموقع. اختر فقط العناصر التي تحمل القيمة `true` للحقل `subCategoryId`.

3. معرفة منصات النشر التي تشملها خطتك

تسرد GET /plan-sites كل منصة نشر مشمولة في خطتك مع قيمة رقمية لـ id، وقيمة لـ url، والبلدان التي تقبلها، والبلدان التي تلتزم فيها بـ hideAddress. هذه المعرّفات هي القيم الصالحة الوحيدة لـ enabledSiteIds عند الإنشاء وsubmissionDisabledSiteIds عند التحديث. صفِّ القائمة حسب بلد الموقع لكي تعرض فقط منصات النشر التي ستقبله.

Plan sites

curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.planSites[] | select(.supportedCountries | index("US")) | {id, name, url}'

JSON

{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 2,        "name": "Yelp",        "url": "yelp.com",        "supportedCountries": ["US", "CA", "GB", "DE", "FR"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "GB"]      }    ]  }}

اقتُطعت كلتا مصفوفتَي البلدان هنا؛ وقد تتضمن الاستجابة الفعلية 50 رمزًا أو أكثر لكل منصة نشر. بالنسبة إلى نشاط تجاري يخدم منطقة محددة، تحقّق أيضًا من hideAddressSupportedCountries، فقد ترفض منصة نشر إدراج نشاط تجاري دون عنوان شارع حتى لو كانت تقبل البلد.

4. تخزين نتائج البحث هذه مؤقتًا

نادرًا ما تتغير الكتالوجات الثلاثة، ولا يُقسَّم أي منها إلى صفحات، لذا اجلب كلًا منها مرة واحدة عند بدء التشغيل، واحتفظ به في الذاكرة أو في جدول صغير، وحدّثه وفق جدول زمني. استدعاؤها أثناء كل عملية إنشاء يستهلك من حد معدل الطلبات دون إرجاع بيانات جديدة؛ وفي خطة Launch، يستهلك ذلك 3 من أصل 10 طلبات متاحة لك في الدقيقة.

الكتالوج	الحجم	وقت التحديث
البلدان	عشرات البلدان ومئات الولايات	نادرًا. التحديث اليومي أكثر من كافٍ.
الفئات الفرعية	نحو 6,000 عنصر	يوميًا، أو عند فشل عملية إنشاء بسبب قيمة غير معروفة لـ `subCategoryId`.
منصات النشر المشمولة في الخطة	عشرات منصات النشر	عند تغيير الخطة، لأن القائمة تقتصر على ما تشمله خطتك.

أنشئ خريطة تربط name بأحرف صغيرة بـ databaseId للفئات الفرعية، وخريطة تربط countryIso بـ states للبلدان. تحقّق من صحة العنوان بالرجوع إلى البيانات المخزنة مؤقتًا قبل استدعاء عملية الإنشاء، لكي يكتشف تطبيقك قيمة غير مدعومة لـ countryIso (SY10036) أو غياب city (SY10126) قبل إرسال الطلب.

الخطوات التالية

إضافة موقع: استخدم subCategoryId وcountryIso ومعرّفات منصات النشر التي بحثت عنها للتو.
تحديث موقع: غيّر الفئات أو استبعد منصات النشر باستخدام submissionDisabledSiteIds.
عرض قائمة البلدان والولايات المدعومة، وعرض قائمة الفئات الفرعية، وعرض قائمة مواقع الخطة: الصفحات المرجعية.