NetEye Trend API

X (Twitter) trend listelerini kendi sisteminize alın: başlıklar, sıralar, listede kalma süreleri, "neden gündemde" notları ve her başlığın örnek tweetleri; trendler 10 dakikada bir güncellenir. İzinli anahtarlarla takip edilen hesapların takipçi, paylaşım ve etkileşim verisi de alınabilir.

Erişim

API anahtarla çalışır. Anahtar talebi, kullanım planı ve fiyatlandırma için info@neteye.dev adresine yazın.

Anahtarı her istekte Authorization başlığıyla gönderin. Anahtarı adres (URL) içinde göndermeyin, tarayıcıda çalışan koda koymayın; yalnızca sunucu tarafında kullanın.

curl https://www.neteye.dev/api/v1/trends?country=turkey \
  -H "Authorization: Bearer ne_live_XXXXXXXXXXXXXXXX"

Sınırlar

Her anahtarın dakikalık istek sınırı ve günlük kotası vardır (planınıza göre).
Her yanıtta X-RateLimit-Limit (günlük kota) ve X-RateLimit-Remaining (kalan) başlıkları bulunur.
Sınır aşılırsa 429 döner; Retry-After başlığı kaç saniye beklemeniz gerektiğini söyler. Kota UTC gece yarısı sıfırlanır.
Trendler 10 dakikada bir yenilenir; /trends uç noktasını 5–10 dakikadan sık sorgulamanız yeni veri getirmez.

Ülkeler

country parametresi şu değerleri alır (varsayılan turkey). Günler ülkenin yerel saatine göre hesaplanır; tüm zamanlar UTC'dir (Z).

country	Ülke	Saat dilimi
`turkey`	Türkiye	Europe/Istanbul
`germany`	Almanya	Europe/Berlin
`uk`	İngiltere	Europe/London
`usa`	ABD	America/New_York

Uç noktalar

Taban adres: https://www.neteye.dev/api/v1. Tüm uç noktalar GET'tir ve JSON döner.

GET `/trends`

Güncel trend listesi.

Parametre	Açıklama
`country`	Ülke (varsayılan `turkey`)
`limit`	1–50 (varsayılan 50)
`tweets`	`1` (varsayılan): her başlığa en fazla 3 örnek tweet; `0`: yalnızca başlıklar

{
  "country": "turkey",
  "fetched_at": "2026-10-19T09:40:02Z",
  "data": [
    {
      "name": "#Örnek",
      "rank": 1,
      "previous_rank": 3,
      "is_new": false,
      "duration_minutes": 140,
      "first_seen": "2026-10-19T07:20:01Z",
      "category": "Spor",
      "why_trending": {"tr": "…", "en": "…"},
      "tweets": [
        {
          "id": "1847…",
          "url": "https://x.com/kullanici/status/1847…",
          "text": "…",
          "created_at": "2026-10-19T08:55:13Z",
          "author": {"name": "…", "username": "kullanici", "verified": true, "avatar_url": "https://pbs.twimg.com/…"},
          "metrics": {"likes": 1520, "retweets": 210, "replies": 48},
          "media": [{"type": "photo", "url": "https://pbs.twimg.com/media/…", "width": 1200, "height": 675}]
        }
      ]
    }
  ]
}

category yalnızca Türkiye için doludur. why_trending notu her başlıkta bulunmayabilir (null).

GET `/trends/daily`

Bir günde listede en uzun kalan başlıklar (en fazla 50). Geçmiş günler için kullanılır.

Parametre	Açıklama
`country`	Ülke
`date`	`YYYY-MM-DD`, ülkenin yerel günü (varsayılan bugün)
`limit`	1–50 (varsayılan 50)

{"country": "germany", "date": "2026-10-18", "timezone": "Europe/Berlin",
 "data": [{"name": "…", "duration_minutes": 410, "best_rank": 1,
           "first_seen": "2026-10-18T05:10:00Z", "last_seen": "2026-10-18T21:50:00Z"}]}

GET `/trends/search`

Adında aranan ifade geçen başlıkların gün gün listede kalışı.

Parametre	Açıklama
`q`	Aranan ifade (en az 2 karakter, büyük/küçük harf duyarsız)
`country`	Ülke
`from`, `to`	`YYYY-MM-DD`; aralık en fazla 31 gün (varsayılan son 7 gün)

{"country": "turkey", "q": "deprem", "from": "2026-10-13", "to": "2026-10-19",
 "data": [{"date": "2026-10-17", "name": "Deprem", "entry_time": "…Z", "exit_time": "…Z",
           "duration_minutes": 230, "entry_rank": 12, "exit_rank": 31, "best_rank": 2}]}

