API

Sro.gg sunucu dizinini JSON olarak yayınlar; böylece siteyi taramanıza gerek kalmaz. Buradaki her şey herkese açıktır, anahtar gerektirmez ve veri metodolojisi sayfasındaki şartlarla kullanılabilir: sro.gg'ye atıf verin ve veriyi aldığınız sayfaya bağlantı koyun.

Tüm uç noktalar IP adresi başına dakikada 10 istek sınırını paylaşır. Her yanıt X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarını taşır; sınırı aşan istekler Retry-After başlığıyla 429 döner. Sınır ortak olduğu için istekleri farklı uç noktalara dağıtmak limiti yükseltmez.

Kendinizi tanıtın

Kim olduğunuzu ve neden istek attığınızı söyleyen bir User-Agent başlığı gönderin. Bu özellikle AI ajanları ve scriptler için önemli: göndermezseniz isimsiz bir istek olarak gelirsiniz ve bir araştırma aracını scraper'dan ayırt edemeyiz.

Ad/sürüm (+iletişim; purpose=kullanım-amacınız)

AcmeBot/1.0 (+https://acme.com/bot; purpose=price-comparison)
ResearchAgent/2.1 (+mailto:siz@example.com; purpose=academic research)

İletişim, başına + konmuş bir URL veya mailto: adresidir. Amaç, cümle değil kullanımı anlatan kısa bir ifadedir. İkisi de zorunludur — tek başına isim beyan sayılmaz ve yine kimliksiz kabul edilir.

Tanıyamadığımız istemciler — curl, çıplak HTTP kütüphaneleri, tanınır bir ajanı olmayan her şey — her yanıtın en başında bunu isteyen bir notice alanı alır. Kendinizi tanıttığınızda uyarı kaybolur. Googlebot, GPTBot ve ChatGPT-User gibi bilinen tarayıcılar otomatik tanınır ve bu uyarıyı hiç görmez; yine de purpose gönderebilirler.

Kendinizi tanıtmanın bir maliyeti yoktur ve şu an istek limitinizi değiştirmez. Anlamı şudur: API'yi kimin kullandığına baktığımızda isimsiz bir IP adresi olarak değil, kendiniz olarak görünürsünüz — kullanımınızla ilgili size ulaşmamız veya limitinizi yükseltmemiz gerekirse bunu yapabiliriz.

Hesabını veremediğimiz trafik, kimliksiz trafiktir. Tek bir IP adresinden sürekli olarak gelen yoğun, isimsiz curl tarzı istekler yavaşlatılabilir veya engellenebilir; çünkü bizim tarafımızdan bakıldığında scraping'den ayırt edilemez. Kendini tanıtan istemcilere böyle davranılmaz: ne için kullandıklarını görebiliriz ve bir adım atmadan önce size ulaşırız. Bu API üzerinde bir otomasyon çalıştırıyorsanız, bu başlığı göndermek doğru tarafta kalmanın en ucuz yoludur.

Sunucu dizini

GET https://sro.gg/api/public/servers

Listelenen her sunucuyu cap seviyesi, ırk yapılandırması, oyuncu limitleri, açılış tarihleri ve bilinen son oyuncu sayısıyla birlikte döner. Nüfus, özellik veya erişilebilirlik soruları için kullanılacak uç nokta budur.

Her kayıt playersOnline değerini, o okumanın yapıldığı anı belirten playersOnlineAt ile birlikte taşır. Sayıyı yayınlarken zaman damgasını da yayınlayın. null bir değer, sıfır oyuncu değil, okunabilir bir sayaç bulunamadığı anlamına gelir.

Süzgeçler

status — yaşam döngüsü durumları, virgülle ayrılır. live, beta, upcoming ve inactive kabul edilir. Örnek: ?status=live,beta
cap — tek bir cap seviyesi. Örnek: ?cap=110
openedAfter — bu tarihte veya sonrasında açılan sunucular. Örnek: ?openedAfter=2026-07-15
openedBefore — bu tarihte veya öncesinde açılan sunucular
sort — playersOnline, opensAt veya likes
locale — en veya tr. name ve description alanlarının dilini seçer ve url alanını o dile yöneltir. urls her durumda tüm dilleri taşır.

Kapanan sunucular, status=inactive veya includeInactive=true ile istenmedikçe dönmez. Referans olsun diye listede kalırlar ve oynanacak yerler değildirler.

Süzgeçleri birleştirmek sitenin kendi liste sayfalarını karşılar: ?status=upcoming&sort=opensAt yakında açılacaklar takvimidir, bir ay öncesine ayarlı ?openedAfter= ise yeni açılanlar sayfasıdır.

Geçersiz parametreler

Bilinen bir parametre izin verilen değer kümesi dışında bir değer taşıyorsa 400 döner — sessizce yok sayılmaz ve yanlışlıkla süzülmemiş bir liste almazsınız:

{
  "error": {
    "code": "invalid_query_parameter",
    "parameter": "status",
    "received": "invalid",
    "allowed": "live, beta, upcoming, inactive (comma separated)",
    "documentation": "https://sro.gg/en/page/api"
  }
}

Tanımadığımız bir parametre de 400 döner; böylece staus=live gibi bir yazım hatası sessizce süzülmemiş dizini döndürmek yerine açıkça hata verir:

{
  "error": {
    "code": "unknown_query_parameter",
    "parameter": "staus",
    "allowed": ["status", "cap", "openedAfter", "openedBefore", "sort", "includeInactive", "locale"],
    "documentation": "https://sro.gg/en/page/api"
  }
}

Bu listenin dışındaki hiçbir parametre kabul edilmez — utm_source veya ref gibi takip parametreleri de reddedilir. 200 aldıysanız, süzgeçleriniz yazdığınız gibi uygulanmıştır.

GET https://sro.gg/api/public/trending

Sunucuları son yedi günde sro.gg sayfalarının kaç kez görüntülendiğine göre sıralar; growthPercent bunu önceki yedi günle karşılaştırır.

Hype

GET https://sro.gg/api/public/hype

Sunucuları şu anda sro.gg sayfasını kaç kişinin okuduğuna göre sıralar; ölçüm 30 dakikalık pencerede yapılır.

İki uç nokta da sro.gg üzerindeki trafiği ölçer, oyundaki oyuncuları değil. "İnsanlar hangi sunuculara bakıyor" sorusunu yanıtlarlar, "hangi sunucu en büyük" sorusunu değil. Bir sunucu yeni açıldığı için, bir yerde adı geçtiği için, hatta kapandığı için trend olabilir.

Bu rakamları oyuncu sayısı olarak yeniden yayınlamayın. Nüfus için dizin uç noktasını kullanın; oradaki her sayı okumanın yapıldığı zaman damgasını taşır.

/api/ dışındaki aynalar

Bazı getirici araçlar ve ajanlar, robots.txt ne izin verirse versin, /api/ ile başlayan hiçbir yolu açmaz. Bu yüzden yukarıdaki uç noktaların tamamı düz .json yollarından da sunulur:

GET https://sro.gg/data/servers.json
GET https://sro.gg/data/trending.json
GET https://sro.gg/data/hype.json

Bunlar aynı işleyicilerdir; yanıt gövdesi, süzgeçler, istek limiti ve önbellek başlıkları birebir aynıdır — https://sro.gg/data/servers.json?status=live&cap=110 ile /api/public/servers karşılığı tamamen aynı sonucu verir. İstemciniz hangisini açabiliyorsa onu kullanın; bunun dışında birini diğerine tercih etmek için bir sebep yoktur.

Önbellek

Dizin ve trending 15 dakika, hype 60 saniye önbelleklenir. Dizinin tamamı tek istekte gelir ve yavaş değişir; bu yüzden sürekli sorgulamak yerine bir yanıtı önbelleğe almak daha iyidir. Daha yüksek bir limite ihtiyacınız varsa, bu sınırı aşmaya çalışmadan önce bizimle iletişime geçin.

Markdown

/sayfa/ altındaki belgeler, adresine .md eklenerek ham markdown olarak da sunulur — örneğin /sayfa/api-dokumantasyonu.md. Bu, sayfaların oluşturulduğu kaynaktır; etrafında gezinme veya biçimlendirme yoktur.

SRO.GG