Fotos

Anexe logotipo, capa e fotos da galeria a um local, marque a imagem principal com estrela e remova arquivos desatualizados com o SDK listingsapi-js.

As fotos são anexadas a um local por meio de uma URL pública: você hospeda a imagem, a plataforma a busca e armazena, e as plataformas de publicação a obtêm a partir daí. Um local mantém um logotipo, uma capa e qualquer quantidade de fotos adicionais, das quais no máximo 4 podem ser marcadas com estrela. Todos os métodos de fotos estão na instância do cliente ListingsAPI e têm escopo restrito a um ID de local. Os IDs numéricos de local são codificados automaticamente, portanto 1800289 e 'TG9jYXRpb246MTgwMDI4OQ==' são intercambiáveis.

Os envios têm 2 formas de sucesso. Um lote pequeno é armazenado na própria chamada, que retorna a mídia já processada; um lote grande é colocado na fila, e você recebe um ID de solicitação para consultar periodicamente. Escolha o fluxo com base na presença de request.requestId, em vez de contar suas próprias imagens.

fetchLocationPhotos

Liste todos os arquivos de mídia anexados a um local: logotipo, capa e imagens adicionais. Chame este método antes de um envio para verificar o que falta e coletar os IDs de fotos aceitos pelos métodos de marcação com estrela e remoção.

const photos = await client.fetchLocationPhotos(1800289); for (const p of photos) {console.log(p.id, p.categoryName, p.starred, p.url);}

Parâmetros

Retorna o array mediaFilesOfLocation, usando um array vazio como padrão. Cada arquivo contém id, url, thumbnailUrl, categoryName (Logo, Cover ou Additional), categoryId, fileType, starred e viewsCount. Um local sem mídia retorna um array vazio, que é a resposta normal para um local recém-criado, e não um erro.

addLocationPhotos

Anexe uma ou mais imagens a um local. Cada item precisa de uma URL de imagem JPEG ou PNG acessível publicamente em photo, além da posição que ocupa em type.

