Locais

Liste, crie, atualize, arquive, pesquise e consulte locais via client.locations.

Todos os métodos de locais estão em client.locations. Instale o SDK e configure sua chave antes de usá-los; consulte Instalação e Início rápido.

IDs de locais

Os métodos que recebem um location_id aceitam um ID numérico (16808) ou seu equivalente codificado em base64 ("TG9jYXRpb246MTY4MDg="). O SDK codifica os IDs numéricos automaticamente, portanto, as duas formas são intercambiáveis:

Python

# These are equivalentclient.locations.retrieve(16808)client.locations.retrieve("TG9jYXRpb246MTY4MDg=")

`locations.add`

Crie um local em uma única chamada, passando cada campo obrigatório como argumento nomeado. Essa é a forma recomendada de criar locais. O SDK valida no cliente os requisitos de criação da API e lança ValidationError antes de qualquer chamada de rede, de modo que um payload inválido causa uma falha imediata com uma mensagem clara.

Python

client.locations.add(    *,    name: str,    description: str,    sub_category_id: int,    country_iso: str,    city: str | None = None,    street: str | None = None,    state_iso: str | None = None,    postal_code: str | None = None,    phone: str | None = None,    website: str | None = None,    store_id: str | None = None,    hide_address: bool | None = None,    business_hours: list[dict] | None = None,    service_area: dict | None = None,    place_action_links: list[dict] | None = None,    enabled_site_ids: list[int] | None = None,    additional_fields: dict | None = None,) -> APIObject

Argumento	Tipo	Descrição
`name`	`str`	Nome da empresa, de 2 a 150 caracteres. Obrigatório.
`description`	`str`	Descrição da empresa, com no mínimo 200 caracteres. As plataformas de publicação a usam como texto principal da listagem. Obrigatória.
`sub_category_id`	`int`	ID da subcategoria principal. Use `client.subcategories()` para obter IDs válidos. Obrigatório.
`country_iso`	`str`	Código ISO de duas letras do país. Use `client.countries()` para obter os países compatíveis. Obrigatório.
`city`	`str`	Cidade. Obrigatória para países cujo endereçamento inclui a cidade; omita apenas para empresas que atendem em uma área de serviço com `hide_address=True`.
`street`	`str`	Endereço.
`state_iso`	`str`	Código ISO do estado ou da região.
`postal_code`	`str`	Código postal ou CEP.
`phone`	`str`	Número de telefone principal, validado de acordo com o país.
`website`	`str`	URL do site da empresa.
`store_id`	`str`	Seu código exclusivo da loja; deve ser único em toda a conta.
`hide_address`	`bool`	Ocultar o endereço (empresas que atendem em uma área de serviço).
`business_hours`	`list[dict]`	Horários semanais, e.g. `[{"day": "MONDAY", "slots": [...]}]`.
`service_area`	`dict`	Configuração da área de serviço: `{businessType, regionCode, placeInfos}`.
`place_action_links`	`list[dict]`	Links de ação do Google, e.g. `[{"placeActionType": "APPOINTMENT", "uri": "https://...", "isPreferred": True}]`.
`enabled_site_ids`	`list[int]`	IDs dos sites em que este local será publicado, quando você quiser usar apenas parte dos sites do seu plano. Use `client.plan_sites()` para obter os IDs.
`additional_fields`	`dict`	Campos extras de camelCase incorporados ao payload sem alterações.

A validação no cliente verifica: name com 2 a 150 caracteres, description com pelo menos 200 caracteres, sub_category_id e country_iso presentes e city presente, exceto quando hide_address=True.

O valor retornado é o payload de criação: .location contém o novo local. Você nunca precisa verificar indicadores de sucesso; o SDK lança ValidationError quando a API rejeita o payload.

Python

result = client.locations.add(  name="Acme Dental",  description=(      "Acme Dental is a family-owned dental practice offering general, "      "cosmetic, and pediatric dentistry in the heart of New York. Our "      "team provides cleanings, fillings, crowns, whitening, and same-day "      "emergency care in a modern, comfortable office with weekend hours "      "and easy online booking for new and returning patients."  ),  sub_category_id=1432,  country_iso="US",  city="New York",  street="123 Jump Street",  state_iso="NY",  postal_code="10013",  phone="6443859313",  website="https://acmedental.example.com",  store_id="NYC-001",  place_action_links=[      {"placeActionType": "APPOINTMENT", "uri": "https://acmedental.example.com/book", "isPreferred": True},  ],  enabled_site_ids=[1, 24, 87],)print("Created:", result.location.id, result.location.name)

