Python requests kütüphanesi, bir API'ye HTTP isteği göndermeyi ve dönen yanıtı işlemeyi tek satırlık komutlarla mümkün kılan, Python'un en yaygın kullanılan dış kütüphanelerinden biridir. Python temellerini bilen ama hiç API'den veri çekmemiş biri için requests, karmaşık ağ programlama detaylarıyla uğraşmadan gerçek dünya verisine erişmenin en pratik yoludur. Bu rehberde, HTTP'nin nasıl çalıştığından başlayarak requests kütüphanesinin kurulumuna, ilk isteğin atılmasına ve gelen JSON verisinin işlenmesine kadar adım adım ilerleyeceğiz. Amaç, teoriyi kısa tutup uygulamaya hızlıca geçmek.
HTTP Nedir ve İstek-Yanıt Döngüsü Nasıl Çalışır?
HTTP (HyperText Transfer Protocol), internet üzerindeki iki bilgisayarın birbiriyle konuşabilmesi için kullandığı ortak bir iletişim dilidir. Bir tarafta bilgi isteyen taraf (istemci/client), diğer tarafta bu bilgiyi elinde tutan taraf (sunucu/server) bulunur. Python kodunuz bir API'ye istek attığında, aslında sizin tarayıcınızın bir web sitesine bağlanmasıyla neredeyse aynı işlemi arka planda gerçekleştirir.
Bu ilişkiyi günlük hayattan bir örnekle düşünmek işi kolaylaştırır: Bir restoranda garsona sipariş verdiğinizde siz istekte bulunursunuz, mutfak siparişi hazırlar ve garson size yanıt olarak yemeği getirir. HTTP dünyasında da istemci bir istek (request) gönderir, sunucu bu isteği işler ve geriye bir yanıt (response) döner. Bu döngü her API çağrısında aynı mantıkla tekrarlanır: istek gönderilir, sunucu işler, yanıt geri gelir.
İsteklerin farklı "niyetleri" olabilir ve bu niyetler HTTP metotlarıyla ifade edilir. En sık karşılaşacağınız iki metot GET ve POST'tur:
- GET: Sunucudan veri okumak, mevcut bilgiyi almak için kullanılır. Örneğin bir hava durumu API'sinden bugünün sıcaklığını sormak bir GET isteğidir.
- POST: Sunucuya yeni veri göndermek, bir kayıt oluşturmak için kullanılır. Örneğin bir üyelik formunu doldurup gönderdiğinizde arka planda genellikle bir POST isteği çalışır.
Bu yazıda ağırlıklı olarak GET isteğine odaklanacağız çünkü API'den veri çekmenin en temel ve en sık kullanılan yolu budur. Ancak POST'un ne işe yaradığını bilmek, ileride bir API'ye veri göndermeniz gerektiğinde kafanızın karışmamasını sağlar.
Python'da requests Kütüphanesini Kurmak
Burada net bir noktayı vurgulamak gerekiyor: requests, Python'un standart kütüphanesiyle birlikte gelmez. Python kurulu bir bilgisayarda import requests yazdığınızda hata almanız normaldir, çünkü bu bir dış (üçüncü parti) kütüphanedir ve ayrıca kurulması gerekir. Python'un kendi standart kütüphanesinde urllib adında benzer bir modül bulunur, fakat requests hem daha okunaklı hem de yeni başlayan için çok daha kolay bir söz dizimine sahiptir.
Kurulum işlemi Python'un paket yöneticisi pip ile tek satırda yapılır. Terminal veya komut satırına aşağıdaki komutu yazmanız yeterlidir:
pip install requestsEğer projelerinizde sanal ortam (venv) kullanıyorsanız, requests kütüphanesini o sanal ortam aktifken kurmanız iyi bir pratiktir; bu sayede her proje kendi bağımlılıklarını izole bir şekilde yönetir ve farklı projeler arasında sürüm çakışması yaşanmaz. Sanal ortam oluşturmak istiyorsanız önce python -m venv env komutuyla ortamı yaratıp ardından aktive edip pip komutunu çalıştırabilirsiniz.
Kurulumun başarılı olup olmadığını anlamak için Python yorumlayıcısını açıp sadece import requests satırını çalıştırmanız yeterlidir. Herhangi bir hata almadan bu satır çalışıyorsa kütüphane doğru şekilde kurulmuş demektir. Eğer ModuleNotFoundError hatası alırsanız, pip komutunu doğru sanal ortamda veya doğru Python sürümü için çalıştırıp çalıştırmadığınızı kontrol etmelisiniz.
Kütüphane kurulumu, sanal ortam yönetimi ve pip gibi araçlar aslında Python'un günlük kullanımının ayrılmaz bir parçasıdır ve bu temelleri sağlam öğrenmek ileride karşılaşacağınız her yeni kütüphaneyle çalışmayı kolaylaştırır. Bu tür temel becerileri birebir uygulamalı şekilde pekiştirmek isteyenler için canlı sınıflı Python eğitimi kapsamında bu konular sıfırdan ve uygulamalı olarak ele alınır.
requests.get() ile Basit Bir İstek Atmak: Adım Adım
Kütüphane kurulduktan sonra sıra ilk isteği atmaya geliyor. Bu süreç aslında sandığınızdan çok daha az adımdan oluşur ve her adımın tek bir sorumluluğu vardır. İşte bir API'ye GET isteği atarken izlenecek temel akış:
- Öncelikle
import requestssatırıyla kütüphaneyi Python dosyanıza dahil edersiniz. - Ardından verinin geleceği hedef adresi, yani API URL'ini bir değişkende veya doğrudan fonksiyona parametre olarak belirlersiniz.
- Bu URL'e
requests.get()fonksiyonunu çağırarak isteği gönderirsiniz; bu satır çalıştığında Python arka planda sunucuyla bağlantı kurar. - Sunucudan dönen tüm bilgiyi (durum kodu, başlıklar, içerik) taşıyan response nesnesini bir değişkende saklarsınız.
- İsteğin gerçekten başarılı olup olmadığını anlamak için response nesnesinin status_code değerini kontrol edersiniz.
- Son olarak, istek başarılıysa response içindeki veriyi (genellikle JSON formatında) okuyup işlersiniz.
Bu altı adım, neredeyse her API entegrasyonunun iskeletini oluşturur; farklı projelerde değişen tek şey genellikle URL, gönderilen parametreler ve veriyle ne yapıldığıdır. Adımların mantığını bir kez kavradığınızda, karşınıza çıkan yeni bir API'yle çalışmak da çok daha az korkutucu hale gelir.
Bu adımları teorik olarak okumak yerine kendi bilgisayarınızda küçük denemelerle pekiştirmeniz, kalıcı öğrenme açısından çok daha etkilidir. Kod yazmadan önce her adımın "neden" orada olduğunu düşünmek, ezberden çok anlayarak ilerlemenizi sağlar; bu yaklaşımı sistemli bir şekilde uygulamak isteyenler video eğitim içerikleri üzerinden kendi hızlarında pratik yapabilir. Bir sonraki bölümde bu adımları gerçek bir kod örneğiyle hayata geçirip response nesnesinin içini birlikte inceleyeceğiz.
Response Nesnesini Tanımak: status_code, .text ve .json()
requests.get() ile bir istek attığınızda geriye size ham bir metin değil, tam donanımlı bir Response nesnesi döner. Bu nesne sunucudan gelen her şeyi içinde barındırır: isteğin sonucu, gelen veri, başlık bilgileri. Yeni başlayanlar için asıl kritik olan üç özellik vardır ve her biri farklı bir amaca hizmet eder.
response.status_code, sunucunun isteğinize verdiği yanıtın "özeti"dir. İsteğin başarılı mı, hatalı mı, sunucuda mı yoksa sizin tarafınızda mı bir sorun olduğunu tek bir sayıyla anlarsınız. Herhangi bir veriyi işlemeye başlamadan önce bu kodu kontrol etmek, kodunuzu çökmekten koruyan en basit alışkanlıktır. Yaygın karşılaşacağınız kodlar şunlardır:
| Durum Kodu | Anlamı |
|---|---|
| 200 | İstek başarılı, veri sorunsuz döndü |
| 201 | Yeni bir kayıt başarıyla oluşturuldu |
| 400 | İstek hatalı biçimlendirilmiş (Bad Request) |
| 401 | Kimlik doğrulama gerekiyor veya geçersiz |
| 404 | İstenen kaynak bulunamadı |
| 500 | Sunucu tarafında beklenmeyen bir hata oluştu |
response.text ise sunucudan gelen veriyi olduğu gibi, yani ham metin (string) hâlinde size verir. API'nin döndürdüğü içerik JSON, HTML ya da düz yazı bile olsa .text her zaman bunu tek bir karakter dizisi olarak sunar. Veriyi sadece görmek, loglamak ya da JSON olmayan bir yanıtla çalışmak istediğinizde .text kullanışlıdır.
response.json() ise bir adım daha ileri gider: gelen metni otomatik olarak ayrıştırır ve size doğrudan Python'ın dict veya list nesnesine dönüştürerek verir. Yani .text "bana ham veriyi ver" derken, .json() "bu veriyi benim için Python nesnesine çevir" der. Çoğu modern API JSON formatında yanıt verdiği için, pratikte gerçek işi çoğunlukla .json() ile yapacaksınız; .text ise daha çok hata ayıklama ya da doğrulama amaçlı devrededir.
JSON Verisini İşlemek: Halka Açık Test API'sinden Veri Çekme
Teoriyi pratiğe dökmenin en kolay yolu, kayıt gerektirmeyen ve ücretsiz olarak herkese açık bir test servisi kullanmaktır. Bu tür servisler gerçek bir ürün ya da şirket API'si değildir; sadece geliştiricilerin JSON isteklerini pratik yapması için tasarlanmış, sahte ama tutarlı veri döndüren basit uç noktalardır. Aşağıdaki örnekte böyle bir test servisinden gönderi (post) verisi çekiyoruz.
import requests
response = requests.get("https://jsonplaceholder.typicode.com/posts")
if response.status_code == 200:
veriler = response.json()
for gonderi in veriler[:5]:
print("Başlık:", gonderi["title"])
print("Kullanıcı ID:", gonderi["userId"])
print("-" * 30)
else:
print("İstek başarısız, durum kodu:", response.status_code)
Bu kodda önce isteği atıyoruz, ardından status_code'un 200 olup olmadığını kontrol ediyoruz; ancak bu kontrolden geçerse .json() çağrısını yapıyoruz. Burada dönen veriler değişkeni aslında bir list (liste) nesnesidir ve listenin her bir elemanı, gönderi bilgilerini tutan ayrı bir dict (sözlük) nesnesidir. Yani JSON'daki köşeli parantezler Python'da listeye, süslü parantezler ise sözlüğe karşılık gelir; bu eşleşmeyi bir kez kavradığınızda herhangi bir API yanıtını çözümlemek çok daha kolay hale gelir.
for döngüsüyle listenin ilk beş elemanını gezip her sözlükten title ve userId anahtarlarına karşılık gelen değerleri yazdırıyoruz. Bu, dict üzerinde köşeli parantez ile anahtar erişimi yapmaktan başka bir şey değildir; API'den gelen veri de sonuçta tanıdık Python veri yapılarına dönüşür. Eğer sözlük ve liste yapılarını, döngüleri ya da koşul ifadelerini tazelemeniz gerekiyorsa Python bilgi seviyeni ölçen ücretsiz test ile hangi konularda eksiğiniz olduğunu hızlıca görebilirsiniz.
Hataları Yönetmek: try/except ile Güvenli İstek Atma
Gerçek dünyada internet bağlantısı her zaman stabil olmaz, sunucular bazen yanıt vermez ya da yazdığınız URL'de küçük bir yazım hatası olabilir. Bu yüzden requests ile yapılan her isteği try/except bloğu içine almak, kodunuzu beklenmedik şekilde çökmekten koruyan temel bir alışkanlıktır. requests kütüphanesi, karşılaşabileceğiniz hataların çoğunu tek bir üst sınıf altında toplar: requests.exceptions.RequestException. Bu sınıfı yakalayarak bağlantı sorunundan zaman aşımına kadar birçok senaryoyu tek bir except bloğuyla ele alabilirsiniz.
import requests
try:
response = requests.get("https://jsonplaceholder.typicode.com/posts/1", timeout=5)
response.raise_for_status()
veri = response.json()
print(veri["title"])
except requests.exceptions.RequestException as hata:
print("İstek sırasında bir sorun oluştu:", hata)
Burada dikkat edilmesi gereken satır response.raise_for_status() satırıdır; status_code 200 dışında bir değer döndüğünde bu satır otomatik olarak bir hata fırlatır ve except bloğu devreye girer. Böylece "isteği attım ama sonucu hiç kontrol etmedim" hatasına düşmezsiniz. Sık karşılaşacağınız hata türleri şunlardır:
- ConnectionError: İnternet bağlantısı yok, sunucu ayakta değil ya da adrese ulaşılamıyor
- Timeout: Sunucu belirlenen sürede yanıt vermedi, isteğin zaman aşımına uğraması
- JSONDecodeError: Gelen yanıt JSON formatında değil ama .json() ile ayrıştırılmaya çalışılıyor
- Hatalı URL / MissingSchema: Adreste yazım hatası var ya da http:// / https:// eksik yazılmış
Bu hataları ilk gördüğünüzde hangisinin neden kaynaklandığını ayırt etmek kafa karıştırıcı olabilir; hata mesajını okumak ve hangi satırda oluştuğunu izole etmek zamanla kolaylaşan bir beceridir. Eğer bu noktada takılıp kalıyorsanız, kodunuzu birlikte satır satır inceleyebileceğiniz birebir Python dersleri bu tür hata ayıklama alışkanlıklarını daha hızlı oturtmanıza yardımcı olabilir.
Bu Mantık Gerçek Projelerde Nasıl Kullanılır?
Buraya kadar öğrendiğin akış aslında tek bir cümleyle özetlenebilir: istek at, durumu kontrol et, veriyi işle. Bu üç adım, JSONPlaceholder gibi basit bir test servisinde nasıl çalışıyorsa, gerçek dünyada kullanılan hava durumu, döviz kuru ya da kullanıcı profili API'lerinde de aynı şekilde çalışır. Fark eden şey sadece hangi adrese istek attığın ve o adresin sana ne tür bir JSON döndürdüğüdür.
Örneğin bir hava durumu servisinden belirli bir şehrin sıcaklığını çekmek istediğinde yine requests.get() ile isteği gönderir, response.status_code ile isteğin başarılı olup olmadığını kontrol eder ve response.json() ile dönen veriyi bir sözlüğe çevirirsin. Döviz kuru API'sinde de, bir kitap arama servisinde de senaryo değişmez; yalnızca dönen sözlüğün içindeki anahtarlar (örneğin "temperature" yerine "rate" veya "title") farklılaşır. Bu yüzden yeni bir API ile karşılaştığında panik yapmana gerek yok: önce isteği at, gelen JSON'un yapısını yazdır, sonra ihtiyacın olan anahtara göre veriyi çek.
Elbette her API tamamen aynı kalıpta değildir. Bazı servisler istek atarken bir API anahtarı (API key) ister, bazıları belirli parametreleri URL'ye eklemeni bekler, bazıları da GET yerine POST isteği kullanmanı gerektirir. Ancak bu farklar, öğrendiğin temel mantığı değiştirmez; sadece isteğin üzerine küçük ek bilgiler eklemeni gerektirir. Bir API'nin dokümantasyonunu okuyup hangi parametrenin zorunlu olduğunu anlamak, kod yazmaktan çok daha fazla dikkat ve okuma pratiği ister — ve bu da zamanla gelişen bir beceridir.
Bu beceriyi öğrenmek, sadece "API'den veri çekmek" ile sınırlı kalmaz. Bir e-ticaret sitesinin stok durumunu düzenli olarak kontrol eden bir otomasyon script'i, bir mobil uygulamanın arkasında çalışan bir backend servisi ya da farklı sistemleri birbirine bağlayan bir entegrasyon katmanı — hepsi temelde aynı istek-yanıt mantığına dayanır. Yazılım kariyerinde hangi yöne ilerlemek istediğinden emin değilsen, ücretsiz kariyer keşif testi ile hangi alanların sana daha yakın hissettirdiğini görebilir, bu temel bilgiyi nereye yönlendireceğine dair fikir edinebilirsin.
Python Temellerinden Gerçek Projelere Geçiş
requests ile veri çekmek, tek başına bir teknik değil; Python'da zaten bildiğin fonksiyon, döngü ve sözlük gibi temel yapı taşlarının bir araya geldiği bir pratiktir. Örneğin bir API'den dönen kullanıcı listesini for döngüsüyle gezmek, her kullanıcının ismini bir fonksiyon içinde işlemek ya da gelen JSON verisini bir sözlükte biriktirip daha sonra kullanmak — bunların hepsi senin zaten bildiğin kavramların yeni bir bağlamda kullanılmasıdır. Bu yüzden requests öğrenmek, sıfırdan yeni bir dil öğrenmek gibi değildir; var olan bilgini gerçek veriyle buluşturmaktır.
Aşağıdaki gibi küçük bir örnek, bu birleşimi net gösterir:
import requests
def kullanici_isimlerini_getir():
response = requests.get("https://jsonplaceholder.typicode.com/users")
if response.status_code == 200:
kullanicilar = response.json()
isimler = [kullanici["name"] for kullanici in kullanicilar]
return isimler
return []
for isim in kullanici_isimlerini_getir():
print(isim)
Bu kısa örnekte fonksiyon tanımlama, koşul kontrolü, liste oluşturma (list comprehension) ve döngü bir arada kullanılıyor — hepsi requests'in getirdiği veri üzerinde çalışıyor. Bu noktada fark ettiğin şey şu olmalı: API'den veri çekmek yeni bir konu değil, bildiğin konuların üzerine eklenen bir katman.
Bu noktadan sonra ilerlemek isteyenler için doğal adım, bu tür pratikleri daha yapılandırılmış bir müfredat içinde, geri bildirim alarak pekiştirmektir. canlı Python eğitimleri kapsamında bu tür konular adım adım, uygulamalı örneklerle ve soru-cevap desteğiyle işlenir; böylece tek başına denemekle sınırlı kalmak yerine, takıldığın noktada geri bildirim alarak ilerleyebilirsin. Önemli olan, bu bilgiyi veri bilimi veya karmaşık bir backend sistemi kurma hedefiyle değil, saf Python pratiğini derinleştirme amacıyla ele almak — geri kalanı zamanla, ihtiyaç duydukça üzerine eklenecektir.
Sık Sorulan Sorular
requests kütüphanesi Python ile birlikte mi gelir?
Hayır, requests Python'un standart kütüphanesinde yer almaz. Kullanmadan önce terminalden pip install requests komutuyla ayrıca kurulması gerekir.
GET ve POST istekleri arasındaki temel fark nedir?
GET isteği genellikle sunucudan veri okumak için kullanılır ve parametreler URL üzerinden gönderilir. POST isteği ise sunucuya yeni veri göndermek veya bir kaydı oluşturmak için kullanılır ve veri genellikle istek gövdesinde (body) taşınır.
API'den dönen JSON verisi Python'da nasıl bir yapıya dönüşür?
response.json() çağrıldığında JSON verisi otomatik olarak Python'un sözlük (dict) veya liste (list) yapılarına dönüştürülür. JSON'daki anahtar-değer çiftleri Python sözlüğüne, dizi (array) yapıları ise Python listesine karşılık gelir.
response.status_code 200 değilse ne yapmalıyım?
200 dışındaki bir kod, isteğin beklendiği gibi sonuçlanmadığını gösterir. Bu durumda veriyi işlemeye çalışmadan önce kodu kontrol etmeli, kullanıcıya veya log kaydına anlamlı bir uyarı bırakmalı ve gerekirse isteği tekrar denemelisin.
requests.exceptions.RequestException hangi hata türlerini kapsar?
Bu istisna sınıfı, bağlantı hatası, zaman aşımı (timeout) ve genel istek hataları gibi requests kütüphanesinin fırlatabileceği farklı hata türlerini kapsayan bir üst sınıftır. Bu sayede tek bir except bloğuyla birden fazla hata senaryosunu yakalayabilirsin.
Ücretsiz bir test API'si olmadan requests pratiği yapabilir miyim?
Teknik olarak herhangi bir açık API ile pratik yapılabilir, ancak yeni başlarken JSONPlaceholder gibi kayıt gerektirmeyen, ücretsiz test servisleri kullanmak hem daha güvenli hem daha hızlı öğrenmeni sağlar; kimlik doğrulama veya API anahtarı gibi ek karmaşıklıklarla uğraşmadan doğrudan istek-yanıt mantığına odaklanabilirsin.
Gerçek bir projede API'den veri çekerken nelere dikkat etmeliyim?
Status code kontrolü yapmak, olası hataları try/except ile yönetmek, gelen JSON verisinin yapısını doğrulamak ve gereksiz yere aynı isteği tekrar tekrar göndermemek dikkat edilmesi gereken temel noktalardır. Ayrıca API'nin dokümantasyonunu okuyup zorunlu parametreleri ve limitleri bilmek de hataları önler.
Python'da requests ile API'den veri çekmek, kod yazma pratiğini gerçek dünya verisiyle buluşturan basit ama güçlü bir adımdır; bu temeli sağlamlaştırdıkça fonksiyon, döngü ve hata yönetimi gibi kavramların birbirine nasıl bağlandığını daha net görürsün. Bu konuyu daha kapsamlı örneklerle ve birebir geri bildirimle pekiştirmek istersen 1-1 özel ders seçeneğiyle kendi hızında ilerleyebilirsin.
