API belgeleri
GET /v1/domains/semrush.com/overview isteği, o alan adının Semrush otorite puanını, trafiğini ve backlink sayılarını JSON olarak döner ve 1 kredi harcar. Backlinkler, anahtar kelimeler, rakipler, referans alan adları ve trafik geçmişi aynı yolun altındadır.
https://api.ornek.com
- Alan adı özeti
- Otorite puanı, organik ve ücretli trafik, anahtar kelime, referans alan adı ve backlink sayıları. 1 kredi.
- Listeler
- Backlinkler, organik anahtar kelimeler ve referans alan adları 100 satırlık sayfalar halinde; rakipler ve aylık trafik geçmişi.
- Toplu özet
- 50 alan adına kadar özet tek istekle, arka planda çalışan bir iş olarak. Alan adı başına 1 kredi.
- Sandbox
sm_test_kostowayanahtarıyla ücretsiz dene; bu sayfadaki örnekler onunla hemen çalışır. Ayrıntılar.
- Yanıtlar UTF-8 JSON'dur. Zaman damgaları ISO 8601 biçiminde ve UTC'dir:
2026-11-15T08:15:08Z. - Hatalarda
error.codealanına göre dallan; mesajlar insanlar içindir ve değişebilir. - Kalan kredini ve kullanımını
/v1/meile ücretsiz görürsün. Makine tarafından okunabilir tanım OpenAPI belgesinde.
Hızlı başlangıç
Anahtar almaktan ilk yanıta üç adım.
- Sandbox anahtarıyla hemen dene, sonra paket al. Herkese açık
sm_test_kostowayanahtarısemrush.comvegetkosto.comiçin ücretsiz çalışır; bu sayfadaki bütün örnekler ve Dene panelleri onunla hazır gelir. Kendi alan adların için kredi paketlerinden birini kayıt sayfasından Telegram üzerinden satın al; anahtarın Telegram'dan gelir. - Uç noktayı çağır. Anahtarı
X-API-Keybaşlığında gönder ve/v1/domains/{alan-adı}/overviewadresine istek at. Örnek seçtiğin dilde hazır; paket aldıktan sonra sandbox anahtarını kendi anahtarınla değiştir. - JSON'u oku.
metricsnesnesi otorite puanını, trafiği ve backlink sayılarını içerir. Harcanan ve kalan kredi her yanıttakicreditsnesnesinde veX-Credits-*başlıklarında yazar.
Her uç noktanın altındaki Dene panelinden isteği doğrudan bu sayfadan gönderebilirsin. Anahtar yalnızca bu tarayıcıda kalır ve istek sen düğmeye basmadan gitmez.
Sandbox
Paket almadan önce API'yi kendi kodunda denemek için herkese açık bir anahtar var: sm_test_kostoway. Bu sayfadaki örnekler ve Dene panelleri varsayılan olarak bu anahtarla gelir.
- Yalnızca
semrush.comvegetkosto.comiçin, yalnızca/v1/domains/…uç noktalarında çalışır. Başka bir alan adı422 sandbox_domaindöner. - Ücretsizdir:
credits.chargedher zaman0,X-Credits-Remainingbaşlığısandbox, gövdede"sandbox": true. - Yalnızca önbellekten okur; önbellekte olmayan bir istek
503 upstream_busydöner.fresh=trueetkisizdir. - IP adresi başına dakikada 10 istek. Eski yollar ve toplu işler
403 sandbox_not_alloweddöner. /v1/mesandbox profilini döner:status: "sandbox",allowed_domains,rate_limit_per_minute.
Kimlik doğrulama
/health, /v1/plans, /v1/quote ve /v1/changelog dışındaki her uç nokta bir API anahtarı ister. Anahtarı X-API-Key başlığında gönder (OpenAPI'deki güvenlik şeması: ApiKey). Anahtarlar sm_ ile başlar.
| Yöntem | Durum |
|---|---|
X-API-Key: sm_… başlığı | Önerilen ve desteklenen yol. |
?api_key=sm_… parametresi | Eskidi; hâlâ çalışır ama adres satırındaki anahtar kayıtlara ve geçmişe sızar. Kullanma. |
- Anahtar yoksa
401 missing_api_key, geçersizse401 invalid_api_keydöner; ikisinde deWWW-Authenticate: ApiKeybaşlığı bulunur./v1/megeçersiz anahtara403 invalid_api_keyile yanıt verir. - İptal edilen anahtar
403 key_revoked, süresi dolan anahtar403 key_expiredalır. - Her anahtar dakikada en fazla 30 istek gönderebilir (
429 rate_limited,Retry-Afterkadar bekle). Bazı anahtarlarda ek bir günlük sınır olabilir (429 daily_limit_reached). - Kalan kredini ve bitiş tarihini giriş yaptıktan sonra kontrol panelinde ya da
/v1/meile görürsün.
Krediler ve fiyatlar
API kredi ile çalışır. Her veri isteği türüne göre belirli sayıda kredi harcar; harcanan ve kalan kredi her yanıttaki credits nesnesinde ve X-Credits-Charged / X-Credits-Remaining başlıklarında yazar.
| İstek | Kredi | Durum |
|---|
- Krediler paketler halinde satılır; paketleri fiyatlar bölümünde görür, kayıt sayfasından Telegram üzerinden satın alırsın.
- Krediler satın alındıktan sonra 90 gün geçerlidir. Yeni bir paket kredilerini artırır ve geçerlilik süresini uzatır.
- Önbellekten dönen yanıtlar da kredi harcar. Sayfalı istekler sayfa başına, toplu özet benzersiz alan adı başına ücretlendirilir.
502ve503ile biten istekler kredi harcamaz; düşülen kredi otomatik iade edilir./v1/me,/v1/plans,/v1/quote,/v1/changelog,/v1/bulk/{job_id}ve/healthücretsizdir; sandbox anahtarı da ücretsizdir. Kredi bittiğinde veri istekleri402 insufficient_creditsdöner.
Özel miktar
Paketlerden büyük bir miktar istersen 7.500 ile 100.000 kredi arasında, 500'lük adımlarla özel teklif alabilirsin. Kredi başı fiyat miktar büyüdükçe düşer; kademeler /v1/plans yanıtındaki custom.tiers alanındadır. Fiyatı GET /v1/quote?credits=10000 ile hesaplatırsın.
| Başlangıç | Kredi başı oran |
|---|
Yanıt yapısı
Bütün veri yanıtları aynı ortak alanlarla gelir; listeler ayrıca bir pagination nesnesi taşır. Uç noktaların alan tablolarında yalnızca kendilerine özgü alanlar yazıyor.
Sayfalama
Backlinkler, anahtar kelimeler ve referans alan adları page parametresiyle 100 satırlık sayfalar halinde gelir (1–100). Rakipler ve trafik geçmişi tek sayfadır ama aynı pagination nesnesini taşır. has_more false olana kadar page değerini artırabilirsin; her sayfa ayrı istektir.
Başlıklar
Yanıt başlıkları gövdedeki bilgiyi tekrar eder; gövdeyi açmadan kredi ve hız durumunu izlemek için kullanabilirsin. Destek isterken X-Request-Id değerini paylaş.
| Başlık | Ne zaman | Anlamı |
|---|
İstek başlıkları
X-API-Key: API anahtarın.Idempotency-Key: yalnızca toplu istekte, isteğe bağlı. Aynı anahtarla 24 saat içinde gelen aynı istek yeni iş açmaz ve ikinci kez ücret almaz.Content-Type: application/json: gövdeli isteklerde (toplu istek).
Önbellek ve süreler
Her alan adı için çekilen sonuç diskte kalıcı olarak saklanır ve sunucu yeniden başlasa da korunur. Önbellekten dönen yanıtta cached: true, X-Cache: HIT ve verinin kaydedildiği cached_at bulunur.
- Güncel veri istiyorsan
fresh=truegönder. Önbellekteki kopya 6 saatten eskiyse veri Semrush'tan yeniden çekilir; daha yeniyse önbellekteki kopya döner. Hangisinin olduğunu yanıttakifresh_appliedsöyler. - Önbellekten dönen yanıtlar da kredi harcar.
İstemci zaman aşımını en az 120 saniye yap. Önbellekte olmayan bir alan adında veri Semrush'tan canlı çekilir ve 10–90 saniye sürebilir. Sunucu 110 saniyede vazgeçer, 503 upstream_timeout döner ve krediyi iade eder.
Ülke veritabanları
db parametresi Semrush'ın ülke veritabanını seçer. Alan adı özetinde ve toplu özette boş bırakırsan tüm ülkelerin toplamı (global) döner; anahtar kelime, rakip ve geçmiş isteklerinde varsayılan us'dir. Listede olmayan bir kod 422 unsupported_db döner.
Hata kodları
Hatalar HTTP durum koduyla ve hep aynı gövdeyle gelir. Programın error.code alanına göre dallanmalı; message insanlar içindir ve değişebilir. details yalnızca bazı doğrulama hatalarında bulunur. Eski istemciler için aynı mesaj üst düzeydeki detail alanında da durur.
| Durum | Kod | Ne zaman, ne yapmalı |
|---|
502ve503bizim taraftaki geçici durumlardır ve kredi harcamaz;Retry-Aftervarsa o kadar bekleyip aynı isteği yinele.402,403,409ve422yanıtlarını aynı istekle yineleme; isteği ya da anahtarı düzelt veya kredi al.
Kod örnekleri
Hata yönetimi ve uzun zaman aşımıyla, üretimde kullanmaya hazır örnekler. Dil seçimi tüm sayfa için geçerlidir ve hatırlanır.
- Anahtarı koda yazma; ortam değişkeninden oku.
- Zaman aşımını en az 120 saniye tut.
error.codedeğerine göre dallan;upstream_*kodlarındaRetry-Afterkadar bekleyip yeniden dene. Destek isterkenrequest_iddeğerini paylaş.
Eski yollar
İlk sürümdeki yollar hâlâ çalışır ve aynı yanıtı döner, ama eskidi ve 1 Temmuz 2027'de kapanacak. Yanıtlarında Deprecation: true, Sunset: Wed, 01 Jul 2027 00:00:00 GMT ve yeni yolu gösteren Link: <…>; rel="successor-version" başlıkları bulunur. Sandbox anahtarı eski yollarda çalışmaz (403 sandbox_not_allowed).
| Eski | Yeni | Kapanış |
|---|---|---|
/domain/{alan-adı} | /v1/domains/{alan-adı}/overview | 1 Temmuz 2027 |
/backlinks/{alan-adı} | /v1/domains/{alan-adı}/backlinks | 1 Temmuz 2027 |
/keywords/{alan-adı} | /v1/domains/{alan-adı}/keywords | 1 Temmuz 2027 |
/competitors/{alan-adı} | /v1/domains/{alan-adı}/competitors | 1 Temmuz 2027 |
/refdomains/{alan-adı} | /v1/domains/{alan-adı}/refdomains | 1 Temmuz 2027 |
/history/{alan-adı} | /v1/domains/{alan-adı}/history | 1 Temmuz 2027 |
?api_key=sm_… | X-API-Key: sm_… başlığı | Eskidi |
Değişiklik günlüğü
Sürümler ve önemli değişiklikler. Aynı liste makine tarafından okunabilir biçimde GET /v1/changelog adresinde.
Swagger ve OpenAPI
Tüm uç noktaların OpenAPI tanımı ve otomatik oluşturulan etkileşimli arayüz Swagger üzerindedir. Swagger'daki sunucu seçicisi canlı API adresini gösterir; istekleri oradan da deneyebilirsin. İstemci kodu üretmek için ham şemayı kullan.