POST/api/v4/locations/update

تحديث موقع

يحدّث الحقول القابلة للكتابة في موقع موجود. لا تتغير إلا الحقول التي ترسلها.

يتطلب مفتاح API. راجع المصادقة لمعرفة تنسيق الترويسة وتدوير المفاتيح.

المعلمات

النص الأساسي

ينطبق الحقل المتداخل المحدد على أنه مطلوب فقط عند إرسال الحقل الأصل. إذا كان الحقل الأصل اختياريًا وحذفته، فلا تنطبق حقوله الفرعية المطلوبة.

الاسم	النوع	مطلوب	الوصف
input.id	string	مطلوب	The location's Base64-encoded Relay ID to update.
input.name	string	اختياري	Business name.
input.street	string	اختياري	Street address.
input.city	string	اختياري	City.
input.stateIso	string	اختياري	State/region ISO code.
input.postalCode	string	اختياري	Postal or ZIP code.
input.countryIso	string	اختياري	Two-letter country ISO code.
input.phone	string	اختياري	Primary phone number.
input.bizUrl	string	اختياري	Business website URL. Published to directories as the location's website.
input.primaryGbpSiteCategoryId	string	اختياري	Primary Google Business Profile category, as a GCID (e.g. `gcid:restaurant`). Resolved against `countryIso`, so send the two together.
input.additionalGbpSiteCategoryIds	array of strings	اختياري	Additional Google Business Profile categories, as GCIDs. Also resolved against `countryIso`.
input.offeringsUrl	string	اختياري	URL of the menu, catalogue, or service list.
input.bookingUrl	string	اختياري	URL customers use to book an appointment.
input.reservationUrl	string	اختياري	URL customers use to make a reservation.
input.street1	string	اختياري	Second address line (suite, unit, floor).
input.latitude	string	اختياري	Latitude of the location, as a string. Send with `longitude`; publishers use it when the address alone is ambiguous.
input.longitude	string	اختياري	Longitude of the location, as a string. Send with `latitude`.
input.ownerEmail	string	اختياري	Email of the location owner. Used for listing claims and verification, not for login.
input.ownerName	string	اختياري	Name of the location owner.
input.facebookUrl	string	اختياري	URL of the location's Facebook page.
input.twitterUrl	string	اختياري	URL of the location's X (Twitter) profile.
input.linkedinUrl	string	اختياري	URL of the location's LinkedIn page.
input.instagramUrl	string	اختياري	URL of the location's Instagram profile.
input.youtubeUrl	string	اختياري	URL of the location's YouTube channel.
input.tiktokUrl	string	اختياري	URL of the location's TikTok profile.
input.pinterestUrl	string	اختياري	URL of the location's Pinterest profile.
input.tagline	string	اختياري	Short tagline for the business.
input.description	string	اختياري	Business description. Published to Google Business Profile as the business description.
input.yearOfIncorporation	string	اختياري	Year the business was incorporated, e.g. `2014`.
input.googleAdsPhone	string	اختياري	Alternate phone shown on Google Ads location extensions instead of `phone`.
input.additionalPhones	array of strings	اختياري	Secondary phone numbers submitted to Google Business Profile.
input.videos	array of strings	اختياري	Video URLs for the location.
input.additionalCategoryIds	array of integers	اختياري	Secondary Listings API subcategory IDs, from the subcategories endpoint. Distinct from `additionalGbpSiteCategoryIds`, which takes Google GCIDs.
input.subCategoryId	integer	اختياري	Primary subcategory ID. Pick a valid ID from the subcategories list endpoint.
input.storeId	string	اختياري	Unique store code. Must be unique across the account.
input.enabledSiteIds	array of integers	اختياري	Site IDs to publish this location to, when you want a subset of your plan's sites. See the plan-sites endpoint for valid IDs. Omit to publish to every site in your plan.
input.updateOnlySiteIds	array of integers	اختياري	Restrict this update to the given site IDs. Other sites keep their current published values.
input.contentPreferredLanguage	string	اختياري	Preferred language for the location's published content, e.g. `ENGLISH`.
input.submissionDisabledSiteIds	array of integers	اختياري	Site IDs to exclude from submission. The inverse of `enabledSiteIds`, useful when you want every site in your plan except a few.
input.hideAddress	boolean	اختياري	Set `true` for a service-area business. ListingsAPI stores the address you send but does not submit it to publishers.
input.temporarilyClosed	boolean	اختياري	Set `true` to stop publishing business hours while the location is temporarily closed.
input.serviceItems	array of objects	اختياري	Services offered, published to Google Business Profile.
input.paymentMethods	array of strings	اختياري	Payment methods accepted. One or more of `VISA`, `MASTERCARD`, `AMEX`, `CASH`, `CHEQUE`, `CRYPTO`, `DINERS_CLUB`, `DISCOVER`, `FINANCING`, `INVOICE`, `TRAVELERS_CHECK`, `APPLE_PAY`, `SAMSUNG_PAY`, `PAYPAL`, `ANDROID_PAY`.
input.businessHours	array of objects	اختياري	Hours. Each entry is `{ day, type, slots }`, plus `specialDate` for a `SPECIAL` entry. Send the full seven-day week when you set hours.
input.businessHours[].day	string	مطلوب	One of MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY, or SPECIAL (a one-off override for the date in `specialDate`).
input.businessHours[].type	string	مطلوب	`OPEN` or `CLOSED`.
input.businessHours[].specialDate	string	اختياري	Date of a one-off override, as `YYYY-MM-DD`. Set this only when `day` is `SPECIAL`.
input.businessHours[].slots	array of objects	اختياري	Open intervals for the day, each `{ start, end }` (e.g. `09:00am`, `05:00pm`). Use an empty array when `type` is `CLOSED`.
input.businessHours[].slots[].start	string	مطلوب	Opening time for the interval, e.g. `09:00am`.
input.businessHours[].slots[].end	string	مطلوب	Closing time for the interval, e.g. `05:00pm`.
input.moreHours	array of objects	اختياري	Additional hour sets (e.g. delivery, drive-through). Each entry is `{ hoursTypeId, moreHour }`, where `moreHour` is an array of `{ day, type, slots }` using the same shape as `businessHours` (minus `specialDate`).
input.serviceArea	object	اختياري	Service-area business config: `businessType`, `regionCode`, and a `placeInfos` array of `{ placeId, placeName }`.
input.customAttributes	array of objects	اختياري	Custom attribute values for the location. Each item is `{ slug, value }`, where `slug` identifies a custom attribute registered on your account and `value` is an array of strings. Sending a slug that is not registered returns `SY10035`. Registering a new custom attribute is not yet available through the API.
input.placeActionLinks	array of objects	اختياري	Google action links (ordering, delivery, takeout, reservation, appointment). Each item: `placeActionType` (enum), `uri` (string), optional `isPreferred` (boolean), optional `action` (`add`, the default, or `delete`), optional `name` (the link identifier returned by read endpoints once synced to Google). Only the links you reference are affected; links you don't include are left unchanged. See the Place Action Links guide.