const result = await client.addLocationPhotos(1800289, [{ photo: 'https://cdn.example.com/brightsmile/logo.png', type: 'LOGO' },{ photo: 'https://cdn.example.com/brightsmile/storefront.jpg', type: 'ADDITIONAL' },]); if (result.request?.requestId) {// Queued: poll fetchPhotoUploadStatus with this idconsole.log('queued', result.request.requestId);} else {for (const p of result.photos ?? []) {  console.log('stored', p.id, p.type);}}

Opções de fotos

Parâmetros

Retorna o payload addLocationPhotos: success, photos, request, errors e clientMutationId. Em um envio processado na própria chamada, photos contém os novos itens de mídia com id, databaseId, url, thumbnailUrl, type e starred de cada um, e request é um objeto vazio. Em um envio colocado na fila, photos está vazio e request.requestId está definido. Ambos os casos indicam sucesso.

As imagens devem estar no formato JPEG ou PNG, e as regras de tamanho das plataformas de publicação se aplicam a cada posição. Um local mantém um único logotipo e uma única capa, portanto reenviar qualquer um deles substitui a imagem existente. Defina type com atenção: ADDITIONAL é a posição destinada às imagens da galeria.

fetchPhotoUploadStatus

Consulte periodicamente um envio colocado na fila até que ele chegue a um estado final. Use o request.requestId retornado por addLocationPhotos.

let job = await client.fetchPhotoUploadStatus('e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a'); while (job.status === 'PROCESSING') {await new Promise((resolve) => setTimeout(resolve, 5000));job = await client.fetchPhotoUploadStatus('e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a');} for (const p of job.photos ?? []) {if (p.status === 'ERROR') {  console.log('rejected:', p.errorMessage);}}

Parâmetros

O payload contém requestId, um status da tarefa com valor PROCESSING, SUCCESS ou ERROR e um array photos cujas entradas contêm, cada uma, mediaId, locationId, seu próprio status e um errorMessage.

O status da tarefa informa que o processamento terminou, não que todas as imagens foram armazenadas. Uma tarefa SUCCESS ainda pode conter fotos rejeitadas, portanto, assim que ela sair de PROCESSING, percorra photos e leia cada entrada. Aguarde alguns segundos entre as consultas: um loop sem intervalo pode fazer você atingir rapidamente o limite de requisições. Consulte apenas IDs de um envio recente, pois um ID expirado nunca chega a um estado final.

starLocationPhotos

Marque fotos adicionais com estrela para que elas tenham prioridade de exibição nas plataformas de publicação que oferecem suporte a imagens em destaque, ou remova a estrela passando false.

// Feature a photoconst result = await client.starLocationPhotos(1800289,['TWVkaWFGaWxlOjU4Nzg5MzI='],true,); console.log(result.success, result.photos[0].starred); // Reverse itawait client.starLocationPhotos(1800289, ['TWVkaWFGaWxlOjU4Nzg5MzI='], false);

Parâmetros

Retorna o payload starUnstarLocationPhotos: success, photos e um único objeto error, em vez de um array errors. Cada foto retornada contém id, databaseId, url, thumbnailUrl, type e seu novo valor de starred.

Somente fotos ADDITIONAL podem ser marcadas com estrela; o logotipo e a capa já são imagens principais. Um local pode ter no máximo 4 fotos marcadas com estrela, e a verificação conta as que já estão marcadas mais as incluídas na sua chamada, portanto ultrapassar 4 faz a solicitação inteira falhar.

removeLocationPhotos

Desvincule fotos de um local pelos IDs delas. Use este método para remover imagens desatualizadas da galeria ou desfazer uma importação incorreta.

const result = await client.removeLocationPhotos(1800289, ['TWVkaWFGaWxlOjU4Nzg5MzI=',]); console.log(result.removedCount); // 1

Parâmetros

Retorna o payload removeLocationPhotos: removedCount, errors e clientMutationId. Um removedCount igual a 0 com errors igual a null significa que nenhum dos IDs enviados estava vinculado àquele local, o que permite identificar IDs que já haviam sido removidos.

Somente fotos ADDITIONAL podem ser removidas aqui. Para substituir um logotipo ou uma capa, envie uma nova imagem. A remoção da mídia a desvincula do local; ela não necessariamente exclui o arquivo da biblioteca de mídia da conta.

Atualização típica da galeria

import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); // reads LISTINGSAPI_KEY from envconst LOCATION_ID = 1800289; // Brightsmile Dental // 1. See what is already attachedconst existing = await client.fetchLocationPhotos(LOCATION_ID);const hasLogo = existing.some((p) => p.categoryName === 'Logo'); // 2. Upload only what is missing, plus the new hero shotconst uploaded = await client.addLocationPhotos(LOCATION_ID, [...(hasLogo ? [] : [{ photo: 'https://cdn.example.com/brightsmile/logo.png', type: 'LOGO' as const }]),{ photo: 'https://cdn.example.com/brightsmile/hero-2026.jpg', type: 'ADDITIONAL' as const },]); // 3. Feature the new hero shotconst hero = (uploaded.photos ?? []).find((p) => p.type === 'ADDITIONAL');if (hero) {await client.starLocationPhotos(LOCATION_ID, [hero.id], true);} // 4. Retire last season's imagesconst stale = existing.filter((p) => p.categoryName === 'Additional' && !p.starred).map((p) => p.id);if (stale.length > 0) {const removed = await client.removeLocationPhotos(LOCATION_ID, stale);console.log('removed ' + removed.removedCount + ' stale photos');}

Recursos relacionados

• Locais, consulte os IDs dos locais
• Tratamento de erros, erros tipados lançados por todos os métodos
• Envie um logotipo, uma capa e fotos, o passo a passo completo
• Referência REST: obter fotos, enviar fotos, status do envio em lote, marcar fotos com estrela, remover fotos