Listings APIListings API
Masuk
POST/api/v4/locations/photos

Unggah foto ke lokasi

Melampirkan media ke lokasi, baik melalui URL gambar publik maupun dengan merujuk file yang sudah ada di pustaka media Anda.

Memerlukan kunci API. Lihat Autentikasi untuk format header dan rotasi kunci.

Parameter

Body

Field bersarang yang ditandai wajib hanya berlaku jika Anda mengirim induknya. Jika induknya opsional dan Anda menghilangkannya, field turunan yang wajib tidak berlaku.

NamaTipeWajibDeskripsi
input.locationIdstringwajibThe location's Base64-encoded Relay ID to attach media to.
input.photosarray of objectswajibImages to attach. `photo` is the only required key on each item.
input.photos[].photostringwajibA publicly accessible JPEG or PNG URL that Listings API fetches and stores. The field is named `photo`, not `url`.
input.photos[].typestringopsionalWhich slot the image fills: `LOGO`, `COVER`, or `ADDITIONAL`. Defaults to an additional photo.
input.photos[].starredbooleanopsionalStar the photo as it is attached, instead of a follow-up call to the star endpoint. Only additional photos can be starred, at most 4 per location.
input.photos[].sourcestringopsionalFree-text label recording where the image came from.

Contoh permintaan

Body siap tempel. Ganti ID dan nilai placeholder dengan milik Anda.

Request body
{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photos": [      { "photo": "https://cdn.example.com/jenny-home/logo.png", "type": "LOGO" },      { "photo": "https://cdn.example.com/jenny-home/storefront.jpg", "type": "ADDITIONAL" }    ]  }}

Respons

200Photos attached inline. Returns the created photo records; `errors` is null on success and `request` is empty because nothing was queued.
Response
{  "data": {    "addLocationPhotos": {      "clientMutationId": null,      "success": true,      "request": {},      "photos": [        {          "id": "TWVkaWFGaWxlOjU4Nzg5MzE=",          "databaseId": 5878931,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.png",          "thumbnailUrl": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/thumbnail_f47d62a6.png",          "type": "LOGO",          "starred": false        },        {          "id": "TWVkaWFGaWxlOjU4Nzg5MzI=",          "databaseId": 5878932,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/ef4ffb12.jpg",          "thumbnailUrl": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/thumbnail_ef4ffb12.jpg",          "type": "ADDITIONAL",          "starred": false        }      ],      "errors": null    }  }}
401Unauthenticated, missing or invalid API key.

Melampirkan satu atau beberapa gambar ke lokasi. Berikan array photos yang setiap itemnya memuat setidaknya photo, yaitu URL gambar publik yang diambil dan disimpan oleh Listings API. locationId dan array photos yang tidak kosong selalu wajib disertakan.

Dua bentuk respons berhasil

Batch kecil diunggah langsung: photos memuat media yang telah selesai diunggah dan request berupa objek kosong, seperti pada contoh di atas. Batch besar dimasukkan ke antrean, dan 200 yang sama akan terlihat seperti ini:

JSON
{  "data": {    "addLocationPhotos": {      "clientMutationId": null,      "success": true,      "request": {        "requestId": "e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a",        "status": "PROCCESSING"      },      "photos": [],      "errors": null    }  }}

Keduanya merupakan respons berhasil, jadi tangani dengan memeriksa apakah request.requestId ada, bukan dengan mengasumsikan bahwa photos terisi.

Field URL adalah photo. Bukan url, dan bukan image. Selain itu, setiap item menerima type (LOGO, COVER, atau ADDITIONAL), starred, dan source sebagai field opsional; publisherOverride dan partnerMediaId juga diterima untuk integrasi mitra. Foto yang dikembalikan tidak memiliki field caption.

Kasus penggunaan: menambahkan gambar awal untuk lokasi baru. Segera setelah membuat lokasi seperti "Jenny Home", gunakan POST untuk mengunggah logo dan foto tampak depan tokonya melalui URL dalam satu panggilan. Respons mengembalikan id setiap foto baru, yang kemudian Anda teruskan ke endpoint star dan remove.

Kasus penggunaan: menggunakan kembali aset yang telah disetujui di beberapa lokasi. Arahkan beberapa lokasi ke URL gambar yang sama dan sudah dihosting dalam array photos masing-masing agar setiap lokasi menggunakan aset sumber yang sama.

Hal yang perlu diperhatikan.

  • Gambar harus berformat JPEG atau PNG. Aturan ukuran platform publikasi berlaku per kategori (batas bawah umumnya sekitar 10 KB dan batas atas beberapa MB).
  • Batch besar diproses secara asinkron. Jika ukuran batch melebihi batas di sisi server, panggilan memasukkan pekerjaan ke antrean alih-alih langsung mengunggah: photos dikembalikan dalam keadaan kosong dan request.requestId ditetapkan. Lakukan polling pada GET /locations/photos/requests/{requestId} dengan id tersebut untuk memantau penyelesaian. Ambang batas ditentukan oleh konfigurasi di sisi server, jadi anggap bahwa "batch besar mungkin dimasukkan ke antrean", bukan menggunakan angka tetap, dan tentukan percabangan berdasarkan ada atau tidaknya request.requestId.
  • Jangan tentukan percabangan berdasarkan request.status. Pada respons untuk pekerjaan yang masuk antrean, nilainya berupa string literal PROCCESSING, yang ejaannya berbeda dari PROCESSING yang dilaporkan endpoint polling untuk pekerjaan yang sama. Keberadaan request.requestId adalah penanda yang dapat diandalkan.
  • Meneruskan starred: true pada foto hingga melebihi batas 4 foto berbintang yang diizinkan akan menggagalkan seluruh panggilan dengan SY15012. Pemeriksaan ini menghitung foto berbintang yang sudah ada di lokasi ditambah item berbintang dalam permintaan ini.
  • Satu lokasi menyimpan satu logo dan satu sampul; mengunggah ulang salah satu kategori tersebut akan menggantikan gambar yang ada.
  • Tetapkan type secara eksplisit jika Anda ingin menjadikan gambar sebagai logo atau sampul. Tanpanya, gambar disimpan sebagai foto tambahan.
Request
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/storefront.jpg",          "type": "ADDITIONAL"        }      ]    }  }'
Run in playground