Entegrasyon yönteminizi seçin

REST API'yi, Python ve Node SDK'larını, MCP sunucusunu ve webhook'ları uygulamanızın mimarisine ve entegrasyon gereksinimlerine göre karşılaştırın.

Tüm entegrasyon yöntemleri aynı API anahtarını ve temel URL'yi kullanır: https://listingsapi.com/api/v4. API istekleri için REST API'yi veya bir SDK'yı, olay odaklı güncellemeler için webhook'ları ve bir yapay zekâ ajanının yardımıyla entegrasyon yapmak için MCP sunucusunu kullanabilirsiniz.

1. API'yi nasıl çağıracağınızı seçin

REST API. Tüm endpoint'lere doğrudan HTTP üzerinden erişmek için REST API'yi kullanın. Uygulamanızın yanıtı ayrıştırması, her iki sayfalama yöntemini de işlemesi ve API hataları için errors[] dizisini incelemesi gerekir.

Python SDK. Python SDK'sını pip install listingsapi ile yükleyin. SDK, client.locations ve client.reviews gibi arayüzler üzerinden kaynak sınıfları sağlar. Cursor tabanlı sayfalamayı auto_paging_iter() ile yönetir, 429 veya 5xx yanıtı döndüren istekleri yeniden dener ve API isteğini göndermeden önce locations.add() içindeki konum veri yüklerini doğrular. Python SDK bölümünü okuyun.

Node SDK. Node SDK'sını npm install listingsapi-js ile yükleyin. Node.js 18 veya üzerini gerektirir, TypeScript tür tanımlarını içerir ve çalışma zamanı bağımlılığı yoktur. SDK metotları doğrudan istemci örneği üzerinden sunulur; örneğin client.fetchAllLocations(). Sayfalanmış sonuçların tamamını tek bir yanıtta almak için fetchAll: true ayarını yapın. Sayısal kimlikler, API istekleri gönderilmeden önce otomatik olarak Base64 ile kodlanır. Node SDK bölümünü okuyun.

MCP sunucusu. Claude, ChatGPT, Cursor ve Gemini gibi yapay zekâ istemcilerini Streamable HTTP kullanarak https://listingsapi.com/mcp adresindeki ListingsAPI MCP sunucusuna bağlayın. Yerel bir MCP sunucusu kurulumu gerekmez. Sunucu, ListingsAPI dokümantasyonunda arama yapmak, REST endpoint'lerini keşfetmek ve desteklenen API işlemlerini yürütmek için araçlar sunar. Kimlik doğrulama için API anahtarı veya OAuth kullanılır. İstemci yapılandırmasını, kullanılabilir MCP araçlarını ve her araç için gereken API anahtarı izin düzeyini görüntülemek üzere /dashboard/mcp adresini açın. MCP ile bir yapay zekâ ajanı bağlayın.

Webhook'lar. Olay odaklı güncellemeleri almak için webhook'ları REST API, SDK'lar veya MCP sunucusuyla birlikte kullanın. Bir konum, işletme kaydı, yorum veya gönderi değiştiğinde ListingsAPI, hesabınız için yapılandırılmış webhook URL'sine bir HTTP POST isteği gönderir. Bu, uygulamanızın güncellemeler için API'yi düzenli olarak sorgulamadan değişiklikleri işlemesini sağlar. Webhook'lara genel bakış bölümünü okuyun.

2. Kimlik doğrulama modelini anlayın

REST API ve SDK'lar, isteklerin kimliğini bir API anahtarı kullanarak doğrular. Anahtarı, API kimlik doğrulama şemasını kullanarak HTTP Authorization istek başlığında iletin:

Authorization: API <YOUR_API_KEY>

API anahtarları Read (okuma) veya Write (yazma) erişimine sahiptir. Read anahtarı, sorgulamalar ve raporlar dâhil okuma işlemlerine erişebilir. Kaynak oluşturan veya güncelleyen işlemler için Write anahtarı gerekir. Bir yazma endpoint'ine Read anahtarı gönderildiğinde endpoint, SY90016 hata koduyla birlikte HTTP 400 durumunu döndürür.

API anahtarlarının kapsamı tek bir hesapla sınırlıdır. Aynı hesaba ait anahtarlarla yapılan istekler, hesap düzeyindeki aynı istek hızı sınırı kotasını tüketir.

MCP sunucusu, OAuth ile kimlik doğrulamayı da destekler. MCP istemcileri, API anahtarı sağlamak yerine tarayıcı üzerinden OAuth kullanarak kimlik doğrulayabilir. REST API ve SDK isteklerinde kimlik doğrulama için Authorization başlığı kullanılır. Yapılandırma ayrıntıları için Kimlik doğrulama dokümantasyonuna bakın.

3. Sayfalama modellerini anlayın

REST listeleme uç noktaları, imleç tabanlı veya ofset tabanlı sayfalama kullanır. SDK'lar bu sayfalama modellerini soyutlar.

İmleç tabanlı uç noktalar first ve after parametrelerini kabul eder. Sonuçlar edges[].node aracılığıyla döndürülür ve pageInfo.endCursor, bir sonraki istek için imleci sağlar.

Ofset tabanlı uç noktalar page ve perPage parametrelerini kabul eder. Sonuçlar records[] içinde döndürülür ve pageInfo.totalRecords, mevcut kayıtların toplam sayısını bildirir.

Tür	Parametreler	Veri yükü	Kullanıldığı yerler
İmleç	`first`, `after`	`edges[].node`, `pageInfo.endCursor`, `pageInfo.hasNextPage`	Konumlar, konum araması, yorumlar
Ofset	`page`, `perPage`	`records[]`, `pageInfo.totalRecords`, `pageInfo.totalPages`	Bağlı hesaplar, öneriler, gönderiler, yinelenen işletme kayıtlarının özeti
Yok		Düz dizi	Ülkeler, alt kategoriler, plan kapsamındaki siteler, bir konumun fotoğrafları

Aşağıdaki örnekler, üç entegrasyon yöntemi kullanarak aynı konum listeleme işlemini gerçekleştirir. cURL uygulaması, uygulamanın API yanıt yapısını doğrudan ayrıştırmasını gerektirir.

List locations

curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY" # Read data.allLocations.edges[].node, then pass# data.allLocations.pageInfo.endCursor back as ?after= for the next page.

Tüm entegrasyon yöntemlerinde API hataları errors[] dizisinde döndürülür ve her hata mesajının başında bir SY hata kodu bulunur. Yazma istekleri success: false ile birlikte HTTP 200 döndürebilir; bu nedenle işlemin başarılı olduğunu kabul etmeden önce yanıt gövdesi kontrol edilmelidir.

Hesap hız sınırını aştığında API, Retry-After başlığıyla birlikte HTTP 429 döndürür. Launch planı dakikada en fazla 10 isteği destekler. Ayrıntılar için Hata kodları ve Hız sınırları belgelerine bakın.

4. Webhook ile periyodik sorgulama arasında seçim yapın

Uygulamanızın, tüm konumların her gece eşitlenmesi gibi belirli bir takvime göre kaynak durumuna ihtiyaç duyduğu veya gerekli olay için webhook desteğinin bulunmadığı durumlarda periyodik sorgulama kullanın. Uygulamanızın yeni bir yorum alınması, bir işletme kaydının durumunun değişmesi veya bir Google gönderisinin reddedilmesi gibi değişiklikleri gerçekleştiği anda işlemesi gerektiğinde webhook kullanın.

/dashboard/webhooks adresinde her hesap için bir webhook URL'si yapılandırın. Her webhook isteği, aşağıdaki biçimde bir X-ListingsAPI-Signature başlığı içerir:

X-ListingsAPI-Signature: sha256=<base64 HMAC>

Webhook uç noktası 5 saniye içinde bir 2xx yanıtı döndürmelidir. Başarısız teslimatlar yeniden denenmez.

Kaynağın güncel durumunu API'den almak için webhook olayını tetikleyici olarak kullanın. Webhook teslimatları yeniden denenmediğinden, kaçırılmış olabilecek güncellemeleri tespit etmek için zamanlanmış bir mutabakat süreci çalıştırın. Bir uygulama örneği için Webhook ile olaylara tepki verin belgesine bakın.

5. Bir bakışta karşılaştırın

Seçenek	En uygun kullanım alanı	Kimlik doğrulama	Sayfalama otomatik olarak yönetiliyor mu?	Daha fazla bilgi
REST	Tüm uç noktalar, tercih ettiğiniz teknoloji yığını ve HTTP istemcisi	API anahtarı başlığı	Hayır, imleçleri veya sayfaları siz takip edersiniz	Başlangıç
Python SDK	Arka uç işleri, veri işleme hatları, betikler	`LISTINGSAPI_KEY` üzerinden alınan API anahtarı	Evet, `SyncPage` ve `auto_paging_iter()`	Python SDK
Node SDK	TypeScript servisleri, sunucusuz uygulamalar, kontrol panelleri	`LISTINGSAPI_KEY` üzerinden alınan API anahtarı	Evet, `fetchAll: true`	Node SDK
MCP	Claude, Cursor ve diğer yapay zekâ asistanları	API anahtarı veya OAuth	Evet, araçlar sonuçları eksiksiz döndürür	`/dashboard/mcp`
Webhook'lar	Değişikliklere saniyeler içinde tepki verme	Her teslimatta HMAC imzası	Geçerli değil, her teslimatta bir olay	Webhook'lara genel bakış

Sonraki adımlar

Konum ekleyin: seçtiğiniz seçenekle ilk yazma çağrınızı yapın.
Webhook ile olaylara tepki verin: imzalı teslimatlar için bir alıcı kurun.
Python SDK ve Node SDK: yükleyin, yapılandırın ve metot tablolarını okuyun.
Kimlik doğrulama, Hız sınırları ve Hata kodları: tüm seçeneklerin ortak kullandığı üç başvuru kaynağı.