API'nin okuduğu veriler

API, Gloriads ekranlarınızdaki rakamların aynısını okur. Hesabınızı veya reklamlarınızı asla değiştirmez.

Uç noktalar

Her parametre ve her alan, Try it düğmesiyle birlikte API referansında yer alır.

Dönemler

/summary, /timeline ve /reports/products bir dönemi kapsar. Şunlardan birini gönderin:

• Hiçbir şey gönderilmezse: paneldeki gibi last_30_days.
• Bir range tamamlanmış günleri, yani panelin topladığı günleri kapsar: last_30_days dün biten 30 gündür; this_month ve this_year de dün biter. Amazon bir satışı tıklamaya günler sonra ilişkilendirir; bu yüzden bugün hiçbir zaman tamamlanmış olmaz.
• today bugündür; ayın 1'inde this_month da bugündür (henüz tamamlanmış günü yoktur).
• all_time, Gloriads'in sakladığı en eski günden başlar ve bugünü de kapsar; paneldeki Tüm zamanlar gibi.
• Bugünü dahil etmek için start_date ve end_date gönderin; end_date = bugün.
• timezone (Europe/Paris, America/New_York…), “bugünün” hangi gün olduğunu belirler. Varsayılan UTC'dir.
• Her yanıt, kapsadığı günleri period içinde tekrarlar.

İki dönemi karşılaştırma

Paneldeki Karşılaştır gibi, /summary, /timeline veya /reports/products isteğine compare ekleyin:

Yanıta bir comparison eklenir. İçinde karşılaştırılan dönemin rakamları ve harcama, satışlar, ACOS, gösterimler, tıklamalar, CPC ve satın almalar için her birinin nasıl değiştiği yer alır:

"changes": {
  "spend": { "kind": "change", "percent": 18.2, "direction": "up", "tone": "neutral" },
  "acos": { "kind": "change", "percent": -6.5, "direction": "down", "tone": "good" }
}

• İki dönem de dün biter, paneldeki gibi: bugüne uzanan tarihlerden bugün çıkarılır ve period bunu belirtir.
• kind: "new", rakamın önceden sıfır olduğu anlamına gelir; kind: "none", karşılaştırılacak bir şey olmadığı anlamına gelir (satış olmadan ACOS).
• tone, paneldeki renkler gibi, değişimin iyi haber olup olmadığını söyler. Harcama her zaman neutral olur.
• all_time öncesinde hiçbir şey yoktur, today ise tamamlanmış bir gün içermez: bu durumda comparison, nedenini unavailable içinde söyler.
• Gloriads karşılaştırılan dönem için geçmiş tutmuyorsa, o dönemin rakamları null, history_covered ise false olur.

Filtreler

Bilinmeyen bir değer, onu adıyla belirten bir 400 yanıtıyla reddedilir; asla sıfırlarla yanıtlanmaz.

Bir dönemin toplamları

curl "https://gloriads.com/api/v1/summary?range=last_month&marketplaces=US" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "period": { "start_date": "2026-09-01", "end_date": "2026-09-30", "range": "last_month", "timezone": "UTC" },
  "currency": "USD",
  "spend": 13140.53,
  "sales": 46562.2,
  "acos": 28.22,
  "roas": 3.54,
  "impressions": 3945723,
  "clicks": 13973,
  "ctr": 0.35,
  "average_cpc": 0.94,
  "purchases": 1479,
  "conversion_rate": 10.58,
  "by_marketplace": [ … ],
  "by_ad_product": [ … ],
  "meta": { "data_last_date": "2026-10-09", "history_covered": true, "truncated": false }
}

• acos, ctr ve conversion_rate yüzdedir: 28.22, %28,22 anlamına gelir.
• purchases, konsoldaki Satın almalar gibi siparişleri sayar, adetleri değil.
• Tabanı olmayan bir oran (satış olmadan ACOS) null olur, asla 0 olmaz.

Gün gün veya ay ay

/timeline aynı dönemi ve filtreleri alır ve data içinde her gün veya her ay için bir nokta döndürür.

• granularity=auto (varsayılan), panelin grafiği gibi 92 güne kadar günleri, ötesinde ayları seçer.
• granularity=day, 92 günden uzun bir dönemde reddedilir.
• Hiç rakamı olmayan bir gün dışarıda bırakılır.

Ürün bazında

/reports/products, reklamı yapılan her ürün (ASIN) için bir satır döndürür; satırlar sort (varsayılan spend) ve order (varsayılan desc) değerlerine göre sıralanır.

• product_id: null, Amazon'un hiçbir ürüne bağlamadığı rakamları toplar; bunlar çoğunlukla Sponsored Brands'den gelir.
• title, Amazon'un ürün raporunun verdiği ürün adıdır; ürünün dönem içinde en çok harcama yaptığı pazaryerindeki adı. product_id: null için null olur; Gloriads hesabın ürün adlarını Amazon'dan henüz almadıysa da null olur.
• Satırlar sayfalar halinde gelir: bkz. Sınırlar ve hatalar.

Streaming TV

Diğer raporlar, paneldeki gibi Streaming TV'yi (Prime Video'daki ve yayın uygulamalarındaki TV reklamları) dışarıda bırakır: Amazon onu, bu raporların geldiği rapora koymaz. /reports/streaming-tv onu ayrı bir Amazon raporundan, tek bir pazaryeri için okur.

curl "https://gloriads.com/api/v1/reports/streaming-tv?marketplace_id=3478512345678901&range=last_30_days" \
  -H "Authorization: Bearer YOUR_API_KEY"

