Fotoğraflar

listingsapi-js SDK ile bir konuma logo, kapak ve galeri fotoğrafları ekleyin, öne çıkan görseli yıldızlayın ve güncelliğini yitiren dosyaları kaldırın.

Fotoğraflar, herkese açık URL'ler aracılığıyla bir konuma eklenir: görseli siz barındırırsınız, platform görseli alıp depolar ve yayın platformları da görseli buradan alır. Bir konumda 1 logo, 1 kapak ve en fazla 4 tanesi yıldızla işaretlenebilen, sınırsız sayıda ek fotoğraf bulunabilir. Tüm fotoğraf metotları ListingsAPI istemci örneğinde bulunur ve bir konum kimliğiyle sınırlıdır. Sayısal konum kimlikleri otomatik olarak kodlanır; bu nedenle 1800289 ve 'TG9jYXRpb246MTgwMDI4OQ==' birbirinin yerine kullanılabilir.

Yüklemeler 2 farklı şekilde başarılı olabilir. Küçük bir grup aynı istek içinde depolanır ve yanıt, işlenmiş medyayı içerir; büyük bir grup ise kuyruğa alınır ve durumu düzenli aralıklarla sorgulamanız için bir istek kimliği döndürülür. Kendi görsellerinizi saymak yerine request.requestId bulunup bulunmadığına göre işlem yapın.

fetchLocationPhotos

Bir konuma eklenmiş tüm medya dosyalarını listeleyin: logo, kapak ve ek görseller. Eksikleri görmek ve yıldızla işaretleme ile kaldırma metotlarının kabul ettiği fotoğraf kimliklerini toplamak için yüklemeden önce bu metodu çağırın.

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

Parametreler

Sonuç olarak mediaFilesOfLocation dizisini döndürür; varsayılan değer boş bir dizidir. Her dosya id, url, thumbnailUrl, categoryName (Logo, Cover veya Additional), categoryId, fileType, starred ve viewsCount alanlarını içerir. Medyası olmayan bir konum için boş bir dizi döndürülür; bu, yeni oluşturulmuş bir konum için normal yanıttır ve hata değildir.

addLocationPhotos

Bir konuma bir veya daha fazla görsel ekleyin. Her öğenin photo alanında herkese açık bir JPEG veya PNG URL'si, type alanında ise görselin yerleştirileceği alan bulunmalıdır.

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

Fotoğraf seçenekleri

Parametreler

Sonuç olarak addLocationPhotos veri yükünü döndürür: success, photos, request, errors ve clientMutationId. Aynı istek içinde tamamlanan bir yüklemede photos, her birinin id, databaseId, url, thumbnailUrl, type ve starred alanlarıyla birlikte yeni medyayı içerir; request ise boş bir nesnedir. Kuyruğa alınan bir yüklemede photos boştur ve request.requestId alanına değer atanır. Her iki durum da başarılıdır.

Görseller JPEG veya PNG olmalıdır ve yayın platformlarının boyut kuralları her alan için ayrı ayrı geçerlidir. Bir konumda yalnızca 1 logo ve 1 kapak bulunur; bu nedenle bunlardan birini yeniden yüklemek mevcut görseli değiştirir. type değerini amacınıza uygun olarak ayarlayın: galeri görselleri ADDITIONAL alanına aittir.

fetchPhotoUploadStatus

Kuyruğa alınmış bir yüklemenin durumunu, işlem sonuçlanana kadar düzenli aralıklarla sorgulayın. addLocationPhotos tarafından döndürülen request.requestId değerini kullanın.

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

Parametreler

Veri yükü requestId alanını, değeri PROCESSING, SUCCESS veya ERROR olan iş status alanını ve her öğesi mediaId, locationId, kendine ait status ve bir errorMessage içeren photos dizisini içerir.

İşin status değeri, her görselin başarıyla eklendiğini değil, işlemenin tamamlandığını bildirir. SUCCESS durumundaki bir iş yine de reddedilmiş fotoğraflar içerebilir; bu nedenle iş PROCESSING durumundan çıktığında photos dizisini dolaşarak her öğeyi okuyun. Sorgular arasında birkaç saniye bekleyin: aralıksız bir döngü, kısa sürede istek sıklığı sınırına takılmanıza neden olur. Yalnızca yakın zamanda yapılan bir yüklemenin kimliklerini sorgulayın; çünkü süresi dolmuş bir kimlik için yapılan sorgular hiçbir zaman nihai bir sonuç vermez.

starLocationPhotos

Öne çıkan görselleri destekleyen yayın platformlarında öncelikli olarak gösterilmeleri için ek fotoğrafları yıldızla işaretleyin veya false ileterek yıldızlarını kaldırın.

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

Parametreler

Sonuç olarak starUnstarLocationPhotos veri yükünü döndürür: success, photos ve bir errors dizisi yerine tek bir error nesnesi. Döndürülen her fotoğraf id, databaseId, url, thumbnailUrl, type alanlarını ve yeni starred değerini içerir.

Yalnızca ADDITIONAL fotoğrafları yıldızla işaretlenebilir; logo ve kapak zaten önceliklidir. Bir konumda en fazla 4 yıldızlı fotoğraf bulunabilir ve kontrolde mevcut yıldızlı fotoğraflarla çağrınızdaki fotoğrafların toplamı dikkate alınır; bu nedenle toplamın 4'ü aşması isteğin tamamının başarısız olmasına neden olur.

removeLocationPhotos

Fotoğrafları kimliklerini kullanarak bir konumdan ayırın. Güncelliğini yitirmiş galeri görsellerini kaldırmak veya hatalı bir içe aktarma işlemini geri almak için bu metodu kullanın.

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

Parametreler

Sonuç olarak removeLocationPhotos veri yükünü döndürür: removedCount, errors ve clientMutationId. removedCount değerinin 0 ve errors değerinin null olması, gönderdiğiniz kimliklerin hiçbirinin o konuma bağlı olmadığı anlamına gelir; daha önce kaldırılmış kimlikleri bu şekilde tespit edebilirsiniz.

Burada yalnızca ADDITIONAL fotoğrafları kaldırılabilir. Bir logoyu veya kapağı değiştirmek için yenisini yükleyin. Medyayı kaldırmak, konumla olan bağlantısını keser; dosyanın hesabın medya kitaplığından da silineceği anlamına gelmez.

Tipik galeri yenileme

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

İlgili kaynaklar

• Konumlar, konum kimliklerini bulma
• Hata işleme, her metodun fırlattığı türü belirli hatalar
• Logo, kapak ve fotoğraf yükleme, tüm adımları içeren kılavuz
• REST referansı: fotoğrafları getirme, fotoğraf yükleme, toplu yükleme durumu, fotoğrafları yıldızla işaretleme, fotoğrafları kaldırma