Konumlar

Konum uç noktaları: listeleme, arama, id/mağaza koduyla sorgu, oluşturma, güncelleme, arşiv, fotoğraf; kullanım sırasıyla cURL, Python ve Node örnekleri.

İşletme kayıtları, yorumlar, gönderiler ve analizlerin tümü bir konum ID'sine bağlıdır. Konumlar kaynağının on üç uç noktası vardır: konumları bulan dört okuma uç noktası, bunları oluşturan, değiştiren ve arşivleyen dört yazma uç noktası ve fotoğrafları yöneten beş uç nokta. Read (okuma) anahtarı, okuma işlemlerini kapsar. Her POST için bir Write (yazma) anahtarı gerekir; bir yazma işleminde Read anahtarı kullanıldığında uç nokta, SY90016 ile birlikte HTTP 400 döndürür.

Bu kılavuzdaki her id, base64 biçimindeki Relay id'sidir; örneğin TG9jYXRpb246MTgwMDI4OQ== (kodu çözüldüğünde Location:1800289 elde edilir). Her iki SDK da sayısal databaseId değerini kabul eder ve sizin için kodlar.

Uç noktalara genel bakış

YöntemYolİşleviBaşvuru
GET/locationsEn yeniden başlayarak tüm konumları sayfalar halinde getirin.Tüm konumları listeleme
GET/locations/searchAd, adres ve mağaza id'sinde anahtar kelime arayarak konumları bulun.Konum arama
GET/locations-by-idsBir grup base64 id'sine karşılık gelen tam kayıtları getirin.ID'lere göre konumları getirme
GET/locations-by-store-codesKendi mağaza kodlarınıza karşılık gelen tam kayıtları getirin.Mağaza kodlarına göre konumları getirme
POST/locationsBir konum oluşturun ve gönderim için kuyruğa alın.Konum oluşturma
POST/locations/updateTek bir konumun yazılabilir herhangi bir alanını değiştirin.Konum güncelleme
POST/locations/archiveKonumları faturalandırma dönemi sonunda arşivlenecek şekilde planlayın.Konumları arşivleme
POST/locations/cancel_archiveArşivlenmesi planlanan konumları yeniden etkin duruma getirin.Planlanan arşivlemeyi iptal etme
POST/locations/photosURL aracılığıyla logo, kapak veya galeri fotoğrafları ekleyin.Fotoğraf yükleme
GET/locations/photos/requests/{requestId}Kuyruğa alınmış bir toplu yüklemenin durumunu düzenli aralıklarla sorgulayın.Toplu yükleme durumunu kontrol etme
GET/locations/{locationId}/photosBir konumdaki tüm medya dosyalarını listeleyin.Fotoğrafları getirme
POST/locations/photos/starEk fotoğrafları yıldızla işaretleyin veya yıldızlarını kaldırın.Fotoğrafları yıldızla işaretleme
POST/locations/photos/removeEk fotoğrafların konumla bağlantısını kaldırın.Fotoğrafları kaldırma

Tüm konumları listeleme

GET /locations, hesaptaki tüm konumları en yeniden başlayarak sayfalar halinde getirir. Bu, imleç tabanlı bir bağlantıdır: edges[].node her bir kaydı içerir ve pageInfo.endCursor, sonraki sayfa için after parametresinin değerini sağlar. Hesabın tamamını kendi sisteminizle senkronize etmek için bunu kullanın.

Parametreler