GET `/trends/tweets`

Bir başlığın son 7 gündeki en çok beğenilen örnek tweetleri (yanıt biçimi /trends içindeki tweets ile aynı).

Parametre	Açıklama
`name`	Başlık adı, örn. `%23Örnek` (adres içinde `#` → `%23`)
`country`	Ülke
`limit`	1–20 (varsayılan 10)

GET `/countries`

Anahtarınızın erişebildiği ülkeler.

Hesap verileri

Bu uç noktalar yalnızca hesap verisi izni tanımlanmış anahtarlarla çalışır. NetEye'nin takip ettiği Türkiye'deki X hesaplarını (siyasetçiler, kurumlar, belediyeler, markalar, sanatçılar…) kapsar. Bu bölümdeki zamanlar İstanbul saatiyle (+03:00) döner.

{account} yerine kullanıcı adı (RTErdogan), X hesap kimliği ya da görünen ad yazılabilir.

Uç nokta	Döndürdüğü / parametreler
`/accounts`	Hesap arama. `q` (ad / kullanıcı adı), `category`, `limit` (1–50)
`/accounts/categories`	Kategoriler ve hesap sayıları
`/accounts/ranking`	Sıralama. `sort_by`: `followers`, `change_24h`, `engagement_24h`, `engagement_7d`, `engagement_rate_7d`; `category`, `order` (`desc`/`asc`), `limit` (1–100)
`/accounts/{account}`	Hesap özeti: takipçi, takip, 1/7/30 günlük takipçi değişimi, son 30 günün paylaşım ve etkileşim toplamları
`/accounts/{account}/history`	Günlük takipçi serisi. `days` (2–365, varsayılan 30)
`/accounts/{account}/posts`	Paylaşımlar. `from`, `to` (`YYYY-MM-DD`, varsayılan son 30 gün), `sort_by`: `recent`, `likes`, `views`, `retweets`, `replies`, `engagement`; `type`: `original`, `retweet`, `quote`, `all`; `q` (metinde ara), `limit` (1–50)
`/accounts/compare`	2–8 hesabı karşılaştırır. `accounts` (virgülle: `RTErdogan,eczozgurozel`), `days` (1–180)
`/posts/popular`	Takip edilen hesapların en çok etkileşim alan orijinal paylaşımları. `days` (1–7, varsayılan 1), `category`, `limit` (1–50)

curl "https://www.neteye.dev/api/v1/accounts/RTErdogan/posts?sort_by=likes&limit=5" \
  -H "Authorization: Bearer ne_live_XXXXXXXXXXXXXXXX"

{"id_str": "68034431", "username": "RTErdogan", "name": "Recep Tayyip Erdoğan", "category": "Kamu ve Siyaset",
 "start_date": "2026-09-19", "end_date": "2026-10-19", "sort_by": "likes", "post_type": "original", "count": 5,
 "posts": [{"tweet_id": "…", "created_at": "2026-09-26T20:00+03:00", "type": "orj_tweet", "text": "…",
            "likes": 52000, "retweets": 9100, "replies": 4300, "quotes": 610, "views": 2400000, "bookmarks": 733,
            "hashtags": [], "photos": 1, "has_video": false, "url": "https://x.com/…"}]}

Etkileşim = beğeni + RT + yanıt + alıntı (hesap özetinde yer imi de dahil); etkileşim oranı = etkileşim ÷ takipçi × 100.

Hatalar

{"error": {"code": "invalid_key", "message": "…"}}

HTTP	code	Anlamı
400	`invalid_parameter`, `invalid_country`, `invalid_range`	Parametre hatalı
401	`missing_key`, `invalid_key`	Anahtar yok, geçersiz, süresi dolmuş ya da iptal edilmiş
403	`country_not_allowed`, `tweets_not_allowed`, `accounts_not_allowed`	Planınız bu veriyi kapsamıyor
404	`not_found`	Hesap takip edilmiyor ya da veri yok
429	`rate_limited`, `daily_quota_exceeded`	Sınır aşıldı; `Retry-After` kadar bekleyin

Örnek: Python

import os, requests

API = "https://www.neteye.dev/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['NETEYE_API_KEY']}"}

r = requests.get(f"{API}/trends", params={"country": "turkey", "limit": 20}, headers=HEADERS, timeout=15)
r.raise_for_status()
for t in r.json()["data"]:
    print(t["rank"], t["name"], t["duration_minutes"], "dk")

Tweet metinleri ve görselleri X kullanıcılarına aittir. Kendi ürününüzde gösterirken tweet bağlantısını (url) ve yazarı belirtin; silinmiş tweetleri yayından kaldırın.