Unggah logo, sampul, dan foto

Lampirkan logo, gambar sampul, dan foto galeri ke lokasi melalui URL, lihat media terlampir, beri bintang pada gambar utama, dan hapus media usang.

Foto dilampirkan ke lokasi melalui URL publik: Anda menghosting gambar, API mengambil dan menyimpannya, lalu platform publikasi mengambilnya dari sana. Setiap lokasi menyimpan satu logo, satu sampul, dan foto tambahan dalam jumlah berapa pun, dan hingga empat foto tambahan tersebut dapat diberi bintang untuk mendapatkan penempatan prioritas.

1. Unggah melalui URL

POST /locations/photos menerima input.locationId dan array input.photos. URL setiap item dimasukkan ke field bernama photo, bukan url. Tetapkan type secara eksplisit ke LOGO, COVER, atau ADDITIONAL; item tanpa type disimpan sebagai foto tambahan.

curl -X POST https://listingsapi.com/api/v4/locations/photos \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photos": [      { "photo": "https://cdn.example.com/jenny-home/logo.png", "type": "LOGO" },      { "photo": "https://cdn.example.com/jenny-home/cover.jpg", "type": "COVER" },      { "photo": "https://cdn.example.com/jenny-home/storefront.jpg", "type": "ADDITIONAL" }    ]  }}'

{  "data": {    "addLocationPhotos": {      "success": true,      "request": {},      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "databaseId": 5878931, "type": "LOGO", "starred": false,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.png" },        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "databaseId": 5878932, "type": "ADDITIONAL", "starred": false }      ],      "errors": null    }  }}

Simpan id setiap foto: nilai inilah yang diterima endpoint untuk memberi bintang dan menghapus foto. Mengunggah ulang LOGO atau COVER akan menggantikan yang sudah ada. Batch kecil langsung disimpan seperti ini. Batch besar akan dimasukkan ke antrean: photos dikembalikan dalam keadaan kosong dan request.requestId ditetapkan. Tentukan percabangan berdasarkan ada atau tidaknya requestId, lalu lakukan polling ke GET /locations/photos/requests/{requestId}.

curl https://listingsapi.com/api/v4/locations/photos/requests/e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a \-H "Authorization: API $LISTINGSAPI_KEY"

2. Tampilkan daftar media yang terlampir

GET /locations/{locationId}/photos mengembalikan semua file media pada lokasi sebagai array biasa. Gunakan untuk memeriksa apakah logo atau sampul belum tersedia sebelum Anda mengunggah, serta untuk mengumpulkan ID bagi dua langkah berikutnya. Path menerima ID dalam format base64 atau angka aslinya.

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/photos \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "mediaFilesOfLocation": [      { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "categoryName": "Logo", "categoryId": "4", "starred": false, "viewsCount": 0 },      { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "categoryName": "Additional", "categoryId": "12", "starred": true, "viewsCount": 143 }    ]  }}

categoryName bernilai Logo, Cover, atau Additional. Lokasi tanpa media mengembalikan array kosong, bukan kesalahan.

3. Beri bintang pada foto tambahan

POST /locations/photos/star menandai foto tambahan agar mendapat penempatan prioritas pada platform publikasi yang mendukung gambar unggulan. Hanya foto ADDITIONAL yang dapat diberi bintang, maksimal 4 per lokasi; foto kelima menyebabkan seluruh panggilan gagal dengan SY15012. Anda juga dapat menyertakan starred: true pada item saat mengunggah.

curl -X POST https://listingsapi.com/api/v4/locations/photos/star \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photoIds": ["TWVkaWFGaWxlOjU4Nzg5MzI="],    "starred": true  }}'

{  "data": {    "starUnstarLocationPhotos": {      "success": true,      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "type": "ADDITIONAL", "starred": true }      ],      "error": null    }  }}

Kunci responsnya adalah starUnstarLocationPhotos dan memuat satu error, bukan array errors. Flag starred dalam body mengendalikan tindakan: kirim false untuk menghapus tanda bintang. Metode SDK menerima nilai boolean yang sama.

4. Hapus foto

POST /locations/photos/remove melepaskan foto tambahan dari lokasi berdasarkan ID. removedCount melaporkan jumlah foto yang dilepaskan, sehingga 0 dengan errors: null berarti tidak ada foto dengan ID tersebut yang terlampir ke lokasi ini.

curl -X POST https://listingsapi.com/api/v4/locations/photos/remove \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photoIds": ["TWVkaWFGaWxlOjU4Nzg5MzI="]  }}'

{  "data": {    "removeLocationPhotos": {      "removedCount": 1,      "errors": null    }  }}

Hanya foto ADDITIONAL yang dapat dihapus di sini. Untuk mengganti logo atau sampul, unggah gambar baru dengan type tersebut dan gambar itu akan menggantikan gambar lama. Penghapusan melepaskan file dari lokasi; tindakan ini tidak selalu menghapus file tersebut secara permanen dari pustaka media Anda.

5. Cara platform publikasi menggunakan setiap slot

Langkah selanjutnya

• Perbarui lokasi: jam operasional, penutupan, dan kategori Google pada rekaman yang sama.
• Periksa status profil bisnis dan tautan aktif: lihat kapan platform publikasi telah memublikasikan gambar baru.
• Unggah foto, Dapatkan foto, Beri bintang pada foto, Hapus foto, dan Status unggahan massal: halaman referensi.
• Referensi SDK: Foto Python dan Foto Node.