مثال على الطلب

نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.

Request body

{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "phone": "5125550199",    "bizUrl": "https://acmekitchen.example.com",    "primaryGbpSiteCategoryId": "gcid:restaurant",    "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": [] }    ]  }}

الاستجابات

200Location updated. `success` is true and the updated location summary is returned.

Response

{  "data": {    "updateLocation": {      "clientMutationId": null,      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "name": "Jenny Home",        "street": "600 Congress Ave, Suite 200",        "city": "Austin",        "stateIso": "TX",        "countryIso": "US",        "postalCode": "78701",        "phone": "5125550199",        "storeId": null,        "status": "APPROVED",        "placeActionLinks": [          { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "name": null, "submissionStatus": null }        ],        "discoveredPlaceActionLinks": []      }    }  }}

401Unauthenticated, missing or invalid API key.

يحدّث موقعًا واحدًا. لا تُعدَّل إلا الحقول الموجودة في input؛ ويحتفظ كل حقل تحذفه من الطلب بقيمته الحالية. الحقل id هو الحقل المطلوب الوحيد.

حالة استخدام: تصحيح رقم هاتف. أرسل id وphone فقط لتصحيح بيانات الاتصال دون المساس بالعنوان أو ساعات العمل. تُرجع الاستجابة الموقع المحدَّث حتى تتمكن من التأكد من حفظ القيم الجديدة.