`locations.list`

Liste locais com paginação baseada em cursor. Retorna um SyncPage.

Python

client.locations.list(    *,    first: int | None = None,    after: str | None = None,    before: str | None = None,    last: int | None = None,) -> SyncPage

Python

# First page of 25page = client.locations.list(first=25)for loc in page:  print(loc.name, loc.city) # Next page manuallyif page.has_more:  page2 = page.next_page() # Auto-paginate all locationsfor loc in client.locations.list(first=100).auto_paging_iter():  print(loc.name)

`locations.retrieve`

Obtenha um único local pelo ID. Lança NotFoundError se o ID não existir.

Python

client.locations.retrieve(location_id: str | int) -> APIObject

Python

loc = client.locations.retrieve(16808)print(loc.name, loc.street, loc.city)

`locations.list_by_ids`

Busque vários locais usando uma lista de IDs (numéricos ou em base64) em uma única chamada.

Python

client.locations.list_by_ids(location_ids: list[str | int]) -> list[APIObject]

Python

locs = client.locations.list_by_ids([16808, 16809, "TG9jYXRpb246MTQwMjQ="])for loc in locs:  print(loc.id, loc.name)

`locations.list_by_store_codes`

Busque locais que correspondam aos códigos de loja informados.

Python

client.locations.list_by_store_codes(store_codes: list[str]) -> list[APIObject]

Python

locs = client.locations.list_by_store_codes(["SF-001", "NYC-042"])for loc in locs:  print(loc.storeId, loc.name)

`locations.search`

Pesquise locais por palavra-chave no nome, no endereço ou no ID da loja. Retorna um SyncPage.

Python

client.locations.search(    query: str,    *,    fields: list[str] | None = None,    first: int | None = None,    after: str | None = None,    before: str | None = None,    last: int | None = None,) -> SyncPage

Python

# Search all fieldspage = client.locations.search("downtown dental", first=10) # Restrict to name onlypage = client.locations.search("Acme Dental", fields=["name"], first=10) for loc in page:  print(loc.name, loc.city)

`locations.create`

Crie um local a partir de um dict de entrada bruto com nomes de campos em camelCase. Prefira locations.add para usar argumentos nomeados e validação no cliente; use create quando você já tiver um payload camelCase.

Python

client.locations.create(input: dict) -> APIObject

Exigidos pela API: name, description (mínimo de 200 caracteres), subCategoryId, countryIso e city (para países cujo endereçamento inclui a cidade).

Python

result = client.locations.create({  "name": "Acme Dental Brooklyn",  "description": (      "Acme Dental Brooklyn is a family-owned dental practice offering "      "general, cosmetic, and pediatric dentistry. Our team provides "      "cleanings, fillings, crowns, whitening, and same-day emergency "      "care in a modern, comfortable office with weekend hours and easy "      "online booking for new and returning patients across Brooklyn."  ),  "subCategoryId": 1432,  "countryIso": "US",  "city": "Brooklyn",  "street": "88 Court St",  "stateIso": "NY",  "postalCode": "11201",  "phone": "6443859314",  "storeId": "NYC-002",})print("Created:", result.location.id)

`locations.update`

Atualize um local. Passe id e os campos que deseja alterar (camelCase). O id pode ser numérico ou estar em base64; o SDK o codifica automaticamente.

Python

client.locations.update(input: dict) -> APIObject

Python

result = client.locations.update({  "id": 16808,  "phone": "6443859399",  "street": "125 Jump Street",})print("Updated:", result.location.id)

`locations.archive`

Arquive um ou mais locais.

Python

client.locations.archive(location_ids: list[str | int]) -> APIObject

Python

result = client.locations.archive([16808, 16809])print(result.to_dict())

`locations.cancel_archive`

Cancele um arquivamento agendado.

Python

client.locations.cancel_archive(    location_ids: list[str | int],    selection_type: str,    changed_by: str,) -> APIObject

Python

client.locations.cancel_archive(  [16808],  selection_type="manual",  changed_by="admin@example.com",)

Veja também

Publicações: publique anúncios, eventos e ofertas
Listagens: verifique o status de sincronização por local
Avaliações: liste e responda a avaliações
Análises: análises de perfis do Google, Bing e Facebook