TweetAPI Dokümantasyonu

TweetAPI REST API'siyle herkese açık Twitter verilerini alabilir, gönderi paylaşabilir ve etkileşimleri yönetebilirsiniz.

İlk isteğinizi gönderin

Dakikada 10 istek hızında, tek seferlik 100 deneme API birimiyle başlayın. Ölçülen çağrıların çoğu bir birim kullanır. Kredi kartı veya ücretli plan gerekmez; deneme birimlerinin süresi dolmaz.

Bir TweetAPI hesabı (İngilizce sayfa) oluşturun. Ücretsiz API erişiminizi otomatik olarak hazırlarız.
API Keys (İngilizce sayfa) sayfasını açın, Create Key seçeneğini seçin, anahtara bir ad verin ve anahtarın tamamını kaydedin. Anahtarın tamamını yalnızca oluştururken görebilirsiniz; kaydetmediyseniz yeni bir anahtar oluşturun.
Aşağıdaki hazır isteği açın. Anahtarınızı seçip Try It! düğmesine basarak herkese açık bir profili sorgulayın. Bu istek için ayrıca bir X hesabını yetkilendirmeniz gerekmez.
200 durum kodunu ve data içeren bir JSON nesnesini görmelisiniz. Playground gerçek API'yi çağırır ve API birimlerinizden düşer.
Aşağıdaki ortam değişkenini tanımlayın ve kendi uygulamanızda bir örnek çalıştırın.

Hazır isteği Playground'da açın (Playground İngilizcedir).

Aynı isteği kendi bilgisayarınızda çalıştırın

YOUR_API_KEY yerine kaydettiğiniz anahtarın tamamını yazın. Değişkeni, kodunuzu çalıştıracağınız terminalde tanımlayın. Anahtarları sunucunuzda tutun; asla frontend koduna koymayın veya Git'e göndermeyin.

macOS / Linux:

export TWEETAPI_API_KEY='YOUR_API_KEY'

PowerShell:

$env:TWEETAPI_API_KEY = 'YOUR_API_KEY'

cURL (Bash)

curl --fail-with-body \
  'https://api.tweetapi.com/tw-v2/user/by-username?username=elonmusk' \
  -H "X-API-Key: ${TWEETAPI_API_KEY:?Set TWEETAPI_API_KEY first}"

Python SDK'sı

SDK'yı pip install tweetapi ile kurun. Aşağıdaki kodu quickstart.py olarak kaydedin ve python quickstart.py komutunu çalıştırın.

import os
from tweetapi import TweetAPI

client = TweetAPI(api_key=os.environ["TWEETAPI_API_KEY"])
user = client.user.get_by_username(username="elonmusk")
print(user["data"])

Node.js SDK'sı (Node.js 18 ve üzeri)

SDK'yı npm install tweetapi-node ile kurun. Aşağıdaki kodu quickstart.mjs olarak kaydedin ve node quickstart.mjs komutunu çalıştırın.

import TweetAPI from "tweetapi-node";

const apiKey = process.env.TWEETAPI_API_KEY;
if (!apiKey) throw new Error("Set TWEETAPI_API_KEY first");
const client = new TweetAPI({ apiKey });
const user = await client.user.getByUsername({ username: "elonmusk" });
console.log(user.data);

İlk isteğiniz başarısız olursa

Değişken tanımlı değilse veya 401 alıyorsanız: TWEETAPI_API_KEY değişkenine anahtar listesindeki maskeli önizlemeyi değil, anahtarın tamamını verin.
Hesap kurulumu hâlâ bekliyorsa: kurulum ekranında Check again seçeneğini kullanın. Erişim açılmazsa destek ekibine yazın.
429: code alanına bakın. RATE_LIMITED ise Retry-After header'ındaki saniye kadar bekleyip tekrar deneyin. QUOTA_EXHAUSTED veya SUBSCRIPTION_INACTIVE ise Billing (İngilizce sayfa) sayfasını kontrol edin.
503: hizmet geçici olarak kullanılamıyor. Varsa Retry-After değerine uyun ve tekrar deneme sayısını sınırlayın.

