Listings APIListings API
Oturum aç

İlk API çağrınızı yapın

Kimlik doğrulaması yapın, konumlarınızı listeleyin, yanıt yapısını inceleyin, sonuç sayfalarında gezinin ve ID'lerin nasıl çalıştığını öğrenin.

Bu kılavuz, Başlangıç bölümünden bir hesap ve API anahtarı edindiğinizi varsayar. Her istek https://listingsapi.com adresindeki canlı API'ye gönderilir; bu nedenle standart bir API anahtarıyla yapılan yazma çağrısı gerçek verileri değiştirir. API'yi gerçek yayın platformlarını etkilemeden denemek için ücretsiz sandbox günlük erişimini kullanın.

1. API anahtarınızı ayarlayın

Anahtarı kontrol panelindeki API anahtarları bölümünden kopyalayın ve kabuğunuzda bir kez ortam değişkeni olarak dışa aktarın:

bash
export LISTINGSAPI_KEY="your-api-key"

Anahtarların bir erişim düzeyi vardır. Bir Read (okuma) anahtarı, bu kılavuzlardaki tüm sorguları ve raporları kapsar. Herhangi bir şey oluşturmak veya güncellemek, bir yoruma yanıt vermek ya da bir gönderi yayımlamak için Write (yazma) anahtarı gerekir. Bir yazma endpoint'ine Read anahtarı gönderdiğinizde endpoint, SY90016 hata koduyla HTTP 400 durumunu döndürür.

2. Konumlarınızı listeleyin

Diğer endpoint'ler bir konuma ID'si ile başvurur; bu nedenle önce mevcut konumlarınızı listeleyin. REST Authorization başlığı, API şemasını, ardından bir boşluk ve API anahtarınızı kullanır: Authorization: API <YOUR_API_KEY>.

List locations
curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY"

3. Yanıtı okuyun

REST API, yalnızca bir dizi yerine iç içe bir yanıt yapısı döndürür. İşlem adı data altında bulunur, liste sonuçları edges öğelerinden oluşan bir bağlantı yapısı olarak döndürülür ve her edge bir node içerir:

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "approved": "APPROVED",            "subCategoryName": "Restaurants"          }        }      ],      "pageInfo": {        "hasNextPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ=="      }    }  }}

Python SDK, üzerinde yineleme yapılabilen bir nesne sayfası döndürür. Node SDK, locations ve pageInfo döndürür. REST API'yi doğrudan çağırdığınızda data.allLocations.edges[].node değerini okuyun.

4. Sonuçların sayfalarında gezinin

Konumları ve yorumları listeleyen endpoint'ler cursor tabanlı sayfalama kullanır. first ile bir sayfa isteyin, ardından sonraki sayfayı almak için pageInfo.endCursor değerini after olarak iletin. SDK'lar tüm sayfaları sizin için okuyabilir.

Next page
curl "https://listingsapi.com/api/v4/locations?first=50&after=TG9jYXRpb246MTgwMDI4OQ==" \-H "Authorization: API $LISTINGSAPI_KEY"

Her endpoint bu şekilde sayfalama yapmaz. Bağlı hesaplar, yinelenen kayıt özetleri ve gönderiler, records dizisiyle birlikte page ve perPage kullanır. Her kılavuz, ilgili endpoint'lerin hangi sayfalama biçimini kullandığını belirtir.

5. İki ID türü

Her kaydın iki tanımlayıcısı vardır. id, TG9jYXRpb246MTgwMDI4OQ== gibi bir base64 dizesidir ve kodu çözüldüğünde Location:1800289 elde edilir. databaseId ise kodlanmamış sayı olan 1800289 değeridir.

base64 biçimindeki id değerini saklayın. Her yazma endpoint'i base64 ile kodlanmış ID'ler gerektirir ve webhook yüklerinde de bu değerler döndürülür. Yol parametresinde konum alan birçok okuma endpoint'i kodlanmamış sayıyı da kabul eder; her iki SDK da her iki biçimi kabul eder ve kodlamayı sizin için yapar.

6. Hatalar ve istek sınırları

Başarısız isteklere verilen yanıtlar, bir errors dizisiyle birlikte ilgili HTTP durumunu döndürür. Mesajın başında, Hata kodları bölümünde listelenen bir SY hata kodu bulunur:

JSON
{  "data": { "allLocations": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

İstek sınırları plana göre belirlenir ve istekler dakika, saat ve gün başına sayılır. Launch, dakikada 10 isteğe izin verir. Bir sınırı aştığınızda API, Retry-After başlığıyla birlikte 429 döndürür; hemen yeniden denemek yerine başlıkta belirtilen saniye kadar bekleyin. SDK'lar RateLimitError hatasını yükseltir ve aynı değere erişim sağlar. Ayrıntılar İstek sınırları bölümündedir.

Sonraki adımlar