JSON API | Eskimeyen Şarkılar

Sitedeki her yayımlanmış şarkı, söz, sanatçı, albüm ve tür JSON olarak da okunabilir. Anahtar yok, kayıt yok: https://www.eskimeyensarkilar.com/api/v1 adresine bir GET yeter. Salt okunurdur; üye verisi, taslak ya da oturum bilgisi taşımaz.

Başlangıç

curl https://www.eskimeyensarkilar.com/api/v1/songs/uzun-ince-bir-yoldayim

Her cevap application/json; charset=UTF-8 döner ve Access-Control-Allow-Origin: * taşır; tarayıcıdan, başka bir alan adından da çağrılabilir. Bir nesne her zaman kendi sayfa adresini (url) ve API adresini (api_url) taşır — bağlantıları izleyerek gezinmek için başka bir şey bilmek gerekmez.

Uç noktalar

Adres	Ne döner
`/api/v1`	Bu listenin makine hali.
`/api/v1/songs`	Şarkı sözleri ve şarkılar tek listede; sayfalı. Süzgeçler aşağıda.
`/api/v1/songs/{slug}`	Bir şarkı sözü sayfası: sözler (bölüm ve satır numaralarıyla), künye, satır notları, kayıtlar, albümler, yeni yorumları, benzer şarkılar. Slug bir sanatçının kendi şarkısına aitse o şarkı döner.
`/api/v1/songs/popular` · `/latest`	En çok bakılan / en son yayımlanan şarkı sözleri (`?per=`, en çok 50).
`/api/v1/artists`	Şarkı sözlerinin sanatçıları (yorumcu, besteci, söz yazarı, düzenlemeci), A'dan Z'ye; `?letter=A`, `?q=`.
`/api/v1/artists/{slug}`	Bir sanatçı: biyografi, role göre şarkı sözleri, albümleri, kronolojisi.
`/api/v1/albums/{slug}`	Bir albüm ve parça listesi.
`/api/v1/genres` · `/makam` · `/usul` · `/yore`	Türler ve üç kırılım, sayılarıyla.
`/api/v1/search?q=`	Tek çağrıda üç liste: şarkı sözleri, şarkılar, sanatçılar (her biri kendi toplamıyla).

Listeleme süzgeçleri

/api/v1/songs sitenin Keşfet listesiyle aynı süzgeçleri alır: kind=classic|recording, genre= (tür slug'ı), decade=1970, makam=, usul=, yore=, letter=A, sort=title|year|views|newest|popular, q= (başlık ya da sanatçıda bir kelime), page=, per= (varsayılan 24, en çok 50). Bilinmeyen bir tür ya da makam 404 döner; sessizce boş liste dönmez. Bir listenin zarfı şöyledir:

{
  "data": [ … ],
  "page": { "n": 1, "per": 24, "total": 312, "pages": 13,
            "next": "https://www.eskimeyensarkilar.com/api/v1/songs?page=2",
            "prev": null }
}

total en çok 1000'dir; daha kalabalık bir listede "1000+" anlamına gelir.

Bir şarkı sözü kaydının şekli

{
  "data": {
    "kind": "classic", "id": 12,
    "slug": "uzun-ince-bir-yoldayim",
    "title": "Uzun İnce Bir Yoldayım", "alt_titles": [],
    "artist": { "name": "Âşık Veysel",
                "slug": "asik-veysel", "url": "…" },
    "year": 1963, "decade": 1960,
    "genre": { "slug": "turk-halk-muzigi",
               "name": "Türk Halk Müziği" },
    "makam": null, "usul": null,
    "yore": { "slug": "sivas", "name": "Sivas" },
    "youtube_id": "…", "spotify_id": null,
    "cover": { "small": "…-300.webp",
               "medium": "…-600.webp",
               "large": "…-1200.webp" },
    "views": 1840, "renditions": 3,
    "published_at": "2026-09-14T10:12:00+03:00",
    "url": "…/song/uzun-ince-bir-yoldayim",
    "api_url": "…/api/v1/songs/uzun-ince-bir-yoldayim",
    "story": "…",
    "credits": {
      "performer": [ { "id": 3, "name": "Âşık Veysel",
                       "slug": "asik-veysel",
                       "url": "…", "api_url": "…" } ],
      "composer": [ … ], "lyricist": [ … ] },
    "lyrics": [ { "label": null,
                  "lines": [ { "n": 1,
                               "text": "Uzun ince bir yoldayım" },
                             … ] } ],
    "lyrics_text": "Uzun ince bir yoldayım\n…",
    "lyrics_restricted": false,
    "notes": [ { "line": 3, "quote": "…", "note": "…" } ],
    "recordings": [ { "performer": "…", "artist": { … },
                      "year": 1963, "source": "…",
                      "youtube_id": "…", "official": true,
                      "note": null } ],
    "albums": [ … ], "member_recordings": [ … ],
    "related": [ … ]
  }
}

Söz satırları, sayfadaki çapalarla (#s-12) ve notlardaki line alanıyla aynı sayıyla numaralanır; bölüm başlıkları sayılmaz.

Sözler hakkında

Künyeye göre hâlâ koruma altında olan eserlerde sözlerin tamamı verilmez: lyrics_restricted true olur, lyrics ve lyrics_text yalnızca ilk birkaç satırı taşır ve lyrics_notice bunu söyler. Bu alanı kontrol etmeden gelen metni "eserin sözleri" diye saklama.

Sanatçıların kendi şarkılarında sözler API'de hiç verilmez — yalnızca has_lyrics alanı şarkının sözü olup olmadığını söyler. Sanatçı şarkısını bu siteye yükledi; açık bir veri akışında dağıtılmasına izin vermedi. Sözler şarkının kendi sayfasında okunur.

Önbellek ve sınırlar

Cevaplar Cache-Control: public ve ETag taşır. If-None-Match gönderen bir istemci değişmemiş cevap için 304 alır; listeler 5 dakika, türler 15 dakika, arama 2 dakika tazedir.
Bir istemci (IP başına) tüm /api/v1 ağacında dakikada 300 istek yapabilir; aşımda 429 ve Retry-After döner. Kataloğu topluca çekmek için per=50 ile sayfala; her slug'ı ayrı ayrı gezmeye gerek yok.
Hatalar da JSON'dur: { "error": "…", "status": 404 }.
Eski bir slug 301 ile yeni adrese yönlenir; istemcin yönlendirmeyi izlemeli.
Ses dosyaları API'den verilmez; bir şarkıyı dinlemek için url alanındaki sayfa kullanılır.

Kullanım şartları

Veriler kaynak gösterilerek, ticari olmayan kullanım için serbesttir. Sözler, hikâyeler ve satır notları eser sahiplerinin ve editörlerin emeğidir; yeniden yayımlarken sayfaya bağlantı ver. Ticari kullanım ya da toplu aktarım için yaz. Bu arayüz Kullanım Koşulları'na tabidir; sürüm numarası değişmeden alan kaldırılmaz, yalnızca eklenir.