Geliştiriciler

Tayf API

Haber kümeleri ve kaynak kaydı için anahtarlı, salt okunur bir JSON API. Yanıtlar CC BY-SA 4.0 lisansıyla, Tayf'a atıf verilerek kullanılabilir.

Hızlı başlangıç

Her istek bir Authorization: Bearer $TAYF_API_KEY başlığı taşır. Anahtarınızı ortam değişkeni olarak saklayın, koda gömmeyin.

curl -sS "https://www.tayfhaber.com/api/v1/clusters?limit=10" \
  -H "Authorization: Bearer $TAYF_API_KEY"

import os
import requests

resp = requests.get(
    f"https://www.tayfhaber.com/api/v1/clusters",
    headers={"Authorization": f"Bearer {os.environ['TAYF_API_KEY']}"},
    params={"limit": 10},
    timeout=10,
)
resp.raise_for_status()
data = resp.json()
for cluster in data["clusters"]:
    print(cluster["title"], cluster["url"])

const res = await fetch("https://www.tayfhaber.com/api/v1/clusters?limit=10", {
  headers: { Authorization: "Bearer " + process.env.TAYF_API_KEY },
});
if (!res.ok) throw new Error("HTTP " + res.status);
const data = await res.json();
for (const cluster of data.clusters) {
  console.log(cluster.title, cluster.url);
}

Kimlik doğrulama

