Foto

Aggiungi logo, copertina e foto della galleria a una sede, segna con una stella l’immagine principale ed elimina file obsoleti con l’SDK listingsapi-js.

Le foto vengono associate a una sede tramite un URL pubblico: tu ospiti l'immagine, la piattaforma la recupera e la memorizza, e le piattaforme di pubblicazione la prelevano da lì. Una sede conserva un logo, una copertina e un numero qualsiasi di foto aggiuntive, di cui al massimo 4 possono essere contrassegnate con una stella. Tutti i metodi per le foto sono disponibili sull'istanza del client ListingsAPI e operano nell'ambito di un ID sede. Gli ID numerici delle sedi vengono codificati automaticamente, quindi 1800289 e 'TG9jYXRpb246MTgwMDI4OQ==' sono intercambiabili.

I caricamenti possono riuscire in due modi. Un piccolo gruppo di immagini viene memorizzato immediatamente e la risposta contiene i file multimediali elaborati; un gruppo grande viene invece messo in coda e ricevi un ID richiesta da usare per verificare periodicamente lo stato. Scegli il percorso da seguire in base alla presenza di request.requestId, anziché contare le immagini.

fetchLocationPhotos

Elenca tutti i file multimediali associati a una sede: logo, copertina e immagini aggiuntive. Chiamalo prima di un caricamento per vedere cosa manca e raccogliere gli ID delle foto accettati dai metodi per contrassegnare con una stella e rimuovere le foto.

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

Parametri

Restituisce l'array mediaFilesOfLocation, con un array vuoto come valore predefinito. Ogni file contiene id, url, thumbnailUrl, categoryName (Logo, Cover o Additional), categoryId, fileType, starred e viewsCount. Una sede senza file multimediali restituisce un array vuoto, che è la risposta normale per una sede appena creata e non un errore.

addLocationPhotos

Associa una o più immagini a una sede. Ogni elemento richiede un URL JPEG o PNG accessibile pubblicamente in photo e la posizione che occupa in 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);}}

Opzioni delle foto

Parametri

Restituisce il payload addLocationPhotos: success, photos, request, errors e clientMutationId. In un caricamento elaborato immediatamente, photos contiene i nuovi file multimediali, ciascuno con id, databaseId, url, thumbnailUrl, type e starred, mentre request è un oggetto vuoto. In un caricamento messo in coda, photos è vuoto e request.requestId è impostato. Entrambi i casi indicano un esito positivo.

Le immagini devono essere in formato JPEG o PNG e le regole sulle dimensioni delle piattaforme di pubblicazione si applicano a ciascuna posizione. Una sede conserva un solo logo e una sola copertina, quindi caricare di nuovo uno dei due sostituisce l'immagine esistente. Imposta type con attenzione: ADDITIONAL è la destinazione delle immagini della galleria.

fetchPhotoUploadStatus

Verifica periodicamente lo stato di un caricamento in coda finché non raggiunge uno stato definitivo. Usa il valore request.requestId restituito da 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);}}

Parametri

Il payload contiene requestId, un valore status del processo pari a PROCESSING, SUCCESS o ERROR e un array photos i cui elementi contengono ciascuno mediaId, locationId, un proprio valore status e un valore errorMessage.

Il valore status del processo indica che l'elaborazione è terminata, non che tutte le immagini siano state caricate. Un processo SUCCESS può comunque contenere foto rifiutate, quindi, quando esce dallo stato PROCESSING, scorri photos e leggi ogni elemento. Attendi qualche secondo tra una verifica e l'altra: un ciclo senza pause porta rapidamente a raggiungere il limite di frequenza delle richieste. Verifica solo gli ID di un caricamento recente, perché un ID scaduto non raggiunge mai uno stato definitivo.

starLocationPhotos

Contrassegna le foto aggiuntive con una stella affinché abbiano una posizione prioritaria sulle piattaforme di pubblicazione che supportano le immagini in evidenza, oppure rimuovi la stella 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);

Parametri

Restituisce il payload starUnstarLocationPhotos: success, photos e un singolo oggetto error anziché un array errors. Ogni foto restituita contiene id, databaseId, url, thumbnailUrl, type e il nuovo valore di starred.

Solo le foto ADDITIONAL possono essere contrassegnate con una stella; il logo e la copertina sono già immagini principali. Una sede può avere al massimo 4 foto contrassegnate con una stella e il controllo conta quelle già contrassegnate più quelle incluse nella chiamata, quindi il superamento del limite di 4 fa fallire l'intera richiesta.

removeLocationPhotos

Rimuove l'associazione delle foto a una sede tramite i loro ID. Usalo per rimuovere immagini obsolete dalla galleria o annullare un'importazione errata.

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

Parametri

Restituisce il payload removeLocationPhotos: removedCount, errors e clientMutationId. Un valore removedCount pari a 0 con errors pari a null indica che nessuno degli ID inviati era associato a quella sede, permettendoti di individuare gli ID già rimossi.

Con questo metodo puoi rimuovere solo le foto ADDITIONAL. Per sostituire un logo o una copertina, caricane invece uno nuovo. La rimozione di un file multimediale ne elimina l'associazione alla sede; non elimina necessariamente il file dalla raccolta multimediale dell'account.

Aggiornamento tipico della galleria

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');}

Risorse correlate

• Sedi, cerca gli ID delle sedi
• Gestione degli errori, errori tipizzati generati da ogni metodo
• Carica un logo, una copertina e delle foto, la guida completa
• Riferimento REST: recupera foto, carica foto, stato del caricamento in blocco, contrassegna foto con una stella, rimuovi foto