POST/api/v4/locations

Konum oluşturma

Hesabınızda yeni bir işletme konumu oluşturur ve işletme kaydı gönderimi için sıraya alır.

API anahtarı gerektirir. Başlık biçimi ve anahtar yenileme için Kimlik doğrulama bölümüne bakın.

Parametreler

Gövde

Zorunlu olarak işaretlenen iç içe bir alan yalnızca üst alanını gönderdiğinizde geçerlidir. Üst alan isteğe bağlıysa ve onu göndermezseniz, zorunlu alt alanları da geçerli olmaz.

Ad	Tür	Zorunlu	Açıklama
input.name	string	zorunlu	Name of the business.
input.description	string	zorunlu	Business description, minimum 200 characters (`SY10005` when missing or shorter). Publishers use it as the primary listing copy.
input.storeId	string	isteğe bağlı	Unique store code. Must be unique across the account.
input.street	string	zorunlu	Street address, 5 to 100 characters (`SY10011`).
input.city	string	zorunlu	City. Required where the country's `hasCity` is `true` (`SY10126`). Where it is `false`, a city you send is dropped.
input.stateIso	string	zorunlu	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	isteğe bağlı	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	zorunlu	Country ISO code. Must be a supported country (`SY10036`). See the countries and states endpoint for valid values.
input.phone	string	zorunlu	Primary phone number, validated for the country (`SY10015`).
input.subCategoryId	integer	zorunlu	Primary subcategory ID. Pick a valid ID from the subcategories list endpoint.
input.bizUrl	string	zorunlu	Business website URL. Published to directories as the location's website. Some publishers refuse a listing without one.
input.primaryGbpSiteCategoryId	string	isteğe bağlı	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	isteğe bağlı	Additional Google Business Profile categories, as GCIDs. Also resolved against `countryIso`.
input.offeringsUrl	string	isteğe bağlı	URL of the menu, catalogue, or service list.
input.bookingUrl	string	isteğe bağlı	URL customers use to book an appointment.
input.reservationUrl	string	isteğe bağlı	URL customers use to make a reservation.
input.street1	string	isteğe bağlı	Second address line (suite, unit, floor).
input.latitude	string	isteğe bağlı	Latitude of the location, as a string. Send with `longitude`; publishers use it when the address alone is ambiguous.
input.longitude	string	isteğe bağlı	Longitude of the location, as a string. Send with `latitude`.
input.ownerEmail	string	isteğe bağlı	Email of the location owner. Used for listing claims and verification, not for login.
input.ownerName	string	isteğe bağlı	Name of the location owner.
input.facebookUrl	string	isteğe bağlı	URL of the location's Facebook page.
input.twitterUrl	string	isteğe bağlı	URL of the location's X (Twitter) profile.
input.linkedinUrl	string	isteğe bağlı	URL of the location's LinkedIn page.
input.instagramUrl	string	isteğe bağlı	URL of the location's Instagram profile.
input.youtubeUrl	string	isteğe bağlı	URL of the location's YouTube channel.
input.tiktokUrl	string	isteğe bağlı	URL of the location's TikTok profile.
input.pinterestUrl	string	isteğe bağlı	URL of the location's Pinterest profile.
input.tagline	string	isteğe bağlı	Short tagline for the business.
input.yearOfIncorporation	string	isteğe bağlı	Year the business was incorporated, e.g. `2014`.
input.googleAdsPhone	string	isteğe bağlı	Alternate phone shown on Google Ads location extensions instead of `phone`.
input.additionalPhones	array of strings	isteğe bağlı	Secondary phone numbers submitted to Google Business Profile.
input.videos	array of strings	isteğe bağlı	Video URLs for the location.
input.additionalCategoryIds	array of integers	isteğe bağlı	Secondary Listings API subcategory IDs, from the subcategories endpoint. Distinct from `additionalGbpSiteCategoryIds`, which takes Google GCIDs.
input.submissionDisabledSiteIds	array of integers	isteğe bağlı	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	isteğe bağlı	Set `true` for a service-area business. ListingsAPI stores the address you send but does not submit it to publishers.
input.temporarilyClosed	boolean	isteğe bağlı	Set `true` to stop publishing business hours while the location is temporarily closed.
input.serviceItems	array of objects	isteğe bağlı	Services offered, published to Google Business Profile.
input.customAttributes	array of objects	isteğe bağlı	Publisher-specific attributes for the location.
input.paymentMethods	array of strings	isteğe bağlı	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	isteğe bağlı	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	zorunlu	MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY, or SPECIAL (a one-off override for the date in `specialDate`).
input.businessHours[].type	string	zorunlu	`OPEN` or `CLOSED`.
input.businessHours[].specialDate	string	isteğe bağlı	Date of a one-off override, as `YYYY-MM-DD`. Set this only when `day` is `SPECIAL`.
input.businessHours[].slots	array of objects	isteğe bağlı	Open intervals for the day, each `{ start, end }`. Omit or leave empty when `type` is `CLOSED`.
input.businessHours[].slots[].start	string	zorunlu	Opening time, e.g. `09:00am`.
input.businessHours[].slots[].end	string	zorunlu	Closing time, e.g. `05:00pm`.
input.serviceArea	object	isteğe bağlı	Service-area definition for service-area businesses: `{ businessType, regionCode, placeInfos: [{ placeId, placeName }] }`.
input.placeActionLinks	array of objects	isteğe bağlı	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	isteğe bağlı	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	isteğe bağlı	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.