Her /api/v1/* isteği Authorization: Bearer tayf_<40 hex> başlığı taşımalıdır (şema büyük/küçük harfe duyarsızdır).

401 — başlık eksik, biçimsiz veya anahtar bilinmiyor: Missing or invalid API key.
403 — anahtar iptal edilmiş: API key revoked.

Anahtarınızı tarayıcıda çalışan koda gömmeyin; CORS açık olsa da anahtar herkese görünür olur.

Kullanım sınırları

Katman	Dakikada	Günde	Nasıl alınır
Ücretsiz	60	2.000	E-postayla başvurun; anahtar elle verilir.
Ortak	600	50.000	Yüksek hacim ve toplu erişim için yazın.

Günlük sayaç UTC gece yarısında sıfırlanır ve tek küresel sınırdır.
Dakikalık sınır sunucu örneği başınadır.
Tek bir IP adresi, katmandan bağımsız olarak dakikada yaklaşık 1800 istekle sınırlıdır.
429 yanıtı details.retryAfterMs taşır.
Hizmet düzeyi taahhüdü (SLA) yoktur.

Uç noktalar

60/dk · 2.000/gün (free)

GET/api/v1/clusters

Haber kümelerini listele

Ad	Yer	Açıklama
since	query	updated_at için alt sınır, tam ISO 8601 zaman damgası (T ve saniye ile). Varsayılan: şimdi−24 saat. 7 günden eski değerler sessizce 7 güne çekilir.
limit	query	Döndürülecek en çok küme sayısı, 1–100 arası tam sayı (varsayılan 50).

Yalnızca üyelerinin en az %60'ı politika/son dakika kategorisinde olan kümeler döner; ekonomi ve spor kümeleri bu uç noktada yoktur.
since, updated_at için alt sınırdır; 7 günden eski değerler sessizce 7 güne çekilir.
Yanıt, limit'ten az küme içerebilir: en yeni en çok 300 aday arasından süzülür.
title, özgün başlığa geri düşebilir; bu durumda başlığın hakları ilgili yayın kuruluşuna aittir.
blindspot_side, haberi YAPAN tarafın kategorisidir — sessiz kalan taraf değil.
is_blindspot, sitenin kör nokta geri çağırma (recall veto) kuralını uygular.
sources listesi toplayıcı ve niş türündeki kaynakları da içerir.

200400401403429500

GET/api/v1/clusters/{id}

Tek bir kümeyi getir

Ad	Yer	Açıklama
id *	path	Küme UUID'si.

Tek küme okumasında siyaset süzgeci uygulanmaz; arşivlenmiş kümeler 404 döner.

200400401403301404429500

GET/api/v1/sources

Kaynak kaydını listele

Yalnızca etkin kaynaklar döner, isme göre sıralı.

200401403429500

GET/api/v1/sources/{slug}/profile

Bir kaynağın 30 günlük kapsama profili

Ad	Yer	Açıklama
slug *	path	Kaynağın kısa adı (/api/v1/sources yanıtındaki slug); küçük harf, rakam ve tire, en çok 64 karakter.

Kaynak sayfasındaki Kapsama karnesinin anahtarlı yansımasıdır: kaynağın son 30 günde yayımladığı ve Tayf'ın bir kümeye eşleştirdiği haberlerden hesaplanır; kümelenmeyen (siyaset dışı) haberler sayılmaz.
Sayılar günde bir kez yeniden hesaplanır; window_start, window_end ve computed_at hesaplamanın zamanını verir. Henüz hesaplanmamış bir kaynak için profile null döner.
Sitedeki eşikler aynen uygulanır: 20 kümeden azsa yalnızca n_clusters döner, diğer sayılar null olur; 10 çok kaynaklı haberden azsa co_covering_zones null olur.
co_covering_zones: kaynağın yazdığı çok kaynaklı haberlerden kaçında her bölgeden (iktidar/bağımsız/muhalefet) en az bir başka kaynağın da yazdığı; bir haber birden çok bölgede sayılabilir.
public_blindspot_appearances: sitenin kör nokta tanımına (geri çağırma vetosu uygulanmış) giren haberlerden kaçında bu kaynağın da haberi var; public_blindspot_same_side: bunların kaçında haberi ağırlıkla yazan bölge kaynağın kendi bölgesiydi.
Bu uç nokta tık tuzağı puanı veya başlık değişikliği verisi içermez.

200400401403404429500

GET/api/v1/kap/pickup

KAP bildirimlerinin medyada yankısı

Ad	Yer	Açıklama
ticker *	query	2–6 büyük harf/rakamdan oluşan hisse kodu (girişte büyük harfe çevrilir).
since	query	KAP bildirimi için alt sınır, tam ISO 8601 zaman damgası. Varsayılan: 30 gün önce. Gelecekteki bir değer reddedilir (400); 90 günden eski değerler sessizce 90 güne çekilir.
limit	query	Döndürülecek en çok bildirim sayısı, 1–100 arası tam sayı (varsayılan 50), en yeniden en eskiye.

"/ekonomi/[ticker]" sayfasındaki "Medyada yankı" panelinin anahtarlı yansımasıdır: her KAP bildirimi için, bildirimden sonraki 48 saat içinde hangi bölgeden (iktidar/bağımsız/muhalefet) ne kadar basın yankısı oluştuğunu döner.
Pencere kuralı harfiyendir: her bildirim, kendi [bildirim_zamanı, bildirim_zamanı+48s) penceresinde yayınlanan her haberi sayar; bildirimden önceki bir haber asla yankı sayılmaz. İki bildirim 48 saat içine düşerse aynı haber her ikisine de sayılabilir — bu, her kayıttaki overlapping_disclosures alanıyla görünür kılınır, sessizce tekilleştirilmez.
relevance_filter: Jev'in ticker_relevance gölge modelinin 0.2 altında puanladığı haberler dışlanır (ör. aynı adlı bir siyasi parti-hisse kodu çakışması); puanlanmamış haberler her zaman tutulur. İlgi puanı sorgusu başarısız olursa uç nokta 500 dönmek yerine relevance_filter.applied: false ile açık başarısız olur.
disclosure_coverage görünümü asla sorgulanmaz (üretimde 60 saniyede zaman aşımına uğradı); sorgu her zaman kap_disclosures / article_tickers üzerinden hisse kodu ve zaman sınırlıdır.

200400401403429500

GET/api/v1/alerts/blindspots

Kör nokta ve sessiz bölge uyarıları

Ad	Yer	Açıklama
since	query	updated_at için alt sınır, tam ISO 8601 zaman damgası (T ve saniye ile). Varsayılan: şimdi−24 saat. 7 günden eski değerler sessizce 7 güne çekilir.
limit	query	Döndürülecek en çok uyarı sayısı, 1–100 arası tam sayı (varsayılan 50), en yeniden en eskiye.
format	query	json veya rss. Başka bir değer 400 döner. Verilmezse Accept başlığı application/rss+xml içeriyorsa RSS, aksi halde JSON döner.

İki kural, tek akış. Kör nokta: geri çağırma (recall veto) uygulanmış, en az 5 oy veren kaynak ve tek bölgeden %80 veya fazlası, 24 saat gecikmeli, yayın sağlığı bozuk bölge için bastırılmış; en çok 30 kayıt (sitedeki /blindspots ile aynı).
Sessiz bölge: tam olarak bir bölgede sıfır kaynak, en az 5 oy veren kaynak, küme en az 6 saat önce başlamış, veto yok, arşivlenmemiş. Sessiz bölgenin yayın akışları bozuksa kayıt düşer; sağlık bilgisi alınamazsa akış açık kalır.
sessiz = Tayf eşleştiremedi: bir bölgenin sessiz görünmesi o bölgenin haberi yapmamayı seçtiği anlamına gelmez, yalnızca Tayf'ın o bölgeden bu kümeye eşleşen haber bulamadığı anlamına gelir.
RSS: format=rss verilirse veya format yokken Accept başlığı application/rss+xml içerirse RSS 2.0 döner (Content-Type application/rss+xml, Vary Origin, Authorization, Accept). Anahtar yalnızca Authorization başlığıyla gönderilir; adres satırında anahtar parametresi yoktur.
Webhook (isteğe bağlı, anahtar başına, yönetici tanımlar): her yeni uyarı için imzalı bir POST gönderilir. Gövde JSON: event (tayf.alert), alert (bu uç noktadaki kayıtla aynı), licence, attribution. Başlıklar: X-Tayf-Event, X-Tayf-Delivery (teslimat numarası; yeniden denemelerde aynı kalır), X-Tayf-Timestamp (saniye), X-Tayf-Signature.
İmza: zaman damgasının, bir noktanın ve ham gövdenin art arda birleşimi imza anahtarıyla HMAC-SHA256'dan geçirilir; sonuç onaltılık yazılır ve başına sha256= eklenir. Alıcı ham gövde üzerinden yeniden hesaplayıp sabit zamanlı karşılaştırmalı, zaman damgası eskiyse reddetmelidir. İmza anahtarı yalnızca tanımlanırken bir kez gösterilir.
Teslimat kuralları: yalnızca https ve 443 numaralı kapı; yönlendirmeler izlenmez (3xx başarısız sayılır). 2xx başarıdır; 5xx, 408, 429, zaman aşımı ve ağ hataları 1, 5, 15 ve 60 dakika arayla en çok 5 denemeye kadar yeniden denenir; diğer 4xx başarısız sayılır. Art arda 20 başarısızlık webhook'u kapatır. Aynı alert.id bir alıcıya en fazla bir kez teslim edilir; yine de X-Tayf-Delivery veya alert.id ile tekilleştirin.

200400401403429500

Her uç nokta anahtarsız OPTIONS ön-uçuş isteğine 204 döner.

Hatalar

Her 2xx dışı yanıt {error, code?, details?} biçimindedir.

Durum	error	Anlamı
400	Invalid since / Invalid limit / Invalid cluster id	İstek parametresi geçersiz.
401	Missing or invalid API key	Authorization başlığı eksik, biçimsiz veya bilinmeyen anahtar.
403	API key revoked	Anahtar iptal edilmiş.
404	Cluster not found	Küme yok veya arşivlenmiş.
429	Too many requests / Daily limit exceeded	Anonim taban, dakikalık veya günlük sınır aşıldı.
500	Internal server error	Beklenmeyen sunucu hatası.

Lisans

CC BY-SA 4.0 — Tayf'a göre yalnızca Tayf'ın kendi çıktısını kapsar: küme gruplandırmaları, nötr başlıklar, Türkçe özetler ve kaynak-kaydı metadatası. Yayın kuruluşlarının kendi başlıkları, metinleri ve fotoğrafları ilgili kuruluşa aittir. Atıf şekli: "Tayf'a göre", bağlantı /metodoloji.

Anahtar alma

Anahtarlar şimdilik elle veriliyor. Kurumunuzu, kullanım amacınızı (akademik / gazetecilik / ticari) ve beklenen günlük istek sayısını yazın. Anahtar yalnızca bir kez gösterilir; Tayf yalnızca özetini (sha256) saklar. Kaybolursa iptal edilir ve yenisi verilir.

İletişim adresi yakında burada yayımlanacak.

OpenAPI

Makine tarafından okunabilir tam tanım: /api/v1/openapi.json.

Anahtarsız kaynak kaydı: /api/sources ve /api/sources/{slug}.

import os import requests resp = requests.get( f"https://www.tayfhaber.com/api/v1/clusters", headers={"Authorization": f"Bearer {os.environ['TAYF_API_KEY']}"}, params={"limit": 10}, timeout=10, ) resp.raise_for_status() data = resp.json() for cluster in data["clusters"]: print(cluster["title"], cluster["url"])

Katman

Dakikada

Günde

Nasıl alınır

Ücretsiz

2.000

E-postayla başvurun; anahtar elle verilir.

Ortak

600

50.000

Yüksek hacim ve toplu erişim için yazın.

Yer

Açıklama

since

query

updated_at için alt sınır, tam ISO 8601 zaman damgası (T ve saniye ile). Varsayılan: şimdi−24 saat. 7 günden eski değerler sessizce 7 güne çekilir.

limit

query

Döndürülecek en çok küme sayısı, 1–100 arası tam sayı (varsayılan 50).

Yer

Açıklama

id *

path

Küme UUID'si.

Yer

Açıklama

slug *

path

Kaynağın kısa adı (/api/v1/sources yanıtındaki slug); küçük harf, rakam ve tire, en çok 64 karakter.

Yer

Açıklama

ticker *

query

2–6 büyük harf/rakamdan oluşan hisse kodu (girişte büyük harfe çevrilir).

since

query

KAP bildirimi için alt sınır, tam ISO 8601 zaman damgası. Varsayılan: 30 gün önce. Gelecekteki bir değer reddedilir (400); 90 günden eski değerler sessizce 90 güne çekilir.

limit

query

Döndürülecek en çok bildirim sayısı, 1–100 arası tam sayı (varsayılan 50), en yeniden en eskiye.

Yer

Açıklama

since

query

updated_at için alt sınır, tam ISO 8601 zaman damgası (T ve saniye ile). Varsayılan: şimdi−24 saat. 7 günden eski değerler sessizce 7 güne çekilir.

limit

query

Döndürülecek en çok uyarı sayısı, 1–100 arası tam sayı (varsayılan 50), en yeniden en eskiye.

format

query

json veya rss. Başka bir değer 400 döner. Verilmezse Accept başlığı application/rss+xml içeriyorsa RSS, aksi halde JSON döner.

Durum

error

Anlamı

400

Invalid since / Invalid limit / Invalid cluster id

İstek parametresi geçersiz.

401

Missing or invalid API key

Authorization başlığı eksik, biçimsiz veya bilinmeyen anahtar.

403

API key revoked

Anahtar iptal edilmiş.

404

Cluster not found

Küme yok veya arşivlenmiş.

429

Too many requests / Daily limit exceeded

Anonim taban, dakikalık veya günlük sınır aşıldı.

500

Internal server error

Beklenmeyen sunucu hatası.