Fotos

Mit dem listingsapi-js SDK einem Standort Logo, Titelbild und Galeriefotos hinzufügen, das Hauptbild mit Stern markieren und veraltete Dateien entfernen.

Fotos werden einem Standort über eine öffentliche URL zugeordnet: Sie hosten das Bild, die Plattform ruft es ab und speichert es, und die weiteren Plattformen übernehmen es von dort. Ein Standort enthält ein Logo, ein Titelbild und beliebig viele zusätzliche Fotos, von denen höchstens vier mit einem Stern markiert sein können. Alle Fotomethoden sind auf der Client-Instanz ListingsAPI verfügbar und auf eine Standort-ID beschränkt. Numerische Standort-IDs werden automatisch codiert, sodass 1800289 und 'TG9jYXRpb246MTgwMDI4OQ==' austauschbar sind.

Erfolgreiche Uploads liefern zwei unterschiedliche Arten von Antworten. Eine kleine Gruppe von Bildern wird direkt gespeichert, und die Antwort enthält die fertig verarbeiteten Medien; eine große Gruppe wird dagegen in eine Warteschlange gestellt, und Sie erhalten eine Anfrage-ID zur Statusabfrage. Entscheiden Sie anhand dessen, ob request.requestId vorhanden ist, welchen Verarbeitungspfad Sie verwenden, statt Ihre Bilder selbst zu zählen.

fetchLocationPhotos

Listen Sie alle Mediendateien auf, die einem Standort zugeordnet sind: Logo, Titelbild und zusätzliche Bilder. Rufen Sie die Methode vor einem Upload auf, um festzustellen, was fehlt, und um die Foto-IDs zu ermitteln, die die Methoden zum Markieren mit einem Stern und zum Entfernen benötigen.

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

Parameter

Gibt das Array mediaFilesOfLocation zurück, standardmäßig ein leeres Array. Jede Datei enthält id, url, thumbnailUrl, categoryName (Logo, Cover oder Additional), categoryId, fileType, starred und viewsCount. Für einen Standort ohne Medien wird ein leeres Array zurückgegeben; dies ist die normale Antwort für einen neu erstellten Standort und kein Fehler.

addLocationPhotos

Ordnen Sie einem Standort ein oder mehrere Bilder zu. Jedes Element benötigt in photo eine öffentlich erreichbare URL zu einem JPEG- oder PNG-Bild und in type die Position, die es belegt.

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

Fotooptionen

Parameter

Gibt die Nutzdaten aus addLocationPhotos zurück: success, photos, request, errors und clientMutationId. Bei einem direkt verarbeiteten Upload enthält photos die neuen Medien mit den jeweiligen Werten für id, databaseId, url, thumbnailUrl, type und starred, und request ist ein leeres Objekt. Bei einem Upload in der Warteschlange ist photos leer und request.requestId gesetzt. Beide Fälle gelten als Erfolg.

Bilder müssen im JPEG- oder PNG-Format vorliegen, und die Größenvorgaben der Plattformen gelten je Position. Ein Standort enthält genau ein Logo und ein Titelbild; ein erneuter Upload eines dieser Bilder ersetzt daher das vorhandene Bild. Setzen Sie type bewusst: Galeriebilder gehören in ADDITIONAL.

fetchPhotoUploadStatus

Fragen Sie den Status eines Uploads in der Warteschlange wiederholt ab, bis er einen endgültigen Zustand erreicht. Verwenden Sie den Wert von request.requestId, den addLocationPhotos zurückgegeben hat.

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

Parameter

Die Nutzdaten enthalten requestId, den Auftragsstatus status mit dem Wert PROCESSING, SUCCESS oder ERROR sowie ein Array photos, dessen Einträge jeweils mediaId, locationId, einen eigenen Wert für status und einen Wert für errorMessage enthalten.

Der Auftragsstatus status zeigt an, dass die Verarbeitung abgeschlossen ist, nicht, dass jedes Bild übernommen wurde. Ein Auftrag mit dem Status SUCCESS kann weiterhin abgelehnte Fotos enthalten; gehen Sie deshalb photos durch und lesen Sie jeden Eintrag aus, sobald der Auftrag den Status PROCESSING verlassen hat. Warten Sie zwischen den Abfragen einige Sekunden: Eine Schleife ohne Pause führt schnell dazu, dass das Anfragelimit erreicht wird. Fragen Sie nur IDs aus einem kürzlich erfolgten Upload ab, da eine abgelaufene ID nie einen endgültigen Zustand erreicht.

starLocationPhotos

Markieren Sie zusätzliche Fotos mit einem Stern, damit sie auf Plattformen, die hervorgehobene Bilder unterstützen, bevorzugt platziert werden, oder entfernen Sie die Sternmarkierung, indem Sie false übergeben.

// 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);

Parameter

Gibt die Nutzdaten aus starUnstarLocationPhotos zurück: success, photos und ein einzelnes Objekt error statt eines Arrays errors. Jedes zurückgegebene Foto enthält id, databaseId, url, thumbnailUrl, type und seinen neuen Wert für starred.

Nur Fotos vom Typ ADDITIONAL können mit einem Stern markiert werden; Logo und Titelbild haben bereits Vorrang. Ein Standort kann höchstens vier mit einem Stern markierte Fotos enthalten, und bei der Prüfung werden die bereits markierten Fotos und die Fotos in Ihrem Aufruf zusammengezählt; bei mehr als vier Fotos schlägt daher die gesamte Anfrage fehl.

removeLocationPhotos

Entfernen Sie anhand der Foto-IDs die Zuordnung von Fotos zu einem Standort. Verwenden Sie diese Methode, um veraltete Galeriebilder zu entfernen oder einen fehlerhaften Import rückgängig zu machen.

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

Parameter

Gibt die Nutzdaten aus removeLocationPhotos zurück: removedCount, errors und clientMutationId. Ein Wert von 0 für removedCount zusammen mit null für errors bedeutet, dass keine der übergebenen IDs diesem Standort zugeordnet war; daran erkennen Sie IDs, deren Zuordnung bereits entfernt wurde.

Hier können nur Fotos vom Typ ADDITIONAL entfernt werden. Ersetzen Sie ein Logo oder Titelbild stattdessen durch den Upload eines neuen Bildes. Beim Entfernen von Medien wird deren Zuordnung zum Standort aufgehoben; die Datei wird dabei nicht zwangsläufig aus der Medienbibliothek des Kontos gelöscht.

Typische Aktualisierung der Galerie

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

Weiterführende Ressourcen

• Standorte, Standort-IDs nachschlagen
• Fehlerbehandlung, typisierte Fehler, die jede Methode auslöst
• Logo, Titelbild und Fotos hochladen, die vollständige Anleitung
• REST-Referenz: Fotos abrufen, Fotos hochladen, Status des Massen-Uploads abrufen, Fotos mit einem Stern markieren, Fotos entfernen