AdBulunduğu yerZorunluNotlar
firstqueryHayırİleri yönde sayfalama için sayfa boyutu. Varsayılan değer 50'dir. after ile birlikte kullanın.
afterqueryHayırÖnceki sayfanın pageInfo.endCursor değeri.
lastqueryHayırGeri yönde sayfalama için sayfa boyutu. before ile birlikte kullanın.
beforequeryHayırGeriye doğru ayrıldığınız sayfanın ilk kenarının cursor değeri. pageInfo, startCursor içermez.
filterqueryHayırSonuç kümesini sunucu tarafında, örneğin onay durumuna göre daraltmak için JSON olarak kodlanmış nesne. İki SDK'nın da listeleme yöntemi bunu kabul etmez; filtrelenmiş bir alt küme için REST çağrısı yapın.
List
curl "https://listingsapi.com/api/v4/locations?first=50" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "storeId": null,            "approved": "APPROVED",            "archived": false,            "archivalScheduledAt": null,            "city": "Austin",            "stateIso": "TX",            "countryIso": "US",            "subCategoryId": 1432,            "planName": "Launch",            "placeActionLinks": [],            "discoveredPlaceActionLinks": []          }        }      ],      "pageInfo": {        "hasNextPage": false,        "hasPreviousPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "total": 1      }    }  }}

pageInfo.hasNextPage değerini okuyun ve bu değer false olduğunda durun. Sayfa düzeyindeki sayı pageInfo.total değeridir. Düğümün id değeri, diğer tüm uç noktaların beklediği tanımlayıcıdır.

Konum arama

GET /locations/search, bir anahtar kelimeyi konum adı, açık adres, şehir ve mağaza id'siyle eşleştirir. Listeyle aynı edges[].node ve pageInfo.endCursor yapısına sahip, imleç tabanlı bir bağlantıdır. Yazdıkça öneriler sunan bir seçim alanı için veya bir mağazayı oluşturmadan önce mevcut olduğunu doğrulamak için bunu kullanın.

Parametreler

AdBulunduğu yerZorunluNotlar
queryqueryHayırArama anahtar kelimesi. Tüm konumları filtrelemeden sayfalar halinde getirmek için bu parametreyi belirtmeyin.
firstqueryHayırSayfa boyutu. Varsayılan değer 50'dir.
afterqueryHayırÖnceki sayfanın pageInfo.endCursor değeri.
filterqueryHayırListeleme uç noktasında olduğu gibi JSON olarak kodlanmış filtre nesnesi.

Her iki SDK da eşleştirmeyi belirli alanlarla, örneğin yalnızca name ile sınırlamak için bir fields listesi kabul eder.

Search
curl "https://listingsapi.com/api/v4/locations/search?query=Jenny&first=10" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "searchLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "storeId": null,            "street": "600 Congress Ave, Suite 200",            "city": "Austin",            "approved": "APPROVED",            "archived": false          }        }      ],      "pageInfo": {        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "hasNextPage": false,        "hasPreviousPage": false,        "total": 1      }    }  }}

Boş bir edges dizisi, hiçbir eşleşme bulunmadığı anlamına gelir. Düğüm tam adresi, kategoriyi ve approved durumunu içerir; bu nedenle bir sonuç satırı için ikinci bir sorgulama gerekmez.

Kimliklere göre konumları alın

GET /locations-by-ids, bir grup base64 kimliği için tam kayıtları tek bir çağrıda döndürür ve konum başına bir çağrı yapmaya göre daha az istek kullanır. Hem etkin hem de arşivlenmiş konumlar bulunur. Bir connection değil, düz bir dizi döndürür. Bir webhook yükündeki veya kendi veri deponuzdaki kimliklerin tam kayıtlarını almak için kullanın.

Parametreler

AdBulunduğu yerZorunluNotlar
idsqueryEvetJSON olarak kodlanmış base64 kimlikleri dizisi. Değerin tamamını URL kodlamasından geçirin; curl -G --data-urlencode bunu sizin için yapar.
By ids
curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ==","TG9jYXRpb246MTgwMDI5MA=="]' \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getLocationsByIds": [      {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "storeId": null,        "name": "Jenny Home",        "archived": false,        "archivedAt": null,        "city": "Austin",        "stateIso": "TX",        "countryIso": "US",        "subCategoryId": 1432,        "businessHours": [],        "locationPhotos": [],        "placeActionLinks": [],        "discoveredPlaceActionLinks": []      }    ]  }}

Hesabınızda bulunmayan kimlikler hata oluşturmak yerine sessizce atlanır. Güncelliğini yitirmiş kimlikleri tespit etmek için döndürülen kayıt sayısını gönderdiğiniz kimlik sayısıyla karşılaştırın.

Mağaza kodlarına göre konumları alın

GET /locations-by-store-codes ters yönde arama yapar: kendi mağaza kodlarınıza karşılık gelen tam kayıtları bulur. Düz bir dizi döndürür. POS sisteminiz veya franchise listeniz konumları mağaza koduyla tanımlıyorsa ve kimliklerimizi hiç kaydetmediyseniz bunu kullanın.

Parametreler

