Yorumlar

Tüm yorum uç noktaları için cURL, Python ve Node örnekleri: kaynaklar, ayarlar, liste, özet, ayrıntı, yanıtlama, düzenleme, arşivleme, ifadeler ve analiz.

Yorumlar, müşterilerin Google, Facebook ve Yelp'te bıraktığı yıldız puanları ve metinlerdir. API her birinin bir kopyasını saklar, yanıt vermenizi sağlar ve yorum analizlerini hesaplar. REST yollarında reviews kullanılır; yanıt anahtarlarında ve referans sayfası başlıklarında ise aynı nesnenin eski dahili adı olan interactions kullanılır. Bu kılavuzun tamamında yorum terimi kullanılır. Okuma işlemleri için Read (okuma) anahtarı gerekir. Yanıtlama, düzenleme, arşivleme ve ayarları değiştirme işlemleri için Write (yazma) anahtarı gerekir; bir yazma işleminde Read anahtarı kullanılması, SY90016 ile birlikte 400 döndürür.

Bir bakışta uç noktalar

Planınızın izin verdiği yorum kaynaklarını listeleyin

GET /reviews/site-config, hesabın erişim hakkına sahip olduğu yorum platformlarının kataloğunu döndürür. Parametre almaz ve hesap kapsamındadır; bu nedenle her konum için çağırmak yerine önbelleğe alın. siteUrl değerleri, bu kaynaktaki diğer tüm filtrelerin kabul ettiği ana makine adlarıdır.

curl https://listingsapi.com/api/v4/reviews/site-config \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionSiteConfig": [      { "site": "Google", "siteUrl": "maps.google.com" },      { "site": "Facebook", "siteUrl": "facebook.com" },      { "site": "Yelp", "siteUrl": "yelp.com" }    ]  }}

data.interactionSiteConfig[] değerini okuyun. Örnek, Launch planındaki bir hesaba aittir; tam küme, plana ve sektöre bağlıdır. Listeleme uç noktalarındaki siteUrls filtresi için ve ayarları düzenlerken siteUrls[].name için siteUrl kullanın.

Bir konum için yapılandırılmış kaynakları listeleyin

GET /locations/{locationId}/reviews/settings, planın desteklediği her platform için yorumların alındığı URL ile birlikte bir kayıt döndürür. Aşağıdaki düzenleme uç noktasının okuma tarafıdır. Yol, base64 id'yi veya düz sayıyı kabul eder.

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews/settings \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionsSetting": {      "siteSettings": [        { "name": "maps.google.com", "url": null },        { "name": "facebook.com", "url": null },        { "name": "yelp.com", "url": null }      ]    }  }}

data.interactionsSetting.siteSettings[] değerini okuyun. url değerinin null olmaması, platformun bağlı olduğu ve yorumların o sayfadan alındığı anlamına gelir. url değerinin null olması, platformun kullanılabilir olduğu ancak yapılandırılmadığı anlamına gelir. Google ve Facebook, bu hesapları OAuth aracılığıyla bağladığınızda otomatik olarak doldurulur ve düzenleme uç noktasıyla üzerlerine yazılamaz. Yelp açıkça belirtilmelidir.

Bir konumun yorum ayarlarını düzenleyin

POST /locations/reviews/settings/edit, bir konumun hangi kaynaklarda izleneceğini ve olumlu sayılan yıldız puanını ayarlar. Alanlar bir input sarmalayıcısının içine değil, doğrudan gövdeye yerleştirilir. Bir kaynak eklemek, veri toplama işlemini kuyruğa alır; bu nedenle yeni sitenin yorumları bu yanıtta değil, daha sonra gelir.

curl -X POST https://listingsapi.com/api/v4/locations/reviews/settings/edit \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "locationId": "TG9jYXRpb246MTgwMDI4OQ==",  "positiveInteractionThreshold": 4,  "siteUrls": [    { "name": "maps.google.com", "url": null },    { "name": "yelp.com", "url": "https://www.yelp.com/biz/blue-bottle-coffee-oakland" }  ]}'

{  "data": {    "editInteractionsSetting": {      "errors": null,      "interactionSetting": {        "locationId": "1800289",        "positiveInteractionThreshold": 4,        "siteSettings": [          { "name": "maps.google.com", "url": null, "monitored": true, "canRespond": true },          { "name": "yelp.com", "url": "https://www.yelp.com/biz/blue-bottle-coffee-oakland", "monitored": true, "canRespond": false }        ]      }    }  }}

Kaydedilmiş seçim için data.editInteractionsSetting.interactionSetting.siteSettings[] değerini okuyun. monitored, kaynağın etkin olduğunu belirtir; canRespond ise API aracılığıyla orada işletme sahibi yanıtlarının yayımlanıp yayımlanamayacağını belirtir. Erişilemeyen bir URL veya planın kapsamı dışındaki bir site gibi, doğrulama sırasında reddedilen bir kaynak, ayar değiştirilmeden errors içinde geri döner; bu nedenle 200 yanıtında errors değerini kontrol edin. SDK'lar bu durumda ValidationError hatasını oluşturur.

Bir konumun yorumlarını listeleyin

GET /locations/{locationId}/reviews, data.interactions altında bulunan ve en yeni kayıtları önce sıralayan cursor tabanlı bir bağlantıdır. first varsayılan olarak 20'dir, bu nedenle tek bir çağrı hiçbir zaman tüm geçmişi kapsamaz. Dizi filtreleri, sorgu dizesinde JSON dizeleri olarak yer alır ve URL kodlamasıyla kodlanmalıdır; cURL örneği bunun için -G ile --data-urlencode kullanır.

Bunlara ek olarak, referans sayfasında listelenen isteğe bağlı category, categories ve tek değerli ratingFilter.

curl -G "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'ratingFilters=[1,2]' \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'sortOrder=["NEWEST_FIRST"]' \--data-urlencode 'first=25'

{  "data": {    "interactions": {      "pageInfo": { "hasNextPage": true, "endCursor": "SW50ZXJhY3Rpb246MV8xNTU0..." },      "edges": [        {          "node": {            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",            "source": "maps.google.com",            "content": "nice place for family together",            "authorName": "vaibhav nakate",            "rating": 5,            "date": "2019-04-02T22:11:13.036997+00:00",            "type": "Review",            "responded": false,            "responseCount": 0,            "canRespond": true,            "permalink": "https://maps.google.com/maps?cid=..."          },          "cursor": "SW50ZXJhY3Rpb246MV8xNTU0..."        }      ],      "totalCount": 425    }  }}

edges[].node verisini okuyun. Yanıt verirken id değerini iletirsiniz; canRespond ise ilgili kaynağın işletme sahibi yanıtlarını kabul edip etmediğini belirtir. totalCount, bu sayfadaki değil, tüm sonuç kümesindeki eşleşmelerin sayısıdır. hasNextPage değeri false olduğunda veya bir sayfa boş edges döndürdüğünde sayfalamayı durdurun; en eski yoruma denk gelen bir sınırın ardından 1 boş sayfa gelir.

Toplu listeyle tüm konumları tarayın

GET /rollup_interactions, anahtarın görebildiği tüm konumları kapsayan, data.rollupInteractions altında bulunan aynı cursor tabanlı bağlantıdır ve her düğümde sayısal bir locationId bulunur. Konum bazındaki listeyle aynı filtreleri kabul eder. Konum filtresi yoktur; locationIds argümanı reddedilmez, yok sayılır. Her iki SDK de henüz bu uç nokta için bir sarmalayıcı sunmadığından, örneklerde requests ve fetch kullanılır.

curl -G "https://listingsapi.com/api/v4/rollup_interactions" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'sortOrder=["NEWEST_FIRST"]' \--data-urlencode 'first=50'

{  "data": {    "rollupInteractions": {      "pageInfo": { "hasNextPage": true, "hasPreviousPage": false },      "edges": [        {          "node": {            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",            "source": "maps.google.com",            "content": "Excellent service, highly recommend.",            "rating": 5,            "responded": false,            "canRespond": true,            "locationId": 1800289          },          "cursor": "SW50ZXJhY3Rpb246OWUyNmQyYTg="        }      ],      "totalCount": 1284    }  }}

Düğümleri, mağazanın databaseId değeri olan locationId değerine göre gruplandırın. Toplu listenin pageInfo verisi endCursor içermeyebilir, bu nedenle son edge'in cursor değerini after olarak alın; bu iki değer eşdeğerdir. Geçmişi yeniden okumak yerine zamanlanmış çalıştırmaları startDate ve endDate ile sınırlandırın ve 429 durumunda Retry-After değerine uyun.

Yorumları id ile getirin

GET /reviewDetails, saklanan yorumların güncel kopyalarını sayfalama olmadan döndürür. Yanıt, data.interactionDetails.interactions altında düz bir dizidir; edges veya pageInfo içermez ve her yorum kendi responses değerini içerir. Bir izleme listesini güncel verilerle yeniden doldurmak ve düzenleme veya arşivleme için gereken responseId değerini bulmak için kullanın.

curl -G "https://listingsapi.com/api/v4/reviewDetails" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'interactionIds=["b2fa765e-c62b-4e0b-b1d6-1c67c855f5e0"]'

{  "data": {    "interactionDetails": {      "interactions": [        {          "id": "b2fa765e-c62b-4e0b-b1d6-1c67c855f5e0",          "source": "maps.google.com",          "content": "Great place for dessert!",          "rating": 5,          "responded": true,          "responseCount": 1,          "canRespond": true,          "responses": [            {              "id": "2090753a-ece6-4837-8336-8494ad308523",              "content": "Thank you so much for the kind words!",              "interactionStatus": "CONFIRMED",              "editedResponse": false            }          ]        }      ]    }  }}

responses[].id, düzenleme ve arşivleme uç noktaları için responseId değeridir. Başka bir hesaba ait id kullanıldığında interactionDetails: null ve SY90001 hatasıyla birlikte 200 döndürülür, bu nedenle indeksle erişmeden önce null olup olmadığını kontrol edin.

Yorum ve yanıt alanları

Öznitelikler referansı, yorum nesnesindeki ve yanıt nesnesindeki tüm alanları listeleyen, yalnızca dokümantasyon amaçlı bir sayfadır. En çok kullanacağınız alanlar:

responses[] içindeki her yanıt id, content, authorName, date, interactionStatus, editedResponse, respondedWith (şablon id değeri) ve remarks (hata ayrıntısı) alanlarını içerir. interactionStatus şu durumlardan geçer:

İşletme sahibi yanıtı yayımlayın

POST /locations/reviews/respond, kaynak platformda herkese açık bir yanıt yayımlar. Alanlar doğrudan gövdeye eklenir. Yanıt hemen kabul edilir ve eşzamansız olarak iletilir; bu nedenle interactionStatus başlangıçta CREATED değerindedir. Önce yorumdaki canRespond alanını kontrol edin.

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "interactionId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responseContent": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!"}'

{  "data": {    "respondToInteraction": {      "interaction": {        "id": "2090753a-ece6-4837-8336-8494ad308523",        "interactionId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",        "content": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!",        "interactionStatus": "CREATED",        "editedResponse": false      },      "errors": null    }  }}

interaction.id değerini saklayın: düzenleme ve arşivleme için kullanılan responseId değeridir. Reddedilen bir yanıt, data.respondToInteraction içindeki errors alanı doldurulmuş olarak 200 ile döner; bu nedenle gövdeyi okuyun; SDK'lar ValidationError hatasını tetikler. Kısa bir süre bekledikten sonra yorumu id ile yeniden okuyarak yanıtın COMPLETED veya CONFIRMED durumuna ulaştığını görün.

Bir yanıtı düzenleyin

POST /locations/reviews/respond/edit, mevcut bir yanıtın metnini değiştirir. Düzenleme platforma yeniden gönderilir; bu nedenle interactionStatus tekrar CREATED değerine döner ve düzenleme platforma ulaştığında editedResponse, true olur. Tek yanıta izin veren platformlarda arşivleyip yeniden yayımlamak yerine bu yöntemi tercih edin.

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond/edit \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "reviewId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responseId": "2090753a-ece6-4837-8336-8494ad308523",  "responseContent": "Thank you again: we have updated our reply to include our new store hours."}'

{  "data": {    "editResponse": {      "status": "true",      "reviewId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",      "responseId": "2090753a-ece6-4837-8336-8494ad308523"    }  }}

Düzenleme kabul edildiğinde status, "true" dizesidir. Bir ayrıntı çağrısıyla yeni metni doğrulayın ve yanıtın interactionStatus alanını kontrol edin.

Bir yanıtı arşivleyin

POST /locations/reviews/respond/archive, bir yanıtı bizim tarafımızda yorum için takip edilen responses alanından kaldırır. Bu, mantıksal bir silme işlemidir: Google, Yelp veya Facebook'ta zaten yayımlanmış olan bir yanıt orada kalır. Başarısız olan veya yerini başka bir taslağın aldığı bir taslağı temizlemek için bu işlemi kullanın; yayımlanmış içerikler için düzenleme işlemini kullanın.

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond/archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "responseId": "2090753a-ece6-4837-8336-8494ad308523" }'

{  "data": {    "archiveResponse": {      "status": "true"    }  }}

Arşivlemeden sonra yorumun responseCount değeri azalır ve responded kalan yanıtları yansıtır.

Müşterilerin tekrarladığı ifadeleri listeleyin

GET /review-phrases, data.newReviewPhrases alanında düz bir dizi döndürür; tekrarlanan her ifade için bir öğe bulunur ve her öğenin istatistikleri yalnızca o ifadeyi içeren yorumlar üzerinden hesaplanır. Sonuçlar sayfalandırılmaz; phraseCount ile sınırlandırın. Her filtre isteğe bağlıdır ve filtreler birlikte kullanılabilir; dolayısıyla ratingFilters=[1,2] ile bir startDate kullanıldığında geçen çeyrekteki şikâyetler elde edilir.

Bunlara ek olarak, referans sayfasında listelenen isteğe bağlı categories ile kullanımdan kaldırılmış tek değerli category ve ratingFilter.

curl -G "https://listingsapi.com/api/v4/review-phrases" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'locationIds=[1800289]' \--data-urlencode 'ratingFilters=[1,2]' \--data-urlencode 'startDate=2026-06-01' \--data-urlencode 'endDate=2026-08-31' \--data-urlencode 'phraseCount=10'

{  "data": {    "newReviewPhrases": [      {        "reviewPhrase": "friendly staff",        "phraseStats": {          "stats": [            { "name": "total-reviews", "value": 46, "delta": 12.5, "abs": 5 },            { "name": "overall-rating", "value": 4.7, "delta": 1.1, "abs": 0.05 }          ]        }      },      {        "reviewPhrase": "long wait",        "phraseStats": {          "stats": [            { "name": "total-reviews", "value": 11, "delta": 37.5, "abs": 3 },            { "name": "overall-rating", "value": 2.9, "delta": -8.4, "abs": -0.27 }          ]        }      }    ]  }}

total-reviews ifadenin ne sıklıkta geçtiğini, overall-rating bu yorumların ortalama puanını, delta önceki döneme göre yüzde değişimi ve abs mutlak değişimi gösterir. SY90003 içeren bir 403, anahtarın istenen konumlardan birini okuyamadığı anlamına gelir.

Bir konumun yorum KPI'larını okuyun

GET /locations/{locationId}/review-analytics-overview, data.interactionsAnalyticsStats.stats alanında dört istatistik döndürür. Tarih aralığı isteğe bağlıdır; değerlerin ve bu değerlerdeki değişimlerin hesaplandığı zaman aralığını daraltır. Her delta, aynı uzunluktaki önceki döneme göre yüzde değişimdir.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-overview?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionsAnalyticsStats": {      "stats": [        { "name": "total-reviews", "value": 128, "delta": 6.67 },        { "name": "new-reviews", "value": 9, "delta": -25 },        { "name": "overall-rating", "value": 4.43, "delta": 2.31 },        { "name": "review-response-rate", "value": 62.5, "delta": 12.5 }      ]    }  }}

Önceki dönemi bulunmayan yeni bir hesapta delta değeri 100 olarak raporlanır; bu nedenle ilk aydaki değişimleri büyüme olarak yorumlamayın.

Günlük yorum zaman çizelgesini alın

GET /locations/{locationId}/review-analytics-timeline, data.interactionsChartData.data içinde her gün için bir kayıt döndürür. Grafiğin tarih aralığının önemli olduğu durumlarda startDate ve endDate parametrelerini iletin; bunları belirtmezseniz hizmet kendi zaman aralığını seçer. Tek bir kaynağı ayrı olarak çizmek için site ekleyin.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-timeline?startDate=2026-08-01&endDate=2026-08-31&site=maps.google.com" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionsChartData": {      "data": [        { "date": "2026-08-01", "interactionCount": 4, "averageRating": 4.5 },        { "date": "2026-08-02", "interactionCount": 0, "averageRating": null },        { "date": "2026-08-03", "interactionCount": 7, "averageRating": 4.285714285714286 }      ]    }  }}

interactionCount değerini çubuklarla, averageRating değerini ise çizgiyle gösterin. Ortalama yalnızca o güne aittir, kümülatif değildir ve yorum olmayan günlerde null değerini alır; bu nedenle sıfır çizmek yerine boşluk bırakın.

Yorum analitiğini kaynağa göre ayırın

GET /locations/{locationId}/review-analytics-sites-stats, data.interactionsSitesStats.stats içinde her yorum kaynağı için bir kayıt döndürür. Ortalamayı hangi platformun değiştirdiğini bulmak için bunu kullanın.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-sites-stats?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionsSitesStats": {      "stats": [        {          "key": "google",          "siteUrl": "maps.google.com",          "averageRating": { "value": 4.6, "delta": 2.2 },          "totalInteractions": { "value": 412, "delta": 6.1 },          "newInteractions": { "value": 24, "delta": 33.3 },          "recency": "2026-09-06T14:12:00Z",          "baseRating": 4.5,          "baseInteractions": 388,          "humanizedRecency": "3 days ago"        },        {          "key": "facebook",          "siteUrl": "facebook.com",          "averageRating": { "value": 4.1, "delta": -1.4 },          "newInteractions": { "value": 0, "delta": -100 },          "recency": null,          "humanizedRecency": null        }      ]    }  }}

averageRating, totalInteractions ve newInteractions alanlarının her biri bir value ve bir delta içerir; baseRating ve baseInteractions, farkın ölçülmesinde başlangıç alınan dönemin başındaki değerlerdir. recency en yeni yorumun zaman damgasıdır; kaynak hiç yorum döndürmediyse null değerini alır. newInteractions değerinin 0 olması ve recency değerinin aylar öncesine ait olması genellikle kaynak bağlantısının güncelliğini yitirdiği anlamına gelir; bu nedenle konumun kaynaklarını kontrol edin.

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

Yazma işlemleri, data.<op> içindeki errors alanı doldurulmuş olarak 200 da döndürebilir; bu nedenle her yazma işleminin yanıt gövdesini okuyun. Tam liste Hata kodları bölümündedir.

Sonraki adımlar

• Yorumları alın: bekleyen yorumlar için bir kuyruk oluşturun ve webhook aracılığıyla bildirim alın.
• Yorumlara yanıt verin: yanıtlayın, doğrulayın, düzenleyin, arşivleyin.
• Yorum analitiği: puan kartı, grafik, şikâyet paneli, günlük anlık görüntüler.
• Analitik: aynı konum için Google, Facebook ve Bing profil metrikleri.
• Referans ana sayfası: Yorumlar. SDK'lar: Python yorumları, Node yorumları.