# 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](https://sro.gg/tr/sayfa/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:

```json
{
  "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:

```json
{
  "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.

## Trending

```
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.

## Trending ve hype ne değildir

İ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](https://sro.gg/tr/sayfa/api-dokumantasyonu.md). Bu, sayfaların oluşturulduğu kaynaktır; etrafında gezinme veya biçimlendirme yoktur.