Listings APIListings API
Oturum aç

İşletme kaydı durumunu kontrol edin, canlı bağlantıları alın

Konumun tüm yayın platformu eşitleme durumlarını, canlı URL'leri, kapsamı ve sesli asistanları kontrol edin; sorgulama yerine webhook bildirimi alın.

Bir konum oluşturulduğunda, planınızdaki her yayın platformuna otomatik olarak bir işletme kaydı gönderilir. Bu kılavuz, her birinin hangi aşamada olduğunu nasıl okuyacağınızı, yayındaki işletme kayıtlarının URL'lerini nasıl alacağınızı ve webhook'lar ayarlandıktan sonra düzenli sorgulamayı nasıl durduracağınızı gösterir.

1. Bir konumun premium işletme kayıtlarını alın

GET /locations/{locationId}/listings/premium, plandaki her premium yayın platformu için bir kayıt döndürür. Bu, sayfalanmış bir liste değil, düz bir dizidir. İlgili /listings/additional yolu, ücretsiz dizinleri aynı yapıda döndürür; listingType sorgu parametresi yoktur.

Premium listings
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "listingsForLocation": [      {        "site": { "name": "Google Maps", "url": "maps.google.com" },        "syncStatus": "REQUIRING_ACTION",        "displayStatus": "Connect your account to sync the listing",        "actionRequired": true,        "listingUrl": null,        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:28Z"      },      {        "site": { "name": "BeLocalFocussed", "url": "belocalfocussed.com" },        "syncStatus": "SYNCED",        "displayStatus": "Synced",        "actionRequired": false,        "listingUrl": "https://belocalfocussed.com/jenny-home-26x0ffkd0e",        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:30Z"      }    ]  }}

Her satır, bir site değerini makine tarafından okunabilir bir syncStatus ve insan tarafından okunabilir bir displayStatus ile eşleştirir. lastUpdate, satırın en son ne zaman değiştiğini belirtir; bu da ilerlemeyen bir gönderimi tespit etmek için yararlıdır.

2. Her yayın platformunun durumunu okuyun

Koşullu dallanma için kullanılacak alan syncStatus alanıdır. displayStatus, kullanıcıya gösterilecek metindir ve syncIssue, varsa yayın platformunun gerekçesini içerir.

syncStatusAnlamıYapılması gerekenler
AVAILABLEGönderilmeye hazır, henüz başlanmadı.Hiçbir şey yapmanız gerekmez. Kendiliğinden ilerler.
IN_PROGRESSYayın platformuna gönderildi, yanıt bekleniyor.Bekleyin. Haftalar geçtiyse lastUpdate değerini kontrol edin.
PENDING_APPROVALYayın platformu gönderimi aldı ve inceliyor.Bekleyin.
SYNCED veya COMPLETEDYayında. listingUrl alanı doldurulmuştur.Bağlantıyı alın (3. adım).
REQUIRING_ACTIONİlerlemesi için sizin işlem yapmanız gerekiyor. actionRequired değeri true.displayStatus değerini okuyun, ardından İşletme kaydı hatalarını bulun ve düzeltin bölümüne bakın.
FAILEDYayın platformu gönderimi reddetti veya işleyemedi.syncIssue değerini okuyun, konumu düzeltin ve yeniden sorgulayın.
CANNOT_SUBMITBu yayın platformu bu konumu hiçbir şekilde kabul edemez.Genellikle yayın platformunun desteklemediği bir ülke veya kategori söz konusudur.

Google Maps ve Facebook, ilgili yayın platformunun hesabı bağlanana kadar REQUIRING_ACTION durumunda kalır: Google Maps için bir Google Business Profile, Facebook için ise bir Facebook Sayfası bağlanmalıdır. Bu, yeni bir konum için beklenen bir durumdur, hata değildir.

Apple Maps bağlantı gerektirmez. Konum sahibi doğrulanmış bir Apple Business kuruluş hesabını bağlamadıysa ListingsAPI, konumu kendi Apple Business Connect hesabı üzerinden gönderir ve Apple, gönderimi yayınlamadan önce doğrular. Apple Business Connect'i bağlayın bölümüne bakın.

listingUrl yalnızca yayındaki satırlarda ayarlanır. SYNCED (ve COMPLETED) durumlarına göre filtreleyin ve URL'yi site adıyla birlikte saklayın; böylece bir "yayında görüntüle" listesi oluşturabilir veya URL'yi kendi kaydınızla ilişkilendirerek saklayabilirsiniz.

Live links
curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '[.data.listingsForLocation[]       | select(.listingUrl != null)       | {site: .site.name, url: .listingUrl}]'

listingUrl değeri null olan bir SYNCED satırıyla karşılaşılabilir: bazı dizinler herkese açık bir sayfa URL'si sunmaz. Durumu esas alın ve bağlantıyı isteğe bağlı olarak değerlendirin.

4. Bir kapsam özeti oluşturun

Satırları syncStatus değerine göre saymak, her konum için tek satırlık bir genel durum göstergesi sağlar: kaç yayın platformunda kaydın yayında olduğunu, kaçında işlemlerin hâlâ sürdüğünü ve kaçında ilerlemenin engellendiğini gösterir. Kontrol panelinde gösterilecek sayı budur.

Coverage
curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.listingsForLocation      | group_by(.syncStatus)      | map({status: .[0].syncStatus, count: length})'

Bunu birçok konum için çalıştırmak üzere GET /locations sonuçlarını sayfa sayfa alın ve her konum için premium uç noktasını bir kez çağırın. Her çağrı istek hızı limitinizden sayılır; bu nedenle çağrılar arasında zaman bırakın ve 429 yanıtı aldığınızda Retry-After değerine uyun. İşletme kaydı hatalarını bulun ve düzeltin bölümü, bu döngüyü tek bir hesabın tamamını kapsayan bir tarama olarak gösterir.

5. Sesli asistanları kontrol edin

Sesli asistanların (Google Assistant, Alexa, Siri, Cortana, Bixby) daha küçük bir durum kümesine sahip kendi endpoint'i vardır: GET /locations/{locationId}/voice-assistants. Google Assistant, Google bağlantısına bağlıdır; bu nedenle bu bağlantısı olmayan bir konum burada da ilgilenmenizi gerektirir. Siri sonuçları, konumun Apple Maps işletme kaydından gelir.

Voice assistants
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/voice-assistants \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "voiceAssistantsForLocation": [      {        "voiceIdentifier": "GOOGLE_ASSISTANT",        "name": "Google Assistant",        "syncStatus": "REQUIRING_ACTION",        "actionRequired": true,        "syncIssue": null,        "errors": []      },      {        "voiceIdentifier": "SIRI",        "name": "Siri",        "syncStatus": "IN_PROGRESS",        "actionRequired": false,        "syncIssue": null,        "errors": []      }    ]  }}
syncStatusAnlamı
NOT_SUBMITTEDHenüz asistana gönderilmedi.
IN_PROGRESSGönderim devam ediyor.
REQUIRING_ACTIONSizin işlem yapmanız bekleniyor; syncIssue öğesini okuyun.
LIVEYayımlandı.

