POST/api/v4/locations

Criar um local

Cria um novo local comercial na sua conta e o coloca na fila para envio de listagens.

Requer uma chave de API. Consulte Autenticação para ver o formato do cabeçalho e a rotação de chaves.

Parâmetros

Corpo

Um campo aninhado marcado como obrigatório só se aplica quando você envia o campo pai. Se o campo pai for opcional e você o omitir, os campos filhos obrigatórios não se aplicam.

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

Exemplo de requisição

Corpo pronto para colar. Substitua os IDs e valores de exemplo pelos seus.

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

Respostas

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.

Cria um novo local comercial. Em caso de sucesso, o local é colocado na fila para envio a todas as plataformas de publicação do seu plano (ou, quando enabledSiteIds é fornecido, apenas àqueles sites). Campos obrigatórios: name, um description com pelo menos 200 caracteres, subCategoryId, countryIso e, para países com endereçamento em nível de cidade, city. Um local também precisa de um endereço válido e um telefone válido para que a publicação possa ocorrer; forneça esses dados no momento da criação para evitar uma atualização posterior.

O id retornado é codificado em base64 (e.g. TG9jYXRpb246MTgwMDI5MA==); decodifique-o para revelar o formato interno Location:<databaseId>. Todas as chamadas subsequentes fazem referência a esse id em base64.

Caso de uso: cadastrar um único estabelecimento com horários de funcionamento. Envie o endereço, phone, subCategoryId e um array businessHours, com uma entrada por dia da semana contendo intervalos type: "OPEN" e { start, end }, ou type: "CLOSED" com um array slots vazio para os dias em que o estabelecimento fica fechado. Armazene sua própria chave em storeId para que você possa encontrar o local posteriormente por meio de consulta por códigos de loja sem precisar manter o ID da Listings API.

Horários especiais exigem horários regulares. Os horários especiais (substituições para feriados ou eventos, enviados como entradas businessHours com day: "SPECIAL", type: "OPEN" ou "CLOSED" e um specialDate no formato YYYY-MM-DD) só são publicados quando o local também tem seus horários regulares de MONDAY–SUNDAY; o Google rejeita um local enviado com horários especiais, mas sem horários regulares. Sempre inclua a semana completa de sete dias em businessHours ao definir entradas SPECIAL; consulte as regras de horários do endpoint de atualização para ver o modelo completo.

Caso de uso: publicar em um subconjunto de sites. Passe enabledSiteIds (IDs de sites obtidos no endpoint plan-sites) para publicar o local em um subconjunto selecionado de diretórios em vez de em todos os diretórios do plano, o padrão que as agências usam para vender cobertura de sites em diferentes níveis.

Configure os botões de ação do Google no momento da criação. Passe placeActionLinks para definir os botões de ação do Google para o local (agendar um horário, fazer um pedido online e assim por diante) na mesma chamada. Os valores válidos de placeActionType são APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT e SHOP_ONLINE, com no máximo um link preferencial por tipo. Logo após a criação, name e submissionStatus de cada link têm o valor null até que o link seja sincronizado com o Google. Para adicionar, editar ou remover links posteriormente, use atualizar um local; consulte o guia de links de ação do local para ver o modelo completo.

Erros comuns (retornados como 400, com detalhes em errors[]): description deve ter pelo menos 200 caracteres (SY10005), countryIso deve ser um país compatível (SY10036), city é obrigatório para países com endereçamento em nível de cidade (SY10126), o estado deve ser um código ISO válido, o código postal e o telefone devem ser válidos para o país, subCategoryId deve existir e storeId deve ser único em toda a conta. Todas as requisições consomem a mesma quantidade do seu limite de requisições, independentemente do endpoint, portanto o cadastro em grande volume aciona um 429 apenas pela contagem de requisições; respeite o cabeçalho Retry-After e crie os locais sequencialmente, em vez de enviar uma rajada de requisições.

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