POST/api/v4/locations

Créer un établissement

Crée un nouvel établissement dans votre compte et le place dans la file d’attente pour la soumission de ses fiches.

Nécessite une clé API. Consultez Authentification pour le format de l’en-tête et la rotation des clés.

Paramètres

Corps

Un champ imbriqué marqué comme obligatoire ne s’applique que si vous envoyez son parent. Si le parent est facultatif et que vous l’omettez, ses champs enfants obligatoires ne s’appliquent pas.

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

Exemple de requête

Corps prêt à coller. Remplacez les identifiants et valeurs d’exemple par les vôtres.

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

Réponses

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.

Crée un nouvel établissement. En cas de succès, l’établissement est placé dans la file d’attente pour soumission à chaque plateforme de publication de son forfait (ou, lorsque enabledSiteIds est fourni, uniquement aux sites indiqués). Champs obligatoires : name, un description d’au moins 200 caractères, subCategoryId, countryIso et, pour les pays dont le système d’adressage exige une ville, city. Un établissement doit également disposer d’une adresse postale et d’un numéro de téléphone valides avant de pouvoir être publié ; fournissez-les lors de la création pour éviter une mise à jour ultérieure.

Le id renvoyé est encodé en base64 (e.g. TG9jYXRpb246MTgwMDI5MA==) ; décodez-le pour obtenir sa forme interne Location:<databaseId>. Chaque appel ultérieur fait référence à ce id en base64.

Cas d’utilisation : intégrer un seul point de vente avec ses horaires. Envoyez l’adresse, phone, subCategoryId et un tableau businessHours contenant une entrée par jour de la semaine avec des créneaux type: "OPEN" et { start, end }, ou type: "CLOSED" avec un tableau slots vide pour les jours de fermeture. Enregistrez votre propre clé dans storeId afin de pouvoir retrouver l’établissement ultérieurement via la récupération par codes de magasin sans avoir à conserver l’identifiant de Listings API.

Les horaires exceptionnels nécessitent des horaires habituels. Les horaires exceptionnels (dérogations pour les jours fériés ou les événements, envoyées sous forme d’entrées businessHours avec day: "SPECIAL", type: "OPEN" ou "CLOSED", et un specialDate au format YYYY-MM-DD) ne sont publiés que si l’établissement dispose également de ses horaires habituels MONDAY–SUNDAY ; Google rejette un établissement soumis avec des horaires exceptionnels mais sans horaires habituels. Incluez toujours la semaine businessHours complète de sept jours lorsque vous définissez des entrées SPECIAL ; consultez les règles relatives aux horaires du point de terminaison de mise à jour pour connaître le modèle complet.

Cas d’utilisation : publier sur un sous-ensemble de sites. Transmettez enabledSiteIds (les identifiants de sites provenant du point de terminaison plan-sites) pour publier l’établissement sur une sélection d’annuaires plutôt que sur tous ceux du forfait ; c’est la méthode utilisée par les agences pour proposer différents niveaux de couverture des sites.

Initialisez les boutons d’action Google lors de la création. Transmettez placeActionLinks pour définir les boutons d’action Google de l’établissement (prendre rendez-vous, commander en ligne, etc.) dans le même appel. Les valeurs valides de placeActionType sont APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT et SHOP_ONLINE, avec au maximum un lien préféré par type. Juste après la création, les champs name et submissionStatus de chaque lien valent null jusqu’à ce que le lien soit synchronisé avec Google. Pour ajouter, modifier ou supprimer des liens ultérieurement, utilisez Mettre à jour un établissement ; consultez le guide Place Action Links pour connaître le modèle complet.

Erreurs courantes (renvoyées sous la forme 400 avec les détails dans errors[]) : description doit comporter au moins 200 caractères (SY10005), countryIso doit être un pays pris en charge (SY10036), city est obligatoire pour les pays dont le système d’adressage exige une ville (SY10126), state doit être un code ISO valide, le code postal et le numéro de téléphone doivent être valides pour le pays, subCategoryId doit exister et storeId doit être unique dans l’ensemble du compte. Chaque requête est décomptée de la même manière de votre limite de débit, quel que soit le point de terminaison ; l’intégration d’un grand nombre d’établissements déclenche donc un 429 sur la seule base du nombre de requêtes ; respectez l’en-tête Retry-After et créez les établissements de manière séquentielle plutôt qu’en rafale.

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