حالة استخدام: نشر جدول أسبوعي كامل. أرسل مصفوفة businessHours التي تشمل الأيام السبعة (كما في نموذج الطلب) لتحديد فترات العمل لكل يوم. ميّز أيام الإغلاق باستخدام { "day": "SUNDAY", "type": "CLOSED", "slots": [] }.

قواعد ساعات العمل.

قدّم الأيام السبعة كلها؛ إذ يُرفض الأسبوع غير المكتمل.
تستخدم الأوقات start/end داخل كل عنصر من عناصر slots (مثل 09:00am و05:00pm)؛ ويجب ألا تتداخل الفترات ضمن اليوم الواحد.
تُرسَل التعديلات الاستثنائية الخاصة بالعطلات والفعاليات كعناصر إضافية تحتوي على day: "SPECIAL" وspecialDate (YYYY-MM-DD)، إلى جانب عناصر أيام الأسبوع السبعة، ولا تحلّ محلّها أبدًا.
استخدم SPECIAL في businessHours فقط. لا تحتوي عناصر moreHours على حقل specialDate، لذا فإن يومًا من نوع SPECIAL فيها لا يحمل تاريخًا.
استخدم moreHours للجداول الثانوية (التوصيل، الخدمة من السيارة)، مع استخدام hoursTypeId مفتاحًا لها.

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

نقاط يجب الانتباه إليها.

حقل المعرّف هو id (معرّف Relay المرمّز بصيغة Base64 الذي تُرجعه كل نقطة نهاية للقراءة).
عند فشل التحقق من الصحة، يظل الاستدعاء يُرجع HTTP 200 مع success: false ومصفوفة errors تحتوي على عناصر؛ لذا تحقّق دائمًا من success، وليس من رمز الحالة وحده.

روابط إجراءات الأماكن

يدير placeActionLinks أزرار الإجراءات الخاصة بموقع على Google (الطلب، التوصيل، استلام الطلبات، الحجز، حجز موعد). نموذج الكتابة هو append/upsert (إضافة أو تحديث)، وليس الاستبدال:

action: "add" (الافتراضي): يضيف رابطًا جديدًا، أو يحدّث uri/isPreferred لرابط محفوظ في موضعه.
action: "delete": يزيل رابطًا محفوظًا ويضع طلب إزالته من Google في قائمة الانتظار.
الروابط التي لا تشير إليها في الطلب تبقى دون تغيير؛ فإغفال رابط لا يؤدي إلى إزالته أبدًا.

كيفية مطابقة الرابط (للتعديل/الحذف): باستخدام name إذا كان موجودًا، وإلا فباستخدام placeActionType + uri. أدرج name (من نقطة نهاية للقراءة) عندما يكون متاحًا لديك للحصول على أدق مطابقة؛ فالرابط الذي لم يُزامَن مع Google بعد لا يحتوي على name، ويُطابَق باستخدام placeActionType + uri.

القيم الصالحة لـ placeActionType: APPOINTMENT، ONLINE_APPOINTMENT، DINING_RESERVATION، FOOD_ORDERING، FOOD_DELIVERY، FOOD_TAKEOUT، SHOP_ONLINE. يُسمح بـ رابط مفضّل واحد لكل نوع كحد أقصى.

تغيير عنوان URL لرابط = إزالة القديم + إضافة الجديد في الطلب نفسه:

JSON

{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "placeActionLinks": [      { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com",     "name": "<link-name-if-synced>", "action": "delete" },      { "placeActionType": "FOOD_ORDERING", "uri": "https://new-order.example.com", "isPreferred": true, "action": "add" }    ]  }}

مباشرةً بعد عملية كتابة، تكون قيمة كل من name وsubmissionStatus للرابط هي null؛ وتُملأ قيمتاهما بمجرد مزامنة الرابط مع Google. راجع دليل روابط إجراءات الأماكن للاطلاع على سير العمل كاملًا، بما في ذلك كيفية ظهور الروابط المكتشفة مباشرةً على Google ضمن discoveredPlaceActionLinks.

Request

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",      "primaryGbpSiteCategoryId": "gcid:restaurant",      "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": []        }      ]    }  }'

Run in playground