API Kullanım Kılavuzu

Classifyes LCSH-TR Çeviri API'si ile 505.000+ konu başlığını programatik olarak sorgulayın.

Genel Bakış

Classifyes LCSH-TR API'si, Library of Congress Konu Başlıklarının (LCSH) Türkçe çevirilerine hızlı ve kolay erişim sağlayan ücretsiz, açık bir REST API'dir. Bu API ile:

Tek tek veya toplu olarak konu başlıklarını sorgulayabilirsiniz
İngilizce veya Türkçe olarak arama yapabilirsiniz
Sonuçları JSON formatında alıp kendi uygulamalarınıza entegre edebilirsiniz
Kütüphane otomasyon sistemlerinize, kataloglama araçlarınıza veya araştırma projelerinize bağlayabilirsiniz

API Uç Noktası (Endpoint)

GET https://classifyes.com/lcsh-translator/api/search

Parametreler

Parametre	Tür	Zorunlu	Açıklama
`q`	string	Evet	Aranacak terim (İngilizce veya Türkçe). Kısmi eşleşme desteklenir.
`limit`	integer	Hayır	Döndürülecek maksimum sonuç sayısı (varsayılan: 100)

Yanıt Formatı (JSON)

[
  {
    "english":    "Traffic engineering",
    "turkish":    "Trafik Mühendisliği",
    "link":       "http://id.loc.gov/authorities/subjects/sh85136739",
    "id":         "sh85136739",
    "lcshId":     "sh85136739"
  },
  ...
]

Temel Kullanım

1. Tarayıcıdan Doğrudan Sorgulama

En basit yol, URL'yi tarayıcınızın adres çubuğuna yapıştırmaktır:

URL

https://classifyes.com/lcsh-translator/api/search?q=traffic+engineering

2. cURL ile Sorgulama

Bash

# Tek bir terim arama
curl "https://classifyes.com/lcsh-translator/api/search?q=traffic+engineering"

# Sonuç sayısını sınırlama
curl "https://classifyes.com/lcsh-translator/api/search?q=biology&limit=10"

# Türkçe ile arama
curl "https://classifyes.com/lcsh-translator/api/search?q=m%C3%BChendislik"

Python ile Toplu Sorgulama

Aşağıdaki Python betiği, bir dosyadan okunan konu başlıklarını toplu olarak API'ye gönderir ve sonuçları bir CSV dosyasına kaydeder.

Python

import requests
import csv
import time

API_URL = "https://classifyes.com/lcsh-translator/api/search"

# Aranacak terimler listesi
terms = [
    "Traffic engineering",
    "Computer science",
    "Library cataloging",
    "Machine learning",
    "Civil engineering",
]

results = []

for term in terms:
    response = requests.get(API_URL, params={"q": term, "limit": 5})
    
    if response.status_code == 200:
        data = response.json()
        for item in data:
            results.append({
                "english": item["english"],
                "turkish": item["turkish"],
                "lcsh_id": item["id"],
            })
        print(f"✓ '{term}' → {len(data)} sonuç")
    else:
        print(f"✗ '{term}' → Hata: {response.status_code}")
    
    time.sleep(0.3)  # Sunucuyu yormamak için kısa bekleme

# CSV'ye kaydet
with open("lcsh_translations.csv", "w", newline="", encoding="utf-8-sig") as f:
    writer = csv.DictWriter(f, fieldnames=["english", "turkish", "lcsh_id"])
    writer.writeheader()
    writer.writerows(results)

print(f"\n✅ {len(results)} çeviri kaydedildi → lcsh_translations.csv")

İpucu: Sunucuyu aşırı yüklememek için toplu istekler arasında time.sleep(0.3) ile kısa bir bekleme süresi ekleyin.

Dosyadan Toplu Sorgulama

Elinizde bir metin dosyası veya CSV varsa, terimleri dosyadan okuyarak toplu sorgulama yapabilirsiniz:

Python

import requests
import csv
import time

API_URL = "https://classifyes.com/lcsh-translator/api/search"

# Dosyadan terimleri oku (her satırda bir terim)
with open("terms.txt", "r", encoding="utf-8") as f:
    terms = [line.strip() for line in f if line.strip()]

print(f"Toplam {len(terms)} terim okundu.\n")

matched = []
unmatched = []

for i, term in enumerate(terms, 1):
    resp = requests.get(API_URL, params={"q": term, "limit": 1})
    
    if resp.status_code == 200 and resp.json():
        item = resp.json()[0]
        matched.append([term, item["turkish"], item["id"]])
        print(f"[{i}/{len(terms)}] ✓ {term} → {item['turkish']}")
    else:
        unmatched.append([term])
        print(f"[{i}/{len(terms)}] ✗ {term} → Bulunamadı")
    
    time.sleep(0.3)

# Sonuçları kaydet
with open("matched.csv", "w", newline="", encoding="utf-8-sig") as f:
    writer = csv.writer(f)
    writer.writerow(["English", "Turkish", "LCSH ID"])
    writer.writerows(matched)

print(f"\n✅ Eşleşen: {len(matched)}, Eşleşmeyen: {len(unmatched)}")

JavaScript ile Kullanım

Web uygulamanızda veya Node.js ortamında fetch ile kullanabilirsiniz:

JavaScript

// Tek sorgulama
async function searchLCSH(query) {
    const url = `https://classifyes.com/lcsh-translator/api/search?q=${encodeURIComponent(query)}`;
    const response = await fetch(url);
    const data = await response.json();
    return data;
}

// Toplu sorgulama
async function batchSearch(terms) {
    const results = [];
    for (const term of terms) {
        const data = await searchLCSH(term);
        results.push({ term, results: data });
        await new Promise(r => setTimeout(r, 300)); // 300ms bekleme
    }
    return results;
}

// Kullanım
batchSearch(["Machine learning", "Library science"])
    .then(res => console.log(res));

Kullanım Kuralları

Dikkat: API ücretsiz olarak sunulmaktadır. Lütfen aşağıdaki kurallara uyunuz:

İstek Hızı: Ardışık istekler arasında en az 300ms bekleme süresi bırakın.
Günlük Limit: Günlük 10.000 istek sınırını aşmamaya özen gösterin.
Önbellekleme: Aynı sorguyu tekrar tekrar yapmak yerine sonuçları yerel olarak önbelleğe alın.
Atıf: API verilerini kullandığınız çalışmalarda Classifyes LCSH-TR kaynağını belirtmeniz rica olunur.

Akademik Atıf

Bu veri setini akademik çalışmalarınızda kullanıyorsanız lütfen aşağıdaki şekilde atıf yapın:

BibTeX

@misc{classifyes_lcsh_tr,
  title   = {Classifyes LCSH-TR: Türkçe Konu Başlıkları Çeviri Hizmeti},
  author  = {Classifyes},
  year    = {2025},
  url     = {https://classifyes.com/lcsh-translator/},
  note    = {505.000+ LCSH konu başlığının yapay zekâ destekli Türkçe çevirisi}
}