Temel URL

API isteklerini şu adrese gönderin:

https://api.tweetapi.com/tw-v2/

Kimlik doğrulama

API anahtarınızı X-API-Key header'ında gönderin:

headers: {
  'X-API-Key': 'YOUR_API_KEY'
}

API'yi çağırmadan önce

Yanıtlar JSON biçimindedir.
Plan limitleri, TweetAPI hesabınızdaki tüm API anahtarları için ortak uygulanır: bir API birimi kotası ve dakikalık bir istek limiti.
Koleksiyon döndüren endpoint'ler, mümkün olduğunda cursor tabanlı sayfalama kullanır.
Gönderi paylaşma, etkileşim, profil, DM ve X Chat endpoint'leri, TweetAPI anahtarınıza ek olarak hesap yetkilendirme alanları gerektirebilir. Tam olarak hangi parametrelerin gerektiğini her endpoint'in sayfasında kontrol edin.
Planınızın limitlerinden kaynaklanan bir 429, nedenini belirten bir code içerir: RATE_LIMITED (dakikalık limiti aştınız; Retry-After header'ı limitin kaç saniye sonra sıfırlanacağını gösterir), QUOTA_EXHAUSTED (kotanız ve ön ödemeli bakiyeniz bitti) veya SUBSCRIPTION_INACTIVE (aboneliğinizin süresi doldu ya da aboneliğiniz etkin değil). Son ikisi tekrar denemeyle düzelmez. code içermeyen bir 429 geçicidir; sınırlı bir backoff ile tekrar deneyin. Yanıtlarda X-RateLimit-* header'ları bulunmaz.
503 yanıtında, varsa Retry-After header'ına uyun. Hata devam ediyorsa art arda denemekten kaçının. Sonucu belirsiz kalan bir işlemi tekrarlamadan önce işlemin tamamlanıp tamamlanmadığını kontrol edin.

TweetAPI SDK'ları

Python ve Node.js SDK'ları tip desteği, otomatik yeniden deneme ve sayfalama içerir. 2.5.0 sürümünden itibaren code alanını error.code olarak sunar ve Retry-After süresini otomatik olarak bekler.

Python

pip install tweetapi

from tweetapi import TweetAPI

client = TweetAPI(api_key="YOUR_API_KEY")
user = client.user.get_by_username(username="elonmusk")
print(user["data"]["followerCount"])

GitHub'da görüntüle

Node.js / TypeScript

npm install tweetapi-node

import TweetAPI from "tweetapi-node";

const client = new TweetAPI({ apiKey: "YOUR_API_KEY" });
const user = await client.user.getByUsername({ username: "elonmusk" });
console.log(user.data.followerCount);

GitHub'da görüntüle

Geliştirici kaynakları

Kod üreticiler ve API araçları için OpenAPI spesifikasyonu (İngilizce sayfa).
Belgelenmiş 83 işlemin tamamını içeren tam Postman koleksiyonu (İngilizce sayfa).
Herkese açık profil, arama ve tweet ayrıntısı istekleri içeren salt okunur Postman hızlı başlangıç koleksiyonu (İngilizce sayfa).

Bu kaynaklar İngilizcedir.

Temel özellikler

Herkese açık kullanıcı profillerini, tweet'leri, takipçileri ve etkileşim metriklerini alın
Tweet paylaşın; beğenileri, retweet'leri, yer işaretlerini ve doğrudan mesajları yönetin
Belgelenmiş sorgu parametreleriyle tweet, kullanıcı ve medya arayın
Uygulamanız istek gönderdiği anda güncel gönderileri, profilleri ve metrikleri alın (İngilizce sayfa) (İngilizce rehber)
Koleksiyonlarda cursor'larla sayfa sayfa ilerleyin
Görseller, videolar ve GIF'lerle çalışın

Kullanılabilir endpoint'ler

Kullanıcı endpoint'leri

Kullanıcı adıyla kullanıcı alma
ID ile kullanıcı alma
Birden çok ID ile kullanıcıları alma
Takipçi ve takip edilen listeleri
Kullanıcının tweet'leri ve yanıtları
Abonelik bilgileri

Tweet endpoint'leri

Tweet ayrıntıları ve sohbet akışları
Alıntı tweet'ler ve retweet'ler
Tweet çevirisi
Etkileşim metrikleri

Etkileşim endpoint'leri

Gönderi oluşturma, yanıtlama ve silme
Tweet beğenme ve yer işaretlerine ekleme
Retweet ve alıntı tweet
Liste yönetimi

Liste ve topluluk endpoint'leri

Liste ayrıntıları ve üyeleri
Topluluk bilgileri
Zaman akışı tweet'leri

Arama endpoint'leri

Tweet, kullanıcı ve medya arama
Gelişmiş arama operatörleri
Filtreleme ve sıralama seçenekleri

Plan limitleri

Herkese açık planların şu anki dakikalık istek limitleri:

Free: dakikada 10 istek
Pro: dakikada 60 istek
Ultra: dakikada 120 istek
Mega: dakikada 180 istek
Giga: dakikada 300 istek
Tera: dakikada 500 istek

Özel, eski veya kişiye özel planların limitleri farklı olabilir. Dakikalık limitten kaynaklanan bir 429 (RATE_LIMITED) alırsanız Retry-After süresi kadar bekleyin ve eş zamanlı istek sayısını azaltın. Planınızın API birimi kotası bittiyse (QUOTA_EXHAUSTED), panelden kullanımınızı ve abonelik seçeneklerini kontrol edin ya da kodunuzdan GET /tw-v2/account/usage (İngilizce sayfa) çağrısı yapın. Kısa bir tekrar deneme kotayı geri getirmez.

Fiyatlar, endpoint başına birim maliyetleri ve faturalandırma kuralları, makine tarafından okunabilir JSON olarak /pricing.json (İngilizce sayfa) adresinde de yayımlanır.

Yedek olarak kullandıkça öde

Billing sayfasından tek seferlik, elle kullandıkça öde (PAYG) alımları yapabilirsiniz: 5 USD'ye 10.000 birim, 10 USD'ye 20.000, 20 USD'ye 40.000 veya 50 USD'ye 100.000 birim. Yüklemeler otomatik olarak yenilenmez. TweetAPI önce ücretsiz planınızdaki veya aboneliğinizdeki kullanılabilir kotayı harcar, ardından geçerli PAYG bakiyenizi otomatik olarak kullanır. Aboneliği iptal etseniz de geçerli PAYG birimleriniz kullanılmaya devam eder. Yalnızca PAYG ile erişim dakikada 60 istekle sınırlıdır; daha yüksek limitli etkin bir planınız varsa o yüksek limit korunur.

PAYG birimlerinin süresi, ödemenin onaylanmasından 365 gün sonra dolar. Her yükleme, bakiye o anda hâlâ geçerliyse bakiyenizin tamamının son kullanma tarihini, mevcut son kullanma tarihi ile yeni ödemenin onaylanmasından 365 gün sonrası arasından hangisi daha geçse ona taşır. Süresi dolmuş birimler geri getirilemez. Süre dolmadan ödeme yaptığınız hâlde yükleme geç uygulandıysa support@tweetapi.com adresine yazın; doğrulanan işlem hatalarını düzeltiriz. Billing sayfası ve ödeme onayları, ortaya çıkan son kullanma tarihini UTC olarak gösterir.

Birimler döndürülen tweet başına değil, ölçülen her API çağrısı başına düşülür. Çağrıların çoğu 1 birimdir; /tw-v2/xchat/send 10, /tw-v2/auth/login ise 50 birimdir. 400, 401, 403, 409, 422 ve 429 dışındaki 200–499 HTTP durum kodlu yanıtlar ücretlendirilir; dolayısıyla boş sonuçlar, sayfalama istekleri, tekrar denemeler ve tekrarlanan isteklerin her biri birim kullanır. Yolla veya metotla eşleşen bir endpoint olmadığı için dönen 404 yanıtları ücretlendirilmez.

Bakiyenizi GET /tw-v2/account/usage (İngilizce sayfa) ile kontrol etmek ücretsizdir; yalnızca dakikalık istek limitinize sayılır.

İadeler birimleri orantılı olarak geri alır ve tam birime yukarı yuvarlar. Bir ödeme itirazı, iadelerle zaten geri alınanlar düşüldükten sonra ilgili satın almanın tüm birimlerini geri alır. Eksi bakiye PAYG'yi kilitler, geçerli bir aboneliği ise etkilemez. Yüklemeler önce eksi bakiyeyi kapatır, sonra kullanılabilir birim ekler. Hatalı birim kesintileri, teslim edilmeyen birimler veya ödeme itirazları için support@tweetapi.com adresine yazın; çözüm talep etmek için yeni birim satın almanız gerekmez. Kullanım koşulları ve iade bilgileri (İngilizce sayfa) sayfasına bakın (İngilizce). Yasal haklarınız saklıdır.

Hata yönetimi

TweetAPI, başarı veya hatayı belirtmek için standart HTTP durum kodlarını kullanır.

Sık görülen hata kodları

400s Errors

400Bad Request - Invalid parameters

401Unauthorized - Invalid API key

404Not Found - Resource doesn't exist

429RATE_LIMITEDToo Many Requests - Per-minute limit

429QUOTA_EXHAUSTEDToo Many Requests - Allowance used up

429SUBSCRIPTION_INACTIVEToo Many Requests - Subscription inactive

500s Errors

500Internal Server Error

Hata yanıtı biçimi

Tüm hatalar aynı biçimi kullanır:

{
  "statusCode": 400,
  "message": "Invalid username parameter"
}

Bazı hatalar, kodunuzda kontrol edebileceğiniz sabit bir neden belirten code alanı da içerir:

{
  "statusCode": 429,
  "message": "Rate limit quota exceeded - 60 requests per minute allowed",
  "code": "RATE_LIMITED"
}

Şu anki kodlar şunlardır: 429 için RATE_LIMITED, QUOTA_EXHAUSTED ve SUBSCRIPTION_INACTIVE; X hesabı artık kullanılamadığında ACCOUNT_SUSPENDED ve ACCOUNT_LOCKED; proxy'niz başarısız olduğunda PROXY_ERROR ve PROXY_TIMEOUT; ayrıca giriş sayfasında (İngilizce sayfa) listelenen giriş sonuçları. Nedeni olmayan hatalarda code alanı bulunmaz. Yeni kodlar eklenebilir; bilinmeyen bir kodu code alanı olmayan bir hata gibi ele alın.

İyi uygulamalar

Yanıtın durum kodunu ve varsa code alanını kontrol edin
Hata ayıklamak için hata yanıtlarını kaydedin
Tekrar denemelerde sınırlı üstel backoff kullanın ve varsa Retry-After süresini bekleyin
QUOTA_EXHAUSTED veya SUBSCRIPTION_INACTIVE hatalarını tekrar denemeyin; bunun yerine Billing (İngilizce sayfa) sayfasını kontrol edin

Güvenlik için iyi uygulamalar

API anahtarınızı asla herkese açık şekilde paylaşmayın veya sürüm kontrolüne göndermeyin
Anahtarlarınızı düzenli olarak yenileyin
Uygulamalarınızda API anahtarlarını ortam değişkenlerinde saklayın
Olağan dışı etkinlikleri fark etmek için panelinizden kullanımı takip edin

Destek

Yardım için support@tweetapi.com adresine e-posta gönderin veya Telegram'da @tweetapi ile iletişime geçin.

Yapay Zekaya Hazır Dokümantasyon