Listings APIListings API
تسجيل الدخول

تحديث تفاصيل موقع وساعات عمله

عدّل بيانات الاتصال، وانشر جدولًا أسبوعيًا كاملًا باستثناءات لمرة واحدة، وحدّد إغلاقًا مؤقتًا، واضبط فئات Google، واسترجع التغييرات.

يُجري POST /locations/update تحديثًا جزئيًا. تُدرَج جميع الحقول ضمن input، ويكون input.id الحقل الوحيد المطلوب، وتحتفظ الحقول التي تغفلها بقيمها الحالية. يغيّر كل قسم أدناه جسم طلب JSON فقط.

1. تحديث رقم الهاتف والموقع الإلكتروني

أرسل id مع الحقول التي تريد تغييرها. تنشر منصات النشر bizUrl بوصفه عنوان URL للموقع الإلكتروني. تقبل locations.update() في Python SDK كائن dict بمفاتيح camelCase، وتقبل updateLocation() في Node SDK الكائن نفسه.

Phone and website
curl -X POST https://listingsapi.com/api/v4/locations/update \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "phone": "5125550199",    "bizUrl": "https://acmekitchen.example.com"  }}'
JSON
{  "data": {    "updateLocation": {      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "name": "Jenny Home",        "phone": "5125550199",        "status": "APPROVED"      }    }  }}

حتى عند فشل التحقق من الصحة، يُرجَع رمز حالة HTTP 200، مع success: false والسبب في data.updateLocation.errors، لذا تحقّق من success بدلًا من رمز الحالة. تثير كلتا حزمتَي SDK الاستثناء ValidationError في هذه الحالة.

2. ضبط ساعات العمل الأسبوعية

businessHours مصفوفة تحتوي على عنصر واحد لكل يوم من أيام الأسبوع. أرسل دائمًا العناصر السبعة جميعها، وحدّد يوم الإغلاق باستخدام type: "CLOSED" ومصفوفة slots فارغة بدلًا من إغفاله. يجب ألا تتداخل الفترات الزمنية ضمن اليوم الواحد.

الحقلالقيمملاحظات
dayمن MONDAY إلى SUNDAY، أو SPECIALSPECIAL تعديل استثنائي لمرة واحدة للتاريخ المحدّد في specialDate.
typeOPEN أو CLOSEDاستخدم CLOSED مع slots: [] ليوم لا يعمل فيه النشاط التجاري.
slots[].start, slots[].end09:00am, 05:00pmأوقات بتنسيق 12 ساعة مع am أو pm. يُسمح بعدة فترات في اليوم الواحد لورديات العمل المنقسمة.
specialDateYYYY-MM-DDفقط ضمن عنصر SPECIAL، يُرسَل إلى جانب عناصر أيام الأسبوع السبعة، ولا يحلّ محلها أبدًا.
moreHours[]hoursTypeId, moreHour[]جداول ثانوية مثل التوصيل أو خدمة الطلبات من السيارة. يستخدم moreHour البنية نفسها المكوّنة من day وtype وslots، ولا يتضمن specialDate.
Weekly hours
curl -X POST https://listingsapi.com/api/v4/locations/update \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "businessHours": [      { "day": "MONDAY",    "type": "OPEN",   "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "TUESDAY",   "type": "OPEN",   "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN",   "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "THURSDAY",  "type": "OPEN",   "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "FRIDAY",    "type": "OPEN",   "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "SATURDAY",  "type": "OPEN",   "slots": [{ "start": "10:00am", "end": "02:00pm" }] },      { "day": "SUNDAY",    "type": "CLOSED", "slots": [] }    ]  }}'

لعطلة، أضف عنصر SPECIAL إلى المصفوفة نفسها. يحلّ هذا العنصر محلّ الجدول المعتاد لذلك التاريخ وحده ويترك النمط الأسبوعي كما هو:

JSON
{ "day": "SPECIAL", "type": "CLOSED", "specialDate": "2026-12-25", "slots": [] }

3. تحديد إغلاق مؤقت أو إخفاء العنوان

يحدّد temporarilyClosed: true النشاط التجاري على أنه مغلق ويوقف نشر ساعات عمله. اضبطه على false لإعادة الفتح. لنشاط تجاري يخدم منطقة محدّدة، اضبط hideAddress: true: تحتفظ ListingsAPI بالعنوان ضمن بيانات الموقع، لكنها لا ترسله إلى منصات النشر.

Temporary closure
curl -X POST https://listingsapi.com/api/v4/locations/update \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "id": "TG9jYXRpb246MTgwMDI4OQ==", "temporarilyClosed": true } }'

4. ضبط فئات Google

لدى Google Business Profile نظام تصنيف خاص به للفئات، منفصل عن subCategoryId الرقمي. يقبل primaryGbpSiteCategoryId معرّف GCID مثل gcid:restaurant، ويقبل additionalGbpSiteCategoryIds معرّفات إضافية منه. تُحدَّد الفئات لكليهما بالرجوع إلى countryIso، لذا أرسل البلد في الاستدعاء نفسه.

Google categories
curl -X POST https://listingsapi.com/api/v4/locations/update \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "countryIso": "US",    "primaryGbpSiteCategoryId": "gcid:restaurant",    "additionalGbpSiteCategoryIds": ["gcid:pizza_restaurant", "gcid:italian_restaurant"]  }}'

لا تخلط بين هذه الحقول وadditionalCategoryIds، الذي يقبل قيم databaseId الصحيحة من نقطة نهاية الفئات الفرعية. راجع البحث عن البلدان والولايات والفئات.

5. استرجاع بيانات الموقع للتحقق منها

يُرجع GET /locations-by-ids السجل الكامل لمعرّف واحد أو أكثر مُرمَّز بصيغة base64، وتُمرَّر هذه المعرّفات كمصفوفة JSON في معامل الاستعلام ids. قارن phone وbusinessHours وtemporarilyClosed بما أرسلته.

Verify
curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ=="]' \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getLocationsByIds": [      {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "name": "Jenny Home",        "phone": "5125550199",        "hideAddress": false,        "temporarilyClosed": true      }    ]  }}

تُحذَف المعرّفات غير الموجودة في حسابك من المصفوفة دون حدوث خطأ، لذا قارن عدد النتائج المُرجَعة بعدد المعرّفات التي طلبتها.

إذا كانت webhooks مُهيَّأة، يُطلَق حدث profile.updated. يُحدّ تكرار تسليمه إلى مرة واحدة لكل موقع كل 60 ثانية، ويحدث التسليم في بداية هذه الفترة: تُدمَج التعديلات اللاحقة ضمن تلك الفترة، ويصف changed_fields فقط التعديل الذي بدأها. استرجع بيانات الموقع عند وصول الحدث، ثم مرة أخرى بعد انتهاء الفترة.

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