Fotos

Añade logo, portada y fotos de galería a una ubicación, marca con estrella la imagen principal y elimina archivos obsoletos con el SDK listingsapi-js.

Las fotos se adjuntan a una ubicación mediante una URL pública: tú alojas la imagen, la plataforma la descarga y la almacena, y las plataformas de publicación la obtienen desde allí. Una ubicación conserva un logotipo, una portada y cualquier número de fotos adicionales, de las cuales se pueden marcar como destacadas un máximo de cuatro. Todos los métodos de fotos están disponibles en la instancia del cliente ListingsAPI y se limitan a un ID de ubicación. Los ID numéricos de ubicación se codifican automáticamente, por lo que 1800289 y 'TG9jYXRpb246MTgwMDI4OQ==' son intercambiables.

Las cargas pueden completarse correctamente de dos formas. Un lote pequeño se almacena durante la propia solicitud y devuelve los archivos multimedia ya procesados; un lote grande se pone en cola y recibes un ID de solicitud para consultar su estado periódicamente. Elige cómo continuar en función de si request.requestId está presente, en lugar de contar tus propias imágenes.

fetchLocationPhotos

Enumera todos los archivos multimedia adjuntos a una ubicación: logotipo, portada e imágenes adicionales. Llama a este método antes de una carga para ver qué falta y recopilar los ID de foto que aceptan los métodos para marcar como destacadas y eliminar.

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

Parámetros

Devuelve el array mediaFilesOfLocation al resolverse, con un array vacío como valor predeterminado. Cada archivo incluye id, url, thumbnailUrl, categoryName (Logo, Cover o Additional), categoryId, fileType, starred y viewsCount. Una ubicación sin archivos multimedia devuelve un array vacío, que es la respuesta normal para una ubicación recién creada y no un error.

addLocationPhotos

Adjunta una o más imágenes a una ubicación. Cada elemento necesita una URL de una imagen JPEG o PNG accesible públicamente en photo, además de la categoría que ocupa en 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);}}

Opciones de las fotos

Parámetros

Devuelve el contenido de addLocationPhotos al resolverse: success, photos, request, errors y clientMutationId. En una carga procesada durante la propia solicitud, photos contiene los nuevos archivos multimedia con los valores de id, databaseId, url, thumbnailUrl, type y starred de cada uno, y request es un objeto vacío. En una carga puesta en cola, photos está vacío y request.requestId tiene un valor asignado. Ambos casos indican que la solicitud se ha completado correctamente.

Las imágenes deben ser JPEG o PNG, y las reglas de tamaño de las plataformas de publicación se aplican a cada categoría. Una ubicación conserva un único logotipo y una única portada, por lo que volver a cargar cualquiera de ellos sustituye la imagen existente. Elige el valor de type de forma explícita: ADDITIONAL es la categoría que corresponde a las imágenes de la galería.

fetchPhotoUploadStatus

Consulta periódicamente el estado de una carga puesta en cola hasta que finalice. Usa el request.requestId que devolvió 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

El contenido de la respuesta incluye requestId, un status del trabajo con el valor PROCESSING, SUCCESS o ERROR, y un array photos cuyas entradas contienen, cada una, mediaId, locationId, su propio status y un errorMessage.

El status del trabajo indica que el procesamiento ha terminado, no que todas las imágenes se hayan almacenado. Un trabajo SUCCESS aún puede contener fotos rechazadas, así que, una vez que salga de PROCESSING, recorre photos y lee cada entrada. Espera unos segundos entre consultas: un bucle sin pausas puede hacer que alcances rápidamente el límite de solicitudes. Consulta únicamente los ID de una carga reciente, porque uno caducado nunca llega a un estado final.

starLocationPhotos

Marca las fotos adicionales como destacadas para que tengan prioridad de aparición en las plataformas de publicación que admiten imágenes destacadas, o quítales esa marca pasando 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

Devuelve el contenido de starUnstarLocationPhotos al resolverse: success, photos y un único objeto error en lugar de un array errors. Cada foto devuelta incluye id, databaseId, url, thumbnailUrl, type y su nuevo valor de starred.

Solo las fotos ADDITIONAL se pueden marcar como destacadas; el logotipo y la portada ya son imágenes principales. Una ubicación puede tener como máximo cuatro fotos destacadas, y la comprobación cuenta las que ya están marcadas más las de tu llamada, por lo que superar cuatro hace que falle toda la solicitud.

removeLocationPhotos

Desvincula fotos de una ubicación mediante sus ID. Usa este método para retirar imágenes obsoletas de la galería o deshacer una importación incorrecta.

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

Parámetros

Devuelve el contenido de removeLocationPhotos al resolverse: removedCount, errors y clientMutationId. Un valor de cero en removedCount con errors en null significa que ninguno de los ID que enviaste estaba vinculado a esa ubicación, lo que permite detectar los ID que ya se habían desvinculado.

Aquí solo se pueden eliminar las fotos ADDITIONAL. Para sustituir un logotipo o una portada, carga uno nuevo. Eliminar un archivo multimedia lo desvincula de la ubicación; no necesariamente borra el archivo de la biblioteca multimedia de la cuenta.

Actualización habitual de la galería

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

• Ubicaciones, consulta los ID de las ubicaciones
• Gestión de errores, errores tipados que lanza cada método
• Sube un logotipo, una portada y fotos, la guía completa paso a paso
• Referencia REST: obtener fotos, subir fotos, estado de la carga masiva, marcar fotos como destacadas, eliminar fotos