Örnek istek

Yapıştırmaya hazır gövde. Yer tutucu kimlikleri ve değerleri kendi değerlerinizle değiştirin.

Request body

{  "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" }    ]  }}

Yanıtlar

200Location created successfully. Returns the new location as a summary object.

Response

{  "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.

Yeni bir işletme konumu oluşturur. Başarılı olduğunda konum, planındaki tüm yayın platformlarına (veya enabledSiteIds sağlandığında yalnızca belirtilen sitelere) gönderilmek üzere sıraya alınır. Zorunlu alanlar: name, en az 200 karakter uzunluğunda bir description, subCategoryId, countryIso ve şehir düzeyinde adresleme kullanan ülkeler için city. Bir konumun yayımlanabilmesi için geçerli bir sokak adresi ve telefon numarası da gerekir; daha sonra güncelleme yapmanız gerekmemesi için bunları oluşturma sırasında sağlayın.

Döndürülen id base64 ile kodlanmıştır (e.g. TG9jYXRpb246MTgwMDI5MA==); dahili Location:<databaseId> biçimini görmek için kodunu çözün. Sonraki tüm çağrılar bu base64 id değerini referans alır.

Kullanım senaryosu: tek bir mağazayı çalışma saatleriyle birlikte sisteme ekleme. Adresi, phone, subCategoryId ve haftanın her günü için type: "OPEN" ve { start, end } zaman aralıklarını içeren bir kayıt veya kapalı günler için boş bir slots dizisiyle birlikte type: "CLOSED" içeren bir businessHours dizisi gönderin. Daha sonra Listings API kimliğini takip etmeden mağaza kodlarına göre getirme yoluyla konumu bulabilmek için kendi anahtarınızı storeId içinde saklayın.

Özel çalışma saatleri için normal çalışma saatleri gereklidir. Özel çalışma saatleri (day: "SPECIAL", type: "OPEN" veya "CLOSED" ve YYYY-MM-DD biçiminde bir specialDate içeren businessHours kayıtları olarak gönderilen, tatil veya etkinlik nedeniyle normal saatlerin yerine geçen saatler), yalnızca konumun normal MONDAY–SUNDAY programı da mevcutsa yayımlanır; Google, özel çalışma saatleriyle gönderilen ancak normal çalışma saatleri bulunmayan bir konumu reddeder. SPECIAL kayıtlarını her ayarladığınızda yedi günün tamamını kapsayan businessHours haftasını ekleyin; modelin tamamı için güncelleme uç noktasının çalışma saatleri kurallarına bakın.

Kullanım senaryosu: sitelerin bir alt kümesinde yayımlama. Konumu planın tamamı yerine seçilmiş bir dizin alt kümesinde yayımlamak için enabledSiteIds (plan-sites uç noktasından alınan site kimlikleri) gönderin; ajanslar, kademeli site kapsamı satmak için bu yöntemi kullanır.

Google işlem düğmelerini oluşturma sırasında ayarlayın. Aynı çağrıda konumun Google işlem düğmelerini (randevu alma, çevrimiçi sipariş verme vb.) ayarlamak için placeActionLinks gönderin. Geçerli placeActionType değerleri APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT ve SHOP_ONLINE olup her tür için en fazla bir tercih edilen bağlantı bulunabilir. Oluşturmanın hemen ardından, her bağlantının name ve submissionStatus değerleri, bağlantı Google ile senkronize edilene kadar null olur. Daha sonra bağlantı eklemek, düzenlemek veya kaldırmak için konum güncelleme uç noktasını kullanın; modelin tamamı için Yer İşlem Bağlantıları kılavuzuna bakın.

Yaygın hatalar (ayrıntılar errors[] içinde olmak üzere 400 olarak döndürülür): description en az 200 karakter olmalıdır (SY10005), countryIso desteklenen bir ülke olmalıdır (SY10036), şehir düzeyinde adresleme kullanan ülkelerde city zorunludur (SY10126), state geçerli bir ISO kodu olmalıdır, posta kodu ve telefon numarası ülke için geçerli olmalıdır, subCategoryId mevcut olmalıdır ve storeId hesap genelinde benzersiz olmalıdır. Uç noktadan bağımsız olarak her istek istek hızı limitinizden aynı miktarda tüketir; bu nedenle yüksek hacimli konum ekleme işlemleri yalnızca istek sayısı nedeniyle bile 429 hatasını tetikler; Retry-After başlığına uyun ve konumları kısa sürede topluca oluşturmak yerine sırayla oluşturun.

Request

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"        }      ]    }  }'

Run in playground