Foto

Lampirkan logo, sampul, dan foto galeri pada lokasi, beri bintang pada gambar utama, dan hapus file usang dengan SDK listingsapi-js.

Foto dilampirkan ke lokasi melalui URL publik: Anda menyediakan hosting gambar, platform mengambil dan menyimpannya, lalu platform publikasi mengambilnya dari sana. Satu lokasi menyimpan 1 logo, 1 sampul, dan foto tambahan dalam jumlah berapa pun, dengan maksimal 4 foto yang dapat diberi bintang. Semua metode foto tersedia pada instans klien ListingsAPI dan cakupannya terbatas pada ID lokasi. ID lokasi numerik dikodekan secara otomatis, sehingga 1800289 dan 'TG9jYXRpb246MTgwMDI4OQ==' dapat digunakan secara bergantian.

Unggahan memiliki 2 bentuk hasil yang berhasil. Sekumpulan kecil gambar disimpan langsung dan responsnya berisi media yang sudah selesai diproses; sekumpulan besar gambar dimasukkan ke antrean, dan Anda menerima ID permintaan untuk diperiksa secara berkala. Tentukan percabangan berdasarkan ada atau tidaknya request.requestId, bukan dengan menghitung gambar Anda sendiri.

fetchLocationPhotos

Tampilkan semua file media yang dilampirkan ke lokasi: logo, sampul, dan gambar tambahan. Panggil metode ini sebelum mengunggah untuk melihat apa yang belum tersedia, serta mengumpulkan ID foto yang diterima oleh metode star dan remove.

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

Parameter

Menghasilkan array mediaFilesOfLocation, dengan array kosong sebagai nilai default. Setiap file memuat id, url, thumbnailUrl, categoryName (Logo, Cover, atau Additional), categoryId, fileType, starred, dan viewsCount. Lokasi tanpa media mengembalikan array kosong, yang merupakan respons normal untuk lokasi yang baru dibuat dan bukan kesalahan.

addLocationPhotos

Lampirkan 1 atau beberapa gambar ke lokasi. Setiap item memerlukan URL JPEG atau PNG yang dapat diakses publik pada photo, serta slot yang ditempatinya pada 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);}}

Opsi foto

Parameter

Menghasilkan payload addLocationPhotos: success, photos, request, errors, dan clientMutationId. Pada unggahan yang diproses langsung, photos memuat media baru beserta id, databaseId, url, thumbnailUrl, type, dan starred dari setiap media, sedangkan request berupa objek kosong. Pada unggahan yang dimasukkan ke antrean, photos kosong dan request.requestId diisi. Keduanya merupakan hasil yang berhasil.

Gambar harus berformat JPEG atau PNG, dan aturan ukuran dari platform publikasi berlaku untuk setiap slot. Satu lokasi hanya menyimpan 1 logo dan 1 sampul, sehingga mengunggah ulang salah satunya akan mengganti gambar yang ada. Tetapkan type dengan cermat: ADDITIONAL adalah slot untuk gambar galeri.

fetchPhotoUploadStatus

Periksa unggahan yang dimasukkan ke antrean secara berkala hingga mencapai status akhir. Gunakan request.requestId yang dikembalikan oleh 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);}}

Parameter

Payload memuat requestId, status tugas dengan nilai PROCESSING, SUCCESS, atau ERROR, serta array photos yang setiap entrinya memuat mediaId, locationId, status masing-masing, dan errorMessage.

status tugas menunjukkan bahwa pemrosesan telah selesai, bukan bahwa setiap gambar berhasil disimpan. Tugas dengan status SUCCESS masih dapat berisi foto yang ditolak, jadi setelah statusnya bukan lagi PROCESSING, telusuri photos dan baca setiap entrinya. Beri jeda beberapa detik di antara pemeriksaan: perulangan tanpa jeda dapat dengan cepat menyebabkan pembatasan laju permintaan. Hanya periksa ID dari unggahan terbaru, karena ID yang sudah kedaluwarsa tidak pernah mencapai status akhir.

starLocationPhotos

Beri bintang pada foto tambahan agar penempatannya diprioritaskan pada platform publikasi yang mendukung gambar unggulan, atau hapus bintangnya dengan meneruskan 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);

Parameter

Menghasilkan payload starUnstarLocationPhotos: success, photos, dan 1 objek error, bukan array errors. Setiap foto yang dikembalikan memuat id, databaseId, url, thumbnailUrl, type, dan nilai starred yang baru.

Hanya foto ADDITIONAL yang dapat diberi bintang; logo dan sampul sudah menjadi gambar utama. Satu lokasi dapat memiliki maksimal 4 foto berbintang, dan pemeriksaan menghitung foto yang sudah berbintang ditambah foto dalam pemanggilan Anda, sehingga jumlah yang melebihi 4 akan menggagalkan seluruh permintaan.

removeLocationPhotos

Lepaskan foto dari lokasi berdasarkan ID-nya. Gunakan metode ini untuk menghapus gambar galeri yang sudah tidak relevan atau membatalkan impor yang keliru.

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

Parameter

Menghasilkan payload removeLocationPhotos: removedCount, errors, dan clientMutationId. Nilai removedCount sebesar 0 dengan errors bernilai null berarti tidak ada foto dengan ID yang Anda kirim yang dilampirkan ke lokasi tersebut, sehingga Anda dapat mendeteksi ID foto yang sudah tidak ada.

Hanya foto ADDITIONAL yang dapat dihapus di sini. Untuk mengganti logo atau sampul, unggah gambar baru. Menghapus media akan melepaskannya dari lokasi; tindakan ini tidak selalu menghapus file dari pustaka media akun.

Pembaruan galeri yang umum

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

Referensi terkait

• Lokasi, cari ID lokasi
• Penanganan error, error bertipe yang dilempar oleh setiap metode
• Unggah logo, sampul, dan foto, panduan lengkap
• Referensi REST: ambil foto, unggah foto, status unggahan massal, beri bintang pada foto, hapus foto