/api/v4/locationsإنشاء موقع
ينشئ موقعًا جديدًا لنشاط تجاري في حسابك ويضعه في قائمة الانتظار لإرسال إدراج النشاط التجاري.
المعلمات
النص الأساسي
ينطبق الحقل المتداخل المحدد على أنه مطلوب فقط عند إرسال الحقل الأصل. إذا كان الحقل الأصل اختياريًا وحذفته، فلا تنطبق حقوله الفرعية المطلوبة.
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| input.name | string | مطلوب | Name of the business. |
| input.description | string | مطلوب | Business description, minimum 200 characters (`SY10005` when missing or shorter). Publishers use it as the primary listing copy. |
| input.storeId | string | اختياري | Unique store code. Must be unique across the account. |
| input.street | string | مطلوب | Street address, 5 to 100 characters (`SY10011`). |
| input.city | string | مطلوب | City. Required where the country's `hasCity` is `true` (`SY10126`). Where it is `false`, a city you send is dropped. |
| input.stateIso | string | مطلوب | State ISO code. Required where the country's `stateRequired` is `true`, and must be one of that country's `states` (`SY10010`). Leave it out where `stateRequired` is `false`. See the countries and states endpoint for valid values. |
| input.postalCode | string | اختياري | Postal code. Optional, but send it wherever the country's `hasPostalCode` is `true`. A value you send must match the country's format (`SY10014`). |
| input.countryIso | string | مطلوب | Country ISO code. Must be a supported country (`SY10036`). See the countries and states endpoint for valid values. |
| input.phone | string | مطلوب | Primary phone number, validated for the country (`SY10015`). |
| input.subCategoryId | integer | مطلوب | Primary subcategory ID. Pick a valid ID from the subcategories list endpoint. |
| input.bizUrl | string | مطلوب | Business website URL. Published to directories as the location's website. Some publishers refuse a listing without one. |
| 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.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.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.customAttributes | array of objects | اختياري | Publisher-specific attributes for the location. |
| 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 | اختياري | Opening hours. Each entry is `{ day, type, slots }`, plus `specialDate` for a `SPECIAL` entry: `day` is an uppercase weekday enum (MONDAY–SUNDAY) or `SPECIAL`, `type` is `OPEN` or `CLOSED`, and `slots` is an array of `{ start, end }` time strings (e.g. `09:00am`, `05:00pm`). For a closed day use `type: "CLOSED"` with an empty `slots` array. |
| input.businessHours[].day | string | مطلوب | 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 }`. Omit or leave empty when `type` is `CLOSED`. |
| input.businessHours[].slots[].start | string | مطلوب | Opening time, e.g. `09:00am`. |
| input.businessHours[].slots[].end | string | مطلوب | Closing time, e.g. `05:00pm`. |
| input.serviceArea | object | اختياري | Service-area definition for service-area businesses: `{ businessType, regionCode, placeInfos: [{ placeId, placeName }] }`. |
| input.placeActionLinks | array of objects | اختياري | Google action links (ordering, delivery, takeout, reservation, appointment). Each item: `placeActionType` (enum), `uri` (string), optional `isPreferred` (boolean). On create every link is new, so no `action` is needed. See the Place Action Links guide. |
| 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.clientMutationId | string | اختياري | Optional correlation token returned unchanged in the response. It does not prevent duplicate writes: the server does not detect repeated calls that reuse the same value. |
مثال على الطلب
نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.
{ "input": { "name": "Acme Kitchen", "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby growers. Our dining room seats forty, takeout and delivery run until close, and the bar pours regional wine and beer on tap.", "storeId": "ACME01", "street": "123 Jump Street", "city": "New York", "stateIso": "NY", "postalCode": "10013", "countryIso": "US", "phone": "6443859313", "bizUrl": "https://acmekitchen.example.com", "subCategoryId": 1432, "primaryGbpSiteCategoryId": "gcid:restaurant", "additionalGbpSiteCategoryIds": ["gcid:pizza_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": [] } ], "placeActionLinks": [ { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true }, { "placeActionType": "FOOD_TAKEOUT", "uri": "https://takeout.acmekitchen.example.com" } ] }}الاستجابات
200Location created successfully. Returns the new location as a summary object.
{ "data": { "createLocation": { "clientMutationId": null, "success": true, "errors": null, "location": { "id": "TG9jYXRpb246MTgwMDI5MA==", "databaseId": 1800290, "storeId": "ACME01", "name": "Acme Kitchen", "street": "123 Jump Street", "city": "New York", "stateIso": "NY", "postalCode": "10013", "countryIso": "US", "phone": "6443859313", "status": "PENDING", "primaryGbpSiteCategoryId": null, "placeActionLinks": [ { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true, "name": null, "submissionStatus": null }, { "placeActionType": "FOOD_TAKEOUT", "uri": "https://takeout.acmekitchen.example.com", "isPreferred": false, "name": null, "submissionStatus": null } ], "discoveredPlaceActionLinks": [] } } }}400Bad request, validation failure (see `errors[]`).
401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.
ينشئ موقعًا جديدًا لنشاط تجاري. عند النجاح، يُوضَع الموقع في قائمة الانتظار لإرساله إلى كل منصة نشر ضمن خطته (أو إلى المواقع الإلكترونية المحددة فقط عند توفير enabledSiteIds). الحقول المطلوبة: name، وdescription بطول لا يقل عن 200 حرف، وsubCategoryId، وcountryIso، وللبلدان التي تتضمن عناوينها تحديد المدينة، city. يحتاج الموقع أيضًا إلى عنوان شارع ورقم هاتف صالحين قبل أن يُنشَر فعليًا؛ لذا وفّرهما عند الإنشاء لتجنب الحاجة إلى تحديث لاحق.
تكون قيمة id المُعادة مرمّزة باستخدام base64 (مثل TG9jYXRpb246MTgwMDI5MA==)؛ فكّ ترميزها للكشف عن صيغة Location:<databaseId> الداخلية. يشير كل استدعاء لاحق إلى id هذا المرمّز باستخدام base64.
حالة استخدام: إضافة متجر واحد مع ساعات عمله. أرسل العنوان وphone وsubCategoryId ومصفوفة businessHours تحتوي على عنصر واحد لكل يوم من أيام الأسبوع مع type: "OPEN" وفترات { start, end }، أو type: "CLOSED" مع مصفوفة slots فارغة لأيام الإغلاق. خزّن مفتاحك الخاص في storeId لتتمكن لاحقًا من العثور على الموقع عبر الجلب باستخدام رموز المتاجر دون تتبّع معرّفه لدى Listings API.
تتطلب ساعات العمل الخاصة ساعات عمل اعتيادية. لا تُنشَر ساعات العمل الخاصة (الاستثناءات الخاصة بالعطلات أو الفعاليات، التي تُرسَل كعناصر businessHours تتضمن day: "SPECIAL" وtype: "OPEN" أو "CLOSED"، وspecialDate بصيغة YYYY-MM-DD) إلا عندما يتضمن الموقع أيضًا جدول ساعات عمله الاعتيادية من MONDAY إلى SUNDAY؛ ترفض Google الموقع المُرسَل بساعات عمل خاصة دون ساعات عمل اعتيادية. أدرج دائمًا أسبوع businessHours كاملًا بأيامه السبعة كلما عيّنت عناصر SPECIAL؛ راجع قواعد ساعات العمل لنقطة نهاية التحديث للاطلاع على النموذج الكامل.
حالة استخدام: النشر على مجموعة فرعية من المواقع الإلكترونية. مرّر enabledSiteIds (معرّفات المواقع الإلكترونية من نقطة نهاية plan-sites) لنشر الموقع على مجموعة فرعية منتقاة من الأدلة بدلًا من جميع الأدلة ضمن الخطة، وهو النمط الذي تستخدمه الوكالات لبيع تغطية متدرّجة للمواقع الإلكترونية.
إعداد أزرار الإجراءات في Google عند الإنشاء. مرّر placeActionLinks لتعيين أزرار إجراءات الموقع في Google (حجز موعد، والطلب عبر الإنترنت، وما إلى ذلك) في الاستدعاء نفسه. القيم الصالحة لـ placeActionType هي APPOINTMENT وONLINE_APPOINTMENT وDINING_RESERVATION وFOOD_ORDERING وFOOD_DELIVERY وFOOD_TAKEOUT وSHOP_ONLINE، مع رابط مفضّل واحد على الأكثر لكل نوع. مباشرةً بعد الإنشاء، تكون قيمتا name وsubmissionStatus لكل رابط هما null إلى أن يُزامَن مع Google. لإضافة الروابط أو تعديلها أو إزالتها لاحقًا، استخدم تحديث موقع؛ وراجع دليل روابط إجراءات الأماكن للاطلاع على النموذج الكامل.
الأخطاء الشائعة (تُعاد على هيئة 400 مع التفاصيل في errors[]): يجب ألا يقل طول description عن 200 حرف (SY10005)، ويجب أن يكون countryIso بلدًا مدعومًا (SY10036)، ويكون city إلزاميًا للبلدان التي تتضمن عناوينها تحديد المدينة (SY10126)، ويجب أن تكون قيمة state رمز ISO صالحًا، ويجب أن يكون الرمز البريدي ورقم الهاتف صالحين للبلد، ويجب أن يكون subCategoryId موجودًا، ويجب أن يكون storeId فريدًا على مستوى الحساب. يُحتسَب كل طلب بالمقدار نفسه ضمن حد معدل الطلبات بغض النظر عن نقطة النهاية، لذا تؤدي إضافة المواقع بأعداد كبيرة إلى تلقي 429 بسبب عدد الطلبات وحده؛ التزم بترويسة Retry-After وأنشئ المواقع بالتتابع بدلًا من إنشائها دفعة واحدة.
curl -X POST 'https://listingsapi.com/api/v4/locations' \ -H "Authorization: API $LISTINGSAPI_KEY" \ -H 'Content-Type: application/json' \ -d '{ "input": { "name": "Acme Kitchen", "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby growers. Our dining room seats forty, takeout and delivery run until close, and the bar pours regional wine and beer on tap.", "storeId": "ACME01", "street": "123 Jump Street", "city": "New York", "stateIso": "NY", "postalCode": "10013", "countryIso": "US", "phone": "6443859313", "bizUrl": "https://acmekitchen.example.com", "subCategoryId": 1432, "primaryGbpSiteCategoryId": "gcid:restaurant", "additionalGbpSiteCategoryIds": [ "gcid:pizza_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": [] } ], "placeActionLinks": [ { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true }, { "placeActionType": "FOOD_TAKEOUT", "uri": "https://takeout.acmekitchen.example.com" } ] } }'