Locais

Liste, pesquise, crie, atualize e arquive locais de empresas com o SDK listingsapi-js.

Os locais são a entidade central da Listings API: cada listagem, avaliação, registro de análise e publicação está associado a um local. Todos os métodos de locais estão na instância do cliente ListingsAPI.

fetchAllLocations

Lista os locais da conta com paginação baseada em cursor. Retorna um objeto com locations, pageInfo, success e o conteúdo raw da resposta da API. Com fetchAll: true, percorre as páginas automaticamente e retorna um Location[] sem aninhamento.

TypeScript

// Single pageconst page = await client.fetchAllLocations({ first: 25 });if (!Array.isArray(page)) {console.log(page.locations);  // Location[]console.log(page.pageInfo);   // { hasNextPage, hasPreviousPage, startCursor, endCursor, total? } // Next pageconst next = await client.fetchAllLocations({  first: 25,  after: page.pageInfo.endCursor!,});} // All pages at once, returns Location[]const all = await client.fetchAllLocations({ fetchAll: true, pageSize: 100 });

Opções

Parâmetro	Tipo	Descrição
`first`	`number`	Tamanho da página na paginação para a frente.
`after`	`string`	Cursor de um `pageInfo.endCursor` anterior.
`before`	`string`	Cursor para paginação para trás.
`last`	`number`	Tamanho da página na paginação para trás.
`fetchAll`	`boolean`	Percorre as páginas automaticamente e retorna um `Location[]` sem aninhamento.
`pageSize`	`number`	Tamanho da página usado internamente quando `fetchAll` é `true` (padrão: `100`).

fetchLocationsByIds

Obtém locais específicos por ID. Aceita IDs numéricos ou codificados em base64 e retorna um Location[] sem aninhamento. Um array de entrada vazio retorna [] sem fazer uma requisição.

TypeScript

const locations = await client.fetchLocationsByIds([16808, 16809, 'TG9jYXRpb246MTY4MTA=']);console.log(locations); // Location[]

fetchLocationsByStoreCodes

Obtém os locais que correspondem aos códigos de loja informados. Retorna um Location[] sem aninhamento; um array de entrada vazio retorna [] sem fazer uma requisição.

TypeScript

const locations = await client.fetchLocationsByStoreCodes(['AD-SF-001', 'AD-NY-001']);

searchLocations

Pesquisa locais por palavra-chave no nome, endereço e ID da loja. Retorna a mesma estrutura paginada de fetchAllLocations e oferece suporte a fetchAll da mesma forma.

TypeScript

// Single pageconst result = await client.searchLocations('Brooklyn', { first: 20 });if (!Array.isArray(result)) {console.log(result.locations, result.pageInfo);} // All matching results, returns Location[]const all = await client.searchLocations('Brooklyn', { fetchAll: true }); // Restrict which fields are searchedconst byName = await client.searchLocations('Acme Dental', { fields: ['name'] });

Opções

Todas as opções de paginação de fetchAllLocations, mais:

Parâmetro	Tipo	Descrição
`fields`	`string[]`	Restringe a pesquisa a campos específicos.

createLocation

Cria um novo local. A API exige name, um valor de description com pelo menos 200 caracteres, subCategoryId, countryIso e city. Retorna o conteúdo da resposta com o local criado; se a API rejeitar os dados de entrada, o cliente lança uma exceção ValidationError, portanto não há um indicador de sucesso a verificar.

TypeScript

const result = await client.createLocation({name: 'Acme Dental',description:  'Acme Dental is a family-owned dental practice offering cleanings, ' +  'checkups, fillings, crowns, and cosmetic dentistry for patients of all ' +  'ages. Our gentle, experienced team uses modern digital imaging and ' +  'same-day scheduling to make every visit fast and comfortable.',subCategoryId: 1432,countryIso: 'US',city: 'San Francisco',street: '2100 Mission St',stateIso: 'CA',postalCode: '94110',phone: '4155550100',storeId: 'AD-SF-003',});console.log(result.location.id);

updateLocation

Atualiza um ou mais campos de um local existente. Informe o id do local e os campos que você deseja alterar. Os IDs numéricos são codificados automaticamente.

TypeScript

await client.updateLocation({id: 16808,phone: '4155550199',name: 'Acme Dental Mission District',});

archiveLocations

Arquiva um ou mais locais. Os locais arquivados deixam de ser sincronizados com os diretórios.

TypeScript

await client.archiveLocations([16808, 16809]);

cancelArchiveLocations

Cancela o arquivamento agendado dos locais informados. Recebe os IDs dos locais, um selectionType e um identificador changedBy como argumentos posicionais.

TypeScript

await client.cancelArchiveLocations([16808],'manual',           // selectionType'ops@example.com',  // changedBy);

Codificação de IDs

Todos os métodos de locais aceitam um ID numérico ou um ID codificado em base64. O SDK codifica IDs numéricos (e strings numéricas) automaticamente usando o formato Location:<id>; os valores que já estão codificados são usados sem alteração.

TypeScript

// These are equivalentawait client.fetchLocationsByIds([16808]);await client.fetchLocationsByIds(['TG9jYXRpb246MTY4MDg=']);

O codificador também é exportado caso você precise obter a forma codificada diretamente:

TypeScript

import { encodeLocationId } from 'listingsapi-js'; encodeLocationId(16808);                  // 'TG9jYXRpb246MTY4MDg='encodeLocationId('16808');                // 'TG9jYXRpb246MTY4MDg='encodeLocationId('TG9jYXRpb246MTY4MDg='); // unchanged

Listagens, status de sincronização com diretórios por local
Avaliações, lista de avaliações e análises por local
Análises, dados do Google, Bing e Facebook por local