AdBulunduğu yerZorunluNotlar
storeCodesqueryEvetJSON olarak kodlanmış mağaza kodu dizeleri dizisi. Değerin tamamını URL kodlamasından geçirin.
By store codes
curl -G https://listingsapi.com/api/v4/locations-by-store-codes \--data-urlencode 'storeCodes=["ACME01","ACME02"]' \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getLocationsByStoreCodes": [      {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "storeId": "ACME01",        "name": "Jenny Home",        "archived": false,        "city": "Austin",        "countryIso": "US",        "planName": "Launch"      }    ]  }}

Her nesnenin storeId değerini listenizdeki ilgili kayıtla eşleştirin. Eşleşmeyen kodlar sonuçta yer almaz. Bir konumun mağaza kodu yalnızca oluşturma veya güncelleme sırasında storeId ayarlanmışsa bulunur.

Bir konum oluşturun

POST /locations bir konum oluşturur ve bu alanı ilettiğinizde yalnızca enabledSiteIds için, aksi takdirde planınızdaki tüm yayın platformlarına gönderilmek üzere kuyruğa ekler. Tüm alanlar input altında yer alır. 10 alan zorunludur; geri kalanı isteğe bağlıdır ve belirtmediğiniz alanları yayın platformları boş gösterir.

Parametreler

AdBulunduğu yerZorunluNotlar
input.namebodyEvetİşletme adı, 2 ila 150 karakter.
input.descriptionbodyEvetEn az 200 karakter (SY10005). Yayın platformları bunu işletme kaydının metni olarak kullanır.
input.countryIsobodyEvetDesteklenen bir ülke kodu (SY10036). Ülkeler kaynağından alınır.
input.citybodyEvetÜlkenin hasCity değeri true olduğunda zorunludur (SY10126). Bu değer false olduğunda gönderdiğiniz şehir değeri atılır.
input.subCategoryIdbodyEvetAlt kategoriler kaynağından alınan sayısal databaseId.
input.streetbodyEvet5 ila 100 karakter (SY10011).
input.stateIsobodyEvetÜlkenin stateRequired değeri true olduğunda zorunludur ve o ülkenin states değerlerinden biri olmalıdır (SY10010). stateRequired değeri false olduğunda bu alanı belirtmeyin.
input.phonebodyEvetÜlkeye göre doğrulanır (SY10015).
input.postalCodebodyHayırİsteğe bağlıdır, ancak ülkenin hasPostalCode değeri true olduğunda gönderin. Gönderdiğiniz değer ülkenin biçimine uymalıdır (SY10014).
input.bizUrlbodyEvetWeb sitesi olarak yayımlanır. Bazı yayın platformları web sitesi olmayan işletme kayıtlarını reddeder.
input.storeIdbodyHayırHesap genelinde benzersiz olan kendi mağaza kodunuz.
input.businessHoursbodyHayır7 adet { day, type, slots } girdisi. type, OPEN veya CLOSED olur; kapalı bir günün slots değeri boştur.
input.placeActionLinksbodyHayırGoogle işlem bağlantıları: placeActionType, uri, isteğe bağlı isPreferred. Oluşturma sırasında action gerekmez. Yer işlem bağlantıları bölümüne bakın.
input.enabledSiteIdsbodyHayırPlanınızdaki sitelerin bir alt kümesinde yayımlayın. Kimlikler plan siteleri kaynağından alınır.
input.clientMutationIdbodyHayırİlişkilendirme için değiştirilmeden döndürülür. Yinelenen yazma işlemlerini önlemez.

Bunlara ek olarak referans sayfasında listelenen isteğe bağlı alanlar da vardır: Google GCID kategorileri, sosyal medya URL'leri, koordinatlar, işletme sahibinin iletişim bilgileri, ödeme yöntemleri, hizmet bölgesi ve daha fazlası.

Create
curl -X POST https://listingsapi.com/api/v4/locations \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "name": "Acme Kitchen",    "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby growers. Our dining room seats forty, takeout and delivery run until close, and the bar pours regional wine and beer on tap.",    "storeId": "ACME01",    "street": "123 Jump Street",    "city": "New York",    "stateIso": "NY",    "postalCode": "10013",    "countryIso": "US",    "phone": "6443859313",    "bizUrl": "https://acmekitchen.example.com",    "subCategoryId": 1432,    "businessHours": [      { "day": "MONDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "TUESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "THURSDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "FRIDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "SATURDAY", "type": "OPEN", "slots": [{ "start": "10:00am", "end": "02:00pm" }] },      { "day": "SUNDAY", "type": "CLOSED", "slots": [] }    ],    "placeActionLinks": [      { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true }    ]  }}'
JSON
{  "data": {    "createLocation": {      "clientMutationId": null,      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME01",        "name": "Acme Kitchen",        "city": "New York",        "countryIso": "US",        "status": "PENDING",        "placeActionLinks": [          { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true, "name": null, "submissionStatus": null }        ],        "discoveredPlaceActionLinks": []      }    }  }}

Her iki kimliği de saklayın: sonraki tüm yazma işlemlerinde base64 biçimindeki id gerekir; databaseId ise kontrol panellerinde ve webhook'larda gördüğünüz sayıdır. status başlangıçta PENDING olur ve başka bir API çağrısı gerekmeden ilerler. Bir yer işlem bağlantısının name ve submissionStatus değerleri, bağlantı Google ile senkronize edilene kadar null olarak kalır. Python'daki locations.add(), zorunlu alanları yerel olarak doğrular ve herhangi bir ağ çağrısından önce ValidationError hatası oluşturur; locations.create(input) ise bunun yerine ham bir camelCase dict alır.

Bir konumu güncelleme

POST /locations/update kısmi bir güncellemedir: zorunlu olan tek alan input.id alanıdır ve yalnızca gönderdiğiniz alanlar değişir. Aynı çağrıyla bir telefon numarası düzeltilir veya haftalık program yeniden yazılır. Python'daki locations.update() ve Node'daki updateLocation(), tek bir camelCase nesnesi alır.

Parametreler

AdBulunduğu yerZorunluNotlar
input.idbodyEvetKonumun base64 kimliği. Alan locationId değil, id alanıdır.
input.phone, input.bizUrl, input.name, adres alanlarıbodyHayırOluşturma çağrısındaki yazılabilir alanlardan herhangi biri.
input.businessHoursbodyHayır7 günün tamamını gönderin; eksik bir hafta reddedilir. Tatil günlerinde geçerli olacak istisnalar için specialDate içeren day: "SPECIAL" girdilerini haftalık programla birlikte ekleyin, asla haftalık programın yerine göndermeyin.
input.moreHoursbodyHayırTeslimat gibi ikincil programlar; her biri { hoursTypeId, moreHour } biçimindedir. Burada specialDate bulunmaz.
input.temporarilyClosedbodyHayırtrue, konum kapalıyken çalışma saatlerinin yayımlanmasını durdurur.
input.primaryGbpSiteCategoryId, input.additionalGbpSiteCategoryIdsbodyHayırGCID biçimindeki Google kategorileri, örneğin gcid:restaurant. Bunlarla birlikte countryIso gönderin.
input.placeActionLinksbodyHayırEkleme veya ekleme/güncelleme: her öğe, action için add (varsayılan) ya da delete değerini alır. Belirtmediğiniz bağlantılar değiştirilmeden bırakılır.
input.submissionDisabledSiteIdsbodyHayırGönderim dışında tutulacak site kimlikleri.

Bunlara ek olarak referans sayfasında listelenen isteğe bağlı alanlar.

Update
curl -X POST https://listingsapi.com/api/v4/locations/update \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "phone": "5125550199",    "bizUrl": "https://acmekitchen.example.com",    "primaryGbpSiteCategoryId": "gcid:restaurant",    "businessHours": [      { "day": "MONDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "TUESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "THURSDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "FRIDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "SATURDAY", "type": "OPEN", "slots": [{ "start": "10:00am", "end": "02:00pm" }] },      { "day": "SUNDAY", "type": "CLOSED", "slots": [] }    ]  }}'
JSON
{  "data": {    "updateLocation": {      "clientMutationId": null,      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "name": "Jenny Home",        "phone": "5125550199",        "status": "APPROVED",        "placeActionLinks": [          { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "name": null, "submissionStatus": null }        ],        "discoveredPlaceActionLinks": []      }    }  }}

Yanıt, yeni değerlerin uygulandığını doğrulayabilmeniz için güncellenmiş konumu döndürür. Her güncelleme, konumun mevcut placeActionLinks kümesinin tamamını döndürür. Bir bağlantının URL'sini değiştirmek için aynı istekte eski bağlantı için bir delete ve yeni bağlantı için bir add gönderin.

Konumları arşivleme

POST /locations/archive, bir veya daha fazla konumun arşivlenmesini planlar. Arşivleme hemen gerçekleşmez: her konum ARCHIVE_SCHEDULED durumuna geçer, mevcut faturalandırma dönemi sona erene kadar yayında kalır ve faturalandırılmaya devam eder, ardından bir sonraki fatura oluşturulduğunda arşivlenir. Kapanan şubeleri toplu olarak hizmetten çıkarmak için bu çağrıyı kullanın.

Parametreler

AdBulunduğu yerZorunluNotlar
input.locationIdsbodyEvetArşivlenecek konumların base64 kimliklerini içeren dizi.
input.clientMutationIdbodyHayırDeğiştirilmeden döndürülür. Yinelenen yazma işlemlerini önlemez.
Archive
curl -X POST https://listingsapi.com/api/v4/locations/archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationIds": ["TG9jYXRpb246MTgwMDI4OQ==", "TG9jYXRpb246MTgwMDI5MA=="]  }}'
JSON
{  "data": {    "archiveLocations": {      "clientMutationId": null,      "bulkEditTaskId": null,      "errors": null,      "success": null,      "result": [        { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ARCHIVE_SCHEDULED", "success": true, "errors": null },        { "locationId": "TG9jYXRpb246MTgwMDI5MA==", "status": "ARCHIVE_SCHEDULED", "success": true, "errors": null }      ]    }  }}

En üst düzeydeki success değeri null olur; bunun yerine her result[] girdisinin kendi success değerini okuyun, böylece tek bir hatalı kimlik toplu işlemin geri kalanını engellemez.

result[].statusAnlamı
ARCHIVE_SCHEDULEDKuyruğa alındı. Konum, faturalandırma dönemi sona erene kadar yayında kalır ve faturalandırılmaya devam eder.
ARCHIVEDÖnceki bir çağrı veya dönem sırasında zaten arşivlenmiş.

Arşivleme planlanmış durumdayken liste ve arama sonuçlarında konumun archivalScheduledAt alanı ayarlanır. Arşivlenmiş bir konum, yeniden etkinleştirilene kadar güncellenemez.

Planlanmış arşivlemeyi iptal etme

POST /locations/cancel_archive, ARCHIVE_SCHEDULED durumundaki konumları yeniden ACTIVE durumuna getirir ve faturalandırma devam eder. Bu çağrı yalnızca faturalandırma dönemi henüz sona ermemişken çalışır; bir konum tamamen arşivlendikten sonra çağrı o konum için 404 döndürür.

Parametreler

AdBulunduğu yerZorunluNotlar
input.locationIdsbodyEvetŞu anda ARCHIVE_SCHEDULED durumunda olan konumların base64 kimliklerini içeren dizi.
input.clientMutationIdbodyHayırDeğiştirilmeden döndürülür.
Cancel archive
curl -X POST https://listingsapi.com/api/v4/locations/cancel_archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="] } }'
JSON
{  "data": {    "cancelLocationsArchive": {      "clientMutationId": null,      "bulkEditTaskId": null,      "errors": null,      "success": null,      "result": [        { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ACTIVE", "success": true, "errors": null }      ]    }  }}

Her result[] girdisi, konumun yeniden ACTIVE durumuna geçtiğini doğrular. Her iki SDK da bir seçim türü ve bir changedBy tanımlayıcısı olmak üzere 2 ek konumsal argüman gerektirir ve bunları locationIds ile birlikte gönderir; REST istek gövdesi yalnızca kimlikleri gerektirir.

Bir konuma fotoğraf yükleme

POST /locations/photos, herkese açık URL üzerinden görseller ekler: görseli siz barındırırsınız, API ise görseli alıp depolar. Bir konumda bir LOGO, bir COVER ve istenilen sayıda ADDITIONAL fotoğrafı tutulur. Bir logoyu veya kapak görselini yeniden yüklemek mevcut olanı değiştirir.

Parametreler

AdBulunduğu yerZorunluNotlar
input.locationIdbodyEvetKonumun base64 kimliği.
input.photosbodyEvetGörsel nesnelerini içeren dizi; boş olmamalıdır.
input.photos[].photobodyEvetHerkese açık bir JPEG veya PNG URL'si. Alan url değil, photo alanıdır.
input.photos[].typebodyHayırLOGO, COVER veya ADDITIONAL. Varsayılan olarak ek fotoğraf kullanılır.
input.photos[].starredbodyHayırFotoğrafı yüklenir yüklenmez yıldızla işaretleyin. Yalnızca ek fotoğraflar için geçerlidir ve konum başına en fazla 4 fotoğrafla sınırlıdır.
input.photos[].sourcebodyHayırGörselin nereden geldiğini kaydeden serbest metin etiketi.
Upload
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" }    ]  }}'
JSON
{  "data": {    "addLocationPhotos": {      "clientMutationId": null,      "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,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/ef4ffb12.jpg" }      ],      "errors": null    }  }}

Her fotoğrafın id değerini saklayın; yıldızla işaretleme ve kaldırma uç noktaları bu değeri alır. Bu, küçük bir toplu işlem için doğrudan döndürülen yanıt biçimidir. Büyük bir toplu işlem ise kuyruğa alınır: photos boş döner ve request.requestId ayarlanır; siz de bu kimlikle bir sonraki uç noktayı düzenli aralıklarla sorgularsınız. Eşik, sunucu tarafında yapılandırıldığı için işlem akışını request.requestId alanının mevcut olup olmamasına göre belirleyin.

Toplu fotoğraf yükleme durumunu kontrol edin

GET /locations/photos/requests/{requestId}, kuyruğa alınmış bir yüklemeyi sonuçlanana kadar düzenli aralıklarla sorgular, ardından her görselin sonucunu bildirir. Bir ilerleme çubuğunu güncellemek ve tam olarak hangi dosyaların neden reddedildiğini göstermek için kullanın.

Parametreler

AdBulunduğu yerZorunluNotlar
requestIdpathEvetKuyruğa alınmış bir yüklemenin yanıtındaki request.requestId alanından alınan UUID. Yalnızca yakın zamanda yapılan bir yüklemenin döndürdüğü id değerlerini sorgulayın.
Upload status
curl https://listingsapi.com/api/v4/locations/photos/requests/e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getLocationPhotosUploadStatus": {      "requestId": "e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a",      "status": "SUCCESS",      "photos": [        { "mediaId": "TWVkaWFGaWxlOjkxODI3", "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "SUCCESS", "errorMessage": null },        { "mediaId": null, "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ERROR", "errorMessage": "Image dimensions below the minimum 250x250." }      ]    }  }}
İşin status değeriAnlamı
PROCESSINGİşlem devam ediyor. Birkaç saniye sonra tekrar sorgulayın.
SUCCESSİşleme tamamlandı. Bazı fotoğraflar yine de başarısız olmuş olabilir; bu nedenle photos[].status ve photos[].errorMessage alanlarını okuyun.
ERRORİşin kendisi başarısız oldu. photos[].errorMessage alanını inceleyin.

İşin durumu yalnızca işlemenin tamamlandığını belirtir, her görselin başarıyla yüklendiğini değil. Sorgulamalar arasında birkaç saniye bekleyin; burada aralıksız bir döngü kullanmak, kısa sürede 429 sınırına ulaşmanıza neden olur.

Bir konumun fotoğraflarını alın

GET /locations/{locationId}/photos, bir konumdaki tüm medya dosyalarını düz bir dizi olarak döndürür: logo, kapak ve ek görseller; her biri herkese açık url değeri, thumbnailUrl değeri, kategorisi, starred bayrağı ve tüm zamanlara ait viewsCount değeriyle birlikte sunulur. Hangi alanın boş olduğunu görmek ve yıldız ekleme ile kaldırma çağrıları için id değerlerini toplamak üzere yüklemeden önce çağırın.

Parametreler

AdBulunduğu yerZorunluNotlar
locationIdpathEvetbase64 biçimindeki id değeri. Ham sayısal databaseId değeri de kabul edilir. Bu iki biçimden hiçbirine uymayan bir değer gönderildiğinde, errors içinde SY90002: Invalid Id ile birlikte HTTP 200 döndürülür.
List photos
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/photos \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "mediaFilesOfLocation": [      { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "categoryName": "Logo", "categoryId": "4", "fileType": "image", "starred": false, "viewsCount": 0,        "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.jpg",        "thumbnailUrl": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/thumbnail_f47d62a6.jpg" },      { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "categoryName": "Additional", "categoryId": "12", "fileType": "image", "starred": true, "viewsCount": 143,        "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" }    ]  }}

categoryName, Logo, Cover veya Additional değerini alır. Izgara görünümü için thumbnailUrl, tam boyutlu görünüm için url kullanın. Medya içermeyen bir konum için hata yerine boş bir dizi döndürülür.

Konum fotoğraflarına yıldız ekleyin

POST /locations/photos/star, öne çıkan görselleri destekleyen yayın platformlarında öncelikli yerleşim için ek fotoğrafları işaretler. Yalnızca ADDITIONAL fotoğraflarına yıldız eklenebilir ve konum başına en fazla 4 fotoğrafa yıldız eklenebilir. Yıldızı kaldırma da aynı şekilde çalışır: yapılacak işlemi gövdedeki starred bayrağı belirler.

Parametreler

AdBulunduğu yerZorunluNotlar
input.locationIdbodyEvetKonumun base64 biçimindeki id değeri.
input.photoIdsbodyEvetget-photos veya yükleme yanıtından alınan medya id değerleri.
input.starredbodyEvetYıldız eklemek için true, yıldızı kaldırmak için false. İşlemi yol değil, bu bayrak belirler; /star ve /unstar aynı şekilde davranır.
Star
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  }}'
JSON
{  "data": {    "starUnstarLocationPhotos": {      "success": true,      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "databaseId": 5878932, "type": "ADDITIONAL", "starred": true }      ],      "error": null    }  }}

Her iki yolda da yanıt anahtarı starUnstarLocationPhotos olur ve bir errors dizisi değil, tek bir error içerir. Beşinci bir fotoğrafa yıldız eklenmesi, çağrının tamamının SY15012 ile başarısız olmasına neden olur; kontrolde, zaten yıldız eklenmiş fotoğraflar ile bu istekteki fotoğrafların toplamı sayılır.

Bir konumdan fotoğrafları kaldırın

POST /locations/photos/remove, medya id değerlerine göre ek fotoğrafların konumla bağlantısını kaldırır. Güncelliğini yitirmiş mağaza cephesi görsellerini kaldırmak veya hatalı bir toplu içe aktarma işlemini geri almak için kullanın. Yalnızca ADDITIONAL fotoğrafları kaldırılabilir; bir logoyu veya kapağı değiştirmek için ilgili type değeriyle yeni bir görsel yükleyin.

Parametreler

AdBulunduğu yerZorunluNotlar
input.locationIdbodyEvetKonumun base64 biçimindeki id değeri.
input.photoIdsbodyEvetBağlantısı kaldırılacak medyanın get-photos veya yükleme yanıtından alınan id değerleri.
Remove
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="]  }}'
JSON
{  "data": {    "removeLocationPhotos": {      "clientMutationId": null,      "removedCount": 1,      "errors": null    }  }}

removedCount, gerçekte kaç dosyanın bağlantısının kaldırıldığını bildirir; dolayısıyla errors: null ile birlikte 0 döndürülmesi, bu id değerlerinden hiçbirinin bu konumla bağlantılı olmadığı anlamına gelir. Kaldırma işlemi dosyanın bağlantısını kaldırır; dosyayı medya kitaplığınızdan mutlaka silmez.

Karşılaşacağınız hatalar

KodAnlamıÇözüm
SY10005Oluşturma sırasında description eksik veya 200 karakterden kısa.Daha kapsamlı bir açıklama yazın.
SY10011street eksik veya 5 karakterden kısa.street gönderin.
SY10010stateIso eksik veya ülke için geçerli değil.Ülkeler listesinden bir eyalet kodu gönderin.
SY10036countryIso, desteklenen bir ülke değil.Ülkeler listesinden bir kod kullanın.
SY10126city, bu alanı zorunlu tutan bir ülke için eksik.city gönderin.
SY15012Bir konumda 4'ten fazla yıldız eklenmiş fotoğraf var.Önce bir fotoğrafın yıldızını kaldırın veya yüklemeden starred alanını çıkarın.
SY90002Fotoğraf yolunda geçersiz id değeri.Başka bir biçim yerine base64 biçimindeki id değerini veya düz sayıyı iletin.
SY90016Bir yazma işleminde Read anahtarı kullanıldı.Write anahtarı kullanın.
HTTP 404Artık ARCHIVE_SCHEDULED durumunda olmayan bir konum için arşivlemeyi iptal etme girişimi.Konum tamamen arşivlenmiş; bunun yerine yeniden etkinleştirme akışını kullanın.
HTTP 429İstek hızı sınırı aşıldı.Retry-After boyunca bekleyin. İstek hızı sınırları bölümüne bakın.

Yazma işlemleri ayrıca success: false ve data.<operation>.errors içindeki ayrıntıyla birlikte HTTP 200 döndürebilir. Tam liste hata kodları bölümündedir.

Sonraki adımlar