• En fazla 31 günlük bir dönem, son 95 gün içinde: Amazon'un bu rapor için koyduğu sınırlar.
• Bir dönem için yapılan ilk çağrı, Amazon raporu hazırlarken "status": "pending" yanıtı verebilir; bu genellikle birkaç dakika sürer. meta.retry_after_seconds kadar bekleyip tekrar çağırın. Rapor ardından 3 saat saklanır.
• Her kampanya harcaması, gösterimleri, cpm (1.000 gösterim başına maliyet), tıklamaları, satışları, satın almaları ve units_sold değeriyle gelir.
• Tutarlar USD cinsinden değil, pazaryerinin kendi para birimindedir.
• "status": "unavailable": Amazon bu hesaba Streaming TV sunmuyor; örneğin bir KDP yazarının hesabına.

Kampanyalar ve reklam grupları

İkisi de marketplace_id gerektirir: /marketplaces yanıtındaki bir id.

curl "https://gloriads.com/api/v1/campaigns?marketplace_id=3478512345678901&states=ENABLED" \
  -H "Authorization: Bearer YOUR_API_KEY"

• Sponsored Products, Sponsored Brands ve Display'in (görüntülü reklamlar) etkin ve duraklatılmış kampanyalarını listeler. Arşivlenen kampanyalar asla listelenmez.
• Bütçeler ve teklifler pazaryerinin kendi para birimindedir (/marketplaces içindeki currency_code).
• provenance, kampanyanın Gloriads tarafından oluşturulduğunu, değiştirildiğini veya hiç dokunulmadığını söyler.
• /ad-groups?campaign_id=… yalnızca bir kampanyanın reklam gruplarını tutar.
• Sayfa başına en fazla 1.000 satır (varsayılan 100).

Anahtar kelimeler, hedefler ve reklamlar

/targets ve /ads, tek bir kampanyanın içindekileri listeler. İkisi de marketplace_id ve campaign_id gerektirir; ad_group_id yalnızca o kampanyanın reklam gruplarından birini tutar.

curl "https://gloriads.com/api/v1/targets?marketplace_id=3478512345678901&campaign_id=28430987654321" \
  -H "Authorization: Bearer YOUR_API_KEY"

• /targets her anahtar kelimeyi eşleşme türüyle (match_type: EXACT, PHRASE, BROAD) listeler; ürün hedeflerini (ASIN'ler), kategorileri, otomatik hedefleme gruplarını ve negatifleri de. Her biri bid değeri ve durumuyla gelir. bid: null, reklam grubunun varsayılan teklifiyle teklif verdiği anlamına gelir.
• /ads her reklamı, reklamını yaptığı ürünlerle (product_ids) listeler.
• Sorduğunuz anda Amazon'dan okunurlar ve hiçbir rakam içermezler.
• Sponsored Products, Sponsored Brands ve Display. Arşivlenenler asla listelenmez.
• Sayfa başına en fazla 1.000 satır (varsayılan 100).

Kurallar ve işlem geçmişi

• /rules her kuralı listeler; en son düzenlenen önce.
• /rules/{rule_id}/runs, son çalıştırmaların her birinin neye baktığını ve neyi değiştirdiğini gösterir. Testler listelenmez.
• /activity, Gloriads'in Amazon'da yürüttüğü her işlemi listeler: oluşturulan veya kopyalanan bir kampanya, eklenen ürünler, bir kuralın değişiklikleri, bir geri alma. Bir kuralın çalıştırması her pazaryeri için bir kez, aynı rule_run_id ile görünür. tool=rule yalnızca kuralların işlemlerini tutar.
• /activity/{operation_id} tek bir işlemi okur: hâlâ çalışan bir işlemi izlemek için onu aralıklarla çağırın.
• /activity/{operation_id}/lines, işlemin yaptığını satır satır listeler: kampanya, reklam grubu, reklam veya hedef; oluşturuldu mu, değiştirildi mi, arşivlendi mi; her değerin önceki ve sonraki hali; bir satır başarısız olduğunda da Amazon'un hatası. Sayfa başına en fazla 500 satır: bir kuralın tek bir çalıştırması 5.000 satır içerebilir.

Rakamlar ne kadar güncel

• Bunlar panelinizin rakamlarıdır; aynı verilerden, aynı kodla okunur.
• Performans tutarları ABD doları (USD) cinsindendir. Amazon her pazaryerinin rakamlarını çevirir.
• Amazon satışları tıklamadan birkaç gün sonra ilişkilendirir; bu yüzden bir dönemin son günleri bir süre daha artmaya devam eder. meta.data_last_date, rakamların hangi güne kadar geldiğini söyler.
• Kampanyalar Amazon'dan pazaryeri başına en fazla 30 dakikada bir okunur. meta.synced_at ne zaman okunduğunu söyler. Bir pazaryeri için yapılan ilk çağrıda liste meta.syncing: true ile boş gelebilir: bir dakika sonra tekrar çağırın.
• Ürün rakamları günde bir kez yenilenir. Gloriads'in sakladığı geçmişten önce başlayan bir dönem meta.history_covered: false döndürür.
• Anahtar kelimeler, hedefler ve reklamlar her çağrıda Amazon'dan canlı okunur: meta.read_at ne zaman okunduklarını söyler.
• Streaming TV rakamları, Amazon raporlarını hazırladıktan sonra 3 saat saklanır: meta.report_ready_at raporun ne zaman hazırlandığını söyler.