Sesli asistanlar için yayındaki kayda ait bir bağlantı yoktur; LIVE son durumdur.

6. Düzenli sorgulama yerine webhook olaylarını alın

/dashboard/webhooks konumunda yapılandırılmış bir webhook URL'niz varsa, bir konum için yapılan yayın platformu gönderimi son duruma her ulaştığında listing.submission olayı tetiklenir. Bu olay, status (success, incomplete veya canceled), site ve başarı durumunda 3. adımda aldığınız URL ile aynı olan live_link bilgisini taşır.

Route listing.submission
import base64 def handle(payload: dict) -> None:  if payload["event"] != "listing.submission":      return   data = payload["data"]  # "TG9jYXRpb246Mjc5Mzgx" -> "Location:279381"  global_id = base64.b64decode(data["location_id"]).decode()  database_id = int(global_id.split(":")[1])   site = data["site"]["name"]  status = payload["status"]   if status == "success":      live_link = payload.get("live_link")      save_live_link(database_id, site, live_link)  elif status == "incomplete":      flag_for_review(database_id, site, payload.get("error_message"))

5 saniye içinde 200 ile yanıt verin ve işlemi daha sonra yapın; yeniden deneme yapılmaz. Alıcının temel yapısı ve imza kontrolü için Webhook'larla olaylara tepki verin bölümüne bakın.

Sonraki adımlar