POST/api/v4/locations

Einen Standort erstellen

Erstellt einen neuen Unternehmensstandort in Ihrem Konto und stellt ihn zur Einreichung von Einträgen in die Warteschlange.

Erfordert einen API-Schlüssel. Format des Headers und Schlüsselrotation finden Sie unter Authentifizierung.

Parameter

Body

Ein als erforderlich markiertes verschachteltes Feld gilt nur, wenn Sie das übergeordnete Feld senden. Ist das übergeordnete Feld optional und lassen Sie es weg, gelten seine erforderlichen Unterfelder nicht.

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

Beispielanfrage

Body zum direkten Einfügen. Ersetzen Sie Platzhalter-IDs und -Werte durch Ihre eigenen.

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

Antworten

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.

Erstellt einen neuen Unternehmensstandort. Bei Erfolg wird der Standort zur Einreichung bei jeder Plattform seines Tarifs in die Warteschlange gestellt (oder nur bei den angegebenen Websites, wenn enabledSiteIds übergeben wird). Pflichtfelder: name, eine description mit mindestens 200 Zeichen, subCategoryId, countryIso und, für Länder mit Adressierung auf Stadtebene, city. Ein Standort benötigt außerdem eine gültige Straßenadresse und Telefonnummer, bevor er tatsächlich veröffentlicht werden kann; geben Sie diese bereits beim Erstellen an, um eine nachträgliche Aktualisierung zu vermeiden.

Die zurückgegebene id ist base64-kodiert (e.g. TG9jYXRpb246MTgwMDI5MA==); dekodieren Sie sie, um die interne Form Location:<databaseId> zu erhalten. Jeder nachfolgende Aufruf referenziert diese base64-kodierte id.

Anwendungsfall: Ein einzelnes Ladengeschäft mit Öffnungszeiten anlegen. Senden Sie die Adresse, phone, subCategoryId und ein businessHours-Array mit einem Eintrag pro Wochentag mit Zeitfenstern für type: "OPEN" und { start, end } oder mit type: "CLOSED" und einem leeren slots-Array für geschlossene Tage. Speichern Sie Ihren eigenen Schlüssel in storeId, damit Sie den Standort später über Abruf anhand von Filialcodes ermitteln können, ohne die ID der Listings API nachhalten zu müssen.

Sonderöffnungszeiten erfordern reguläre Öffnungszeiten. Sonderöffnungszeiten (abweichende Zeiten für Feiertage oder Veranstaltungen, die als businessHours-Einträge mit day: "SPECIAL", type: "OPEN" oder "CLOSED" sowie einer specialDate im Format YYYY-MM-DD gesendet werden) werden nur veröffentlicht, wenn für den Standort auch der reguläre Zeitplan für MONDAY–SUNDAY hinterlegt ist; Google lehnt einen Standort ab, der mit Sonderöffnungszeiten, aber ohne reguläre Öffnungszeiten eingereicht wird. Geben Sie immer die vollständige siebentägige businessHours-Woche an, wenn Sie SPECIAL-Einträge festlegen; das vollständige Modell finden Sie in den Regeln für Öffnungszeiten des Update-Endpunkts.

Anwendungsfall: Auf einer Teilmenge von Websites veröffentlichen. Übergeben Sie enabledSiteIds (Website-IDs vom plan-sites-Endpunkt), um den Standort in einer gezielt ausgewählten Teilmenge von Verzeichnissen statt im gesamten Tarif zu veröffentlichen; dieses Vorgehen nutzen Agenturen, um gestaffelte Pakete für die Abdeckung von Websites anzubieten.

Google-Aktionsschaltflächen bereits beim Erstellen einrichten. Übergeben Sie placeActionLinks, um die Google-Aktionsschaltflächen des Standorts (Termin buchen, online bestellen usw.) im selben Aufruf festzulegen. Gültige Werte für placeActionType sind APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT und SHOP_ONLINE, wobei pro Typ höchstens ein bevorzugter Link zulässig ist. Unmittelbar nach dem Erstellen haben name und submissionStatus jedes Links den Wert null, bis der Link mit Google synchronisiert ist. Um Links später hinzuzufügen, zu bearbeiten oder zu entfernen, verwenden Sie Einen Standort aktualisieren; das vollständige Modell finden Sie im Leitfaden zu Place Action Links.

Häufige Fehler (zurückgegeben als 400 mit Details in errors[]): description muss mindestens 200 Zeichen lang sein (SY10005), countryIso muss ein unterstütztes Land sein (SY10036), city ist für Länder mit Adressierung auf Stadtebene erforderlich (SY10126), state muss ein gültiger ISO-Code sein, Postleitzahl und Telefonnummer müssen für das Land gültig sein, subCategoryId muss existieren und storeId muss innerhalb des gesamten Kontos eindeutig sein. Jede Anfrage wird unabhängig vom Endpunkt im gleichen Umfang auf Ihr Anfragelimit angerechnet, sodass das Anlegen großer Mengen allein durch die Anzahl der Anfragen einen 429 auslöst; beachten Sie den Retry-After-Header und erstellen Sie Standorte nacheinander statt in einem Schub.

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