API'yi kullanın

İçindekiler

  1. Giriş
    1. Kimlik doğrulama ve yetkilendirme
    2. Google Kitaplar Kimlikleri
    3. Kullanıcı Konumunu Ayarlama
  2. Birimlerle çalışma
    1. Arama yapma
    2. Belirli bir birimi alma
  3. Kitap raflarıyla çalışma
    1. Bir kullanıcının herkese açık kitap raflarının listesini alma
    2. Belirli bir herkese açık kitaplığı alma
    3. Herkese açık bir kitap rafındaki ciltlerin listesini alma
  4. "Kitaplığım"daki kitap raflarıyla çalışma
    1. Kitap raflarımın listesini alma
    2. Kitap rafımdaki ciltlerin listesini alma
    3. Kitap rafıma cilt ekleme
    4. Kitap rafımdan bir cildi kaldırma
    5. Kitap rafımdaki tüm ciltleri temizleme
  5. Sorgu parametresi referansı
    1. Standart sorgu parametreleri
    2. API'ye özel sorgu parametreleri

Giriş

Bu belge, Books API ile etkileşimde bulunabilecek uygulamalar yazmak isteyen geliştiricilere yöneliktir. Google Kitaplar'ın misyonu, dünyadaki kitap içeriğini dijitalleştirmek ve web'de daha kolay bulunabilir hale getirmektir. Books API, söz konusu içeriği arayıp erişmenin yanı sıra, bu içerikle ilgili kişiselleştirme oluşturma ve görüntüleme olanağı sunar.

Google Kitaplar kavramlarına aşina değilseniz kodlamaya başlamadan önce Başlarken bölümünü okumalısınız.

İstekleri yetkilendirme ve uygulamanızı tanımlama

Uygulamanızın Books API'ye gönderdiği her isteğin, uygulamanızı Google'a tanımlaması gerekir. Uygulamanızı tanımlamanın iki yolu vardır: OAuth 2.0 jetonu (isteği de yetkilendirir) ve/veya uygulamanın API anahtarını kullanmak. Bu seçeneklerden hangisinin kullanılacağını nasıl belirleyeceğiniz aşağıda açıklanmıştır:

  • İstek, yetkilendirme gerektiriyorsa (örneğin, bir kişinin özel verilerine yönelik istek), uygulamanın istekle birlikte bir OAuth 2.0 jetonu sağlaması gerekir. Uygulama da API anahtarını sağlayabilir, ancak bu zorunlu değildir.
  • İstek, yetkilendirme gerektirmiyorsa (örneğin, herkese açık veri isteği) uygulamanın, sizin için en uygun seçenek olan API anahtarını veya OAuth 2.0 jetonunu ya da her ikisini de sağlaması gerekir.

Yetkilendirme protokolleri hakkında

Uygulamanız, istekleri yetkilendirmek için OAuth 2.0 kullanmalıdır. Başka hiçbir yetkilendirme protokolü desteklenmez. Uygulamanız Google ile Oturum Açma özelliğini kullanıyorsa yetkilendirme işleminin bazı kısımları sizin adınıza gerçekleştirilir.

OAuth 2.0 kullanarak istekleri yetkilendirme

Herkese açık olmayan kullanıcı verileri için Books API'ye yapılan istekler, kimliği doğrulanmış bir kullanıcı tarafından yetkilendirilmelidir.

OAuth 2.0 ile yetkilendirme işleminin ("akış") ayrıntıları, yazdığınız uygulamanın türüne bağlı olarak değişiklik gösterir. Aşağıdaki genel işlem tüm uygulama türleri için geçerlidir:

  1. Uygulamanızı oluştururken Google API Konsolu'nu kullanarak kaydedersiniz. Ardından Google, daha sonra ihtiyaç duyacağınız bilgiler (ör. istemci kimliği ve istemci gizli anahtarı) sağlar.
  2. Google API Konsolu'nda Books API'yi etkinleştirin. (API, API Konsolu'nda listelenmemişse bu adımı atlayın.)
  3. Uygulamanız kullanıcı verilerine erişmesi gerektiğinde Google'dan belirli bir erişim kapsamı ister.
  4. Google, kullanıcıya uygulamanızı kullanıcının verilerinden bazılarını istemeye yetkilendirmesi için bir onay ekranı gösterir.
  5. Kullanıcı onaylarsa Google, uygulamanıza kısa süreli bir erişim jetonu verir.
  6. Uygulamanız, erişim jetonunu isteğe ekleyerek kullanıcı verileri için istekte bulunur.
  7. Google, isteğinizin ve jetonun geçerli olduğuna kanaat getirirse istenen verileri döndürür.

Bazı akışlarda başka adımlar da yer alır. Örneğin, yeni erişim jetonları almak için yenileme jetonları kullanmak. Farklı uygulama türlerine yönelik akışlar hakkında ayrıntılı bilgi için Google'ın OAuth 2.0 dokümanlarına bakın.

Books API için OAuth 2.0 kapsam bilgileri aşağıda verilmiştir:

https://www.googleapis.com/auth/books

Uygulamanızın OAuth 2.0 kullanarak erişim isteğinde bulunabilmesi için hem kapsam bilgilerine hem de uygulamanızı kaydederken Google tarafından sağlanan bilgilere (ör. istemci kimliği ve istemci gizli anahtarı) ihtiyacı vardır.

İpucu: Google API'leri istemci kitaplıkları, yetkilendirme işleminin bazı adımlarını sizin yerinize gerçekleştirebilir. Bu kitaplıklar çeşitli programlama dilleri için kullanıma sunulmuştur. Ayrıntılar için kitaplıkların ve örneklerin bulunduğu sayfayı inceleyin.

API anahtarı edinme ve kullanma

Herkese açık veriler için Books API'ye yapılan isteklere bir tanımlayıcı (API anahtarı veya erişim jetonu olabilir) eşlik etmelidir.

API anahtarı almak için:

  1. API Konsolu'nda Kimlik Bilgileri sayfasını açın.
  2. Bu API, iki tür kimlik bilgisini destekler. Projeniz için uygun olan kimlik bilgilerini oluşturun:

    • OAuth 2.0: Uygulamanız, özel kullanıcı verileri istediğinde istekle birlikte bir OAuth 2.0 jetonu göndermelidir. Uygulamanız önce bir istemci kimliği ve muhtemelen bir jeton almak için istemci gizli anahtarı gönderir. Web uygulamaları, hizmet hesapları veya yüklü uygulamalar için OAuth 2.0 kimlik bilgileri oluşturabilirsiniz.

      Daha fazla bilgi için OAuth 2.0 dokümanlarına bakın.

    • API anahtarları: OAuth 2.0 jetonu sağlamayan isteklerin API anahtarı göndermesi gerekir. Anahtar, projenizi tanımlar ve API erişimi, kota ve raporlar sağlar.

      API, API anahtarlarında çeşitli kısıtlama türlerini destekler. İhtiyacınız olan API anahtarı yoksa Kimlik bilgisi oluştur > API anahtarı'nı tıklayarak Console'da bir API anahtarı oluşturun. Anahtarı kısıtla'yı tıklayıp Kısıtlamalar'dan birini seçerek anahtarı üretimde kullanmadan önce kısıtlayabilirsiniz.

API anahtarlarınızı güvende tutmak için API anahtarlarını güvenli bir şekilde kullanmaya yönelik en iyi uygulamaları izleyin.

Bir API anahtarınız olduktan sonra, uygulamanız tüm istek URL'lerine key=yourAPIKey sorgu parametresini ekleyebilir.

API anahtarı, URL'lere yerleştirmek için güvenlidir; herhangi bir kodlama yapmanız gerekmez.

Google Kitaplar Kimlikleri

Belirli API yöntemi çağrılarına sahip kimlik alanlarını belirtmeniz gerekir. Google Kitaplar'da kullanılan üç tür kimlik vardır:

  • Cilt Kimlikleri - Google Kitaplar'ın bildiği her cilde verilen benzersiz dizeler. Birim kimliğine örnek olarak _LettPDhwR0C verilebilir. Birim kaynağı döndüren bir istekte bulunarak birim kimliğini almak için API'yi kullanabilirsiniz. Birim kimliğini ilgili id alanında bulabilirsiniz.
  • Kitap Rafı Kimlikleri: Bir kullanıcının kitaplığındaki bir kitap rafına verilen sayısal değerler. Google, her kullanıcı için aşağıdaki kimliklere sahip bazı önceden tanımlanmış raflar sağlar:
    • Favoriler: 0
    • Satın alındı: 1
    • Okumak için: 2
    • Şu Anda Okuyanlar: 3
    • Okundu: 4
    • İncelendi: 5
    • Son Görüntülenenler: 6
    • E-kitaplarım: 7
    • Size Özel Kitaplar: 8 Kullanıcı için herhangi bir önerimiz yoksa bu raf mevcut değildir.
    Özel rafların 1.000'den fazla kimliği var. Kitap rafı kimliği belirli bir kullanıcı için benzersizdir. Yani iki kullanıcı, farklı kitap raflarına atıfta bulunan aynı kimliğe sahip bir kitap rafına sahip olabilir. Bookshelf kaynağı döndüren bir istekte bulunarak API'yi kullanarak kitap rafı kimliğini alabilirsiniz. Bookshelf kimliğini, id alanında bulabilirsiniz.
  • Kullanıcı Kimlikleri - Her bir kullanıcıya atanan benzersiz sayısal değerler. Bu değerlerin, diğer Google hizmetlerinde kullanılan kimlik değeriyle aynı olması gerekmez. Şu anda kullanıcı kimliğini almanın tek yolu, kimliği kimliği doğrulanmış istekle alınan bir Bookshelf kaynağındaki selfLink'ten çıkarmaktır. Kullanıcılar ayrıca Kitaplar sitesinden kendi kullanıcı kimliklerini de alabilirler. Bir kullanıcı, API veya Kitaplar sitesi üzerinden başka bir kullanıcının kullanıcı kimliğini alamaz. Diğer kullanıcının bu bilgileri açıkça, örneğin e-posta yoluyla paylaşması gerekir.

Google Kitaplar sitesindeki kimlikler

Books API ile kullandığınız kimlikler Google Kitaplar sitesinde kullanılan kimliklerle aynıdır.

  • Cilt kimliği

    Sitedeki belirli bir birimi görüntülerken birim kimliğini id URL parametresinde bulabilirsiniz. Örnek: 

    https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard

  • Kitaplık kimliği

    Sitede belirli bir kitap rafını görüntülerken kitap rafı kimliğini as_coll URL parametresinde bulabilirsiniz. Örnek: 

    https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary

  • Kullanıcı Kimliği

    Sitede kitaplığınızı görüntülerken kullanıcı kimliğini uid URL parametresinde bulabilirsiniz. Örnek: 

    https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list

Kullanıcı Konumunu Ayarlama

Google Kitaplar son kullanıcının konumuyla ilişkili telif hakkı, sözleşme ve diğer yasal kısıtlamalara uyar. Bunun sonucunda bazı kullanıcılar belirli ülkelerden kitap içeriğine erişemeyebilir. Örneğin, belirli kitaplar yalnızca ABD'de "önizleme yapılabilir". Bu tür önizleme bağlantıları diğer ülkelerdeki kullanıcılar için geçerli değildir. Bu nedenle, API sonuçları sunucunuzun veya istemci uygulamanızın IP adresine göre kısıtlanır.

Birimlerle çalışma

Arama yapma

Aşağıdaki URI'ye HTTP GET isteği göndererek hacim araması yapabilirsiniz:

https://www.googleapis.com/books/v1/volumes?q=search+terms

Bu isteğin tek bir zorunlu parametresi var:

  • q - Bu metin dizesini içeren ciltleri arayın. Belirli alanlarda arama yapmak için arama terimlerinde belirtebileceğiniz özel anahtar kelimeler vardır. Örneğin:
    • intitle: Bu anahtar kelimeden sonraki metnin başlıkta bulunduğu sonuçları döndürür.
    • inauthor: Bu anahtar kelimeden sonraki metnin yazarda bulunduğu sonuçları döndürür.
    • inpublisher: Bu anahtar kelimeden sonraki metnin yayıncıda bulunduğu sonuçları döndürür.
    • subject: Bu anahtar kelimeden sonraki metnin, hacim kategori listesinde listelendiği sonuçları döndürür.
    • isbn: Bu anahtar kelimeden sonraki metnin ISBN numarası olduğu sonuçları döndürür.
    • lccn: Bu anahtar kelimeden sonra gelen metnin Kongre Kütüphanesi Kontrol Numarası olduğu sonuçları döndürür.
    • oclc: Bu anahtar kelimeden sonra gelen metnin Çevrimiçi Bilgisayar Kütüphanesi Merkezi numarası olduğu sonuçları döndürür.

İstek

Daniel Keyes'in "Flowers for Algernon" (Algernon için Çiçek) aramasıyla ilgili bir örnek: 

GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey

Not: Arama yapmak için kimlik doğrulama gerekmez. Bu nedenle, GET isteğiyle Authorization HTTP üst bilgisini sağlamanız gerekmez. Ancak, çağrı kimlik doğrulama ile yapılırsa her Birim, satın alma durumu gibi kullanıcıya özel bilgiler içerir.

Yanıt

İstek başarılı olursa sunucu 200 OK HTTP durum koduyla ve hacim sonuçlarıyla yanıt verir:

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "_ojXNuzgHRcC",
   "etag": "OTD2tB19qn4",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/_ojXNuzgHRcC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Vijaya Khisty Bodach"
    ],
   ...
  },
  {
   "kind": "books#volume",
   "id": "RJxWIQOvoZUC",
   "etag": "NsxMT6kCCVs",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/RJxWIQOvoZUC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Gail Saunders-Smith"
    ],
    ...
  },
  {
   "kind": "books#volume",
   "id": "zaRoX10_UsMC",
   "etag": "pm1sLMgKfMA",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/zaRoX10_UsMC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Paul McEvoy"
    ],
    ...
  },
  "totalItems": 3
}

İsteğe bağlı sorgu parametreleri

Hacim araması yaparken, standart sorgu parametrelerine ek olarak aşağıdaki sorgu parametrelerini de kullanabilirsiniz.

İndirme Biçimi

Döndürülen sonuçları, kullanılabilir indirme biçimi epub olan birimlerle sınırlamak için değerini epub olarak ayarlayarak download parametresini kullanabilirsiniz.

Aşağıdaki örnekte, indirilebilir epub (ePUB) indirme özelliği olan kitaplar aranır:

GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey
Filtreleme

Döndürülen sonuçları daha da kısıtlamak için filter parametresini, aşağıdaki değerlerden birine ayarlayarak kullanabilirsiniz:

  • partial - Metnin en az bir bölümünün önizlenebildiği sonuçları döndürür.
  • full - Yalnızca metnin tamamının görüntülenebilir olduğu sonuçları döndürür.
  • free-ebooks - Yalnızca ücretsiz Google e-kitapları olan sonuçları döndürür.
  • paid-ebooks - Yalnızca fiyatı olan Google e-Kitapları olan sonuçları döndürür.
  • ebooks - Yalnızca ücretli veya ücretsiz Google e-kitapları olan sonuçları döndürür. E-kitap olmayanlara örnek olarak sınırlı önizlemede olup satılamayan yayıncı içerikleri veya dergiler verilebilir.

Aşağıdaki örnekte arama sonuçları ücretsiz e-Kitap olarak mevcut olanlarla sınırlandırılmıştır:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey
Sayfalara ayırma

İsteğin parametrelerinde iki değer belirterek birimler listesini sayfalara ayırabilirsiniz:

  • startIndex: Koleksiyonda başlatılacak konum. İlk öğenin dizini 0'dır.
  • maxResults: Döndürülecek maksimum sonuç sayısı. Varsayılan değer 10, izin verilen maksimum değer 40'tır.

Döndürülen sonuçları belirli bir baskı veya yayın türüyle kısıtlamak için printType parametresini aşağıdaki değerlerden birine ayarlayarak kullanabilirsiniz:

  • all - Yazdırma türüne göre kısıtlamaz (varsayılan).
  • books - Yalnızca kitap olan sonuçları döndürür.
  • magazines - Dergi olan sonuçları döndürür.

Aşağıdaki örnekte arama sonuçları dergilerle sınırlandırılmıştır:

GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey
Projeksiyon

Döndürülecek önceden tanımlanmış Hacim alanları grubunu belirtmek için projection parametresini aşağıdaki değerlerden biriyle kullanabilirsiniz:

  • full - Tüm Cilt alanlarını döndürür.
  • lite: Yalnızca belirli alanları döndürür. Hangi alanların dahil edildiğini öğrenmek için Hacim referansı bölümünde çift yıldızla işaretlenmiş alan açıklamalarına bakın.

Aşağıdaki örnek, sınırlı hacim bilgisi içeren arama sonuçları döndürür:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey
Sıralama

Varsayılan olarak, hacim arama isteği maxResults sonuçlarını döndürür. Burada maxResults, sayfalara ayırma işleminde (yukarıda) kullanılan ve arama terimleriyle alaka düzeyine göre sıralanmış parametredir.

orderBy parametresini şu değerlerden biri olacak şekilde ayarlayarak sıralamayı değiştirebilirsiniz:

  • relevance - Sonuçları, arama terimlerinin alaka düzeyine göre döndürür (bu, varsayılan değerdir).
  • newest - Sonuçları en son yayınlanandan en az yakın zamanda yayınlanana doğru döndürür.

Aşağıdaki örnekte sonuçlar, en yeniden en eskiye doğru yayınlanma tarihine göre listelenmektedir:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey

Belirli bir birimi alma

Birim kaynak URI'sine HTTP GET isteği göndererek belirli bir birime ait bilgileri alabilirsiniz:

https://www.googleapis.com/books/v1/volumes/volumeId

volumeId yol parametresini, alınacak birimin kimliğiyle değiştirin. Cilt kimlikleri hakkında daha fazla bilgi için Google Kitaplar Kimlikleri bölümüne bakın.

İstek

Tek bir birim alan GET isteği örneğini aşağıda bulabilirsiniz:

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey

Not: Birim bilgilerini almak için kimlik doğrulama gerekmez. Bu nedenle, GET isteğiyle Authorization HTTP üst bilgisini sağlamanız gerekmez. Ancak, arama kimlik doğrulamayla yapılırsa Birim, satın alma durumu gibi kullanıcıya özel bilgileri içerir.

Yanıt

İstek başarılı olursa sunucu, 200 OK HTTP durum koduyla ve istenen Birim kaynağıyla yanıt verir:

200 OK

{
 "kind": "books#volume",
 "id": "zyTCAlFPjgYC",
 "etag": "f0zKg75Mx/I",
 "selfLink": "https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC",
 "volumeInfo": {
  "title": "The Google story",
  "authors": [
   "David A. Vise",
   "Mark Malseed"
  ],
  "publisher": "Random House Digital, Inc.",
  "publishedDate": "2005-11-15",
  "description": "\"Here is the story behind one of the most remarkable Internet
  successes of our time. Based on scrupulous research and extraordinary access
  to Google, ...",
  "industryIdentifiers": [
   {
    "type": "ISBN_10",
    "identifier": "055380457X"
   },
   {
    "type": "ISBN_13",
    "identifier": "9780553804577"
   }
  ],
  "pageCount": 207,
  "dimensions": {
   "height": "24.00 cm",
   "width": "16.03 cm",
   "thickness": "2.74 cm"
  },
  "printType": "BOOK",
  "mainCategory": "Business & Economics / Entrepreneurship",
  "categories": [
   "Browsers (Computer programs)",
   ...
  ],
  "averageRating": 3.5,
  "ratingsCount": 136,
  "contentVersion": "1.1.0.0.preview.2",
  "imageLinks": {
   "smallThumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=5&edge=curl&source=gbs_api",
   "thumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api",
   "small": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=2&edge=curl&source=gbs_api",
   "medium": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=3&edge=curl&source=gbs_api",
   "large": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=4&edge=curl&source=gbs_api",
   "extraLarge": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=6&edge=curl&source=gbs_api"
  },
  "language": "en",
  "infoLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&source=gbs_api",
  "canonicalVolumeLink": "https://books.google.com/books/about/The_Google_story.html?id=zyTCAlFPjgYC"
 },
 "saleInfo": {
  "country": "US",
  "saleability": "FOR_SALE",
  "isEbook": true,
  "listPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "retailPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "buyLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&buy=&source=gbs_api"
 },
 "accessInfo": {
  "country": "US",
  "viewability": "PARTIAL",
  "embeddable": true,
  "publicDomain": false,
  "textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
  "epub": {
   "isAvailable": true,
   "acsTokenLink": "https://books.google.com/books/download/The_Google_story-sample-epub.acsm?id=zyTCAlFPjgYC&format=epub&output=acs4_fulfillment_token&dl_type=sample&source=gbs_api"
  },
  "pdf": {
   "isAvailable": false
  },
  "accessViewStatus": "SAMPLE"
 }
}
Erişim Bilgileri

Bir e-Kitap için hangi özelliklerin kullanılabileceğinin belirlenmesinde accessInfo bölümü özellikle önemlidir. epub, akan metin biçimindeki bir e-kitaptır. epub bölümünde, bu e-kitap türünün kullanılabilir olup olmadığını belirten bir isAvailable özelliği bulunur. Kitap için bir örnek varsa veya kullanıcı kitabı satın almış olması ya da bulunduğu yerde kamu alanında olması nedeniyle okuyabiliyorsa burada bir indirme bağlantısı bulunur. Google Kitaplar için pdf ifadesi, e-kitabın, kullanılabilir olması ve indirme bağlantısı gibi benzer ayrıntılara sahip taranmış sayfalar sürümünü belirtir. Taranan sayfaların bu cihazlarda okunması zor olabileceğinden, Google, e-Okuyucular ve Akıllı Telefonlar için epub dosyalarını önerir. accessInfo bölümü yoksa cilt Google e-Kitap olarak kullanılamaz.

İsteğe bağlı sorgu parametreleri

Belirli bir birimi alırken standart sorgu parametrelerine ek olarak aşağıdaki sorgu parametresini kullanabilirsiniz.

Projeksiyon

Döndürülecek önceden tanımlanmış Hacim alanları grubunu belirtmek için projection parametresini aşağıdaki değerlerden biriyle kullanabilirsiniz:

  • full - Tüm Cilt alanlarını döndürür.
  • lite: Yalnızca belirli alanları döndürür. Hangi alanların dahil edildiğini öğrenmek için Hacim referansı bölümünde çift yıldızla işaretlenmiş alan açıklamalarına bakın.

Aşağıdaki örnek, tek bir birim için sınırlı hacim bilgileri döndürür:

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey

Kitap raflarıyla çalışma

Bir kullanıcının herkese açık kitap raflarının listesini alma

URI'ye aşağıdaki biçimde bir HTTP GET isteği göndererek bir kullanıcının genel kitap raflarının listesini alabilirsiniz:

https://www.googleapis.com/books/v1/users/userId/bookshelves

userId path parametresini, kitap raflarını almak istediğiniz kullanıcının kimliğiyle değiştirin. Kullanıcı kimlikleri hakkında daha fazla bilgi için Google Kitaplar Kimlikleri bölümüne bakın.

İstek

Örnek:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey

Kullanıcının herkese açık kitap raflarıyla ilgili bilgileri alması için kullanıcının kimliğinin doğrulanması gerekmediğinden, GET isteğini Authorization HTTP üst bilgisiyle sağlamanız gerekmez.

Yanıt

İstek başarılı olursa sunucu 200 OK HTTP durum kodu ve kitap raflarının listesiyle yanıt verir:

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   ...
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "description": "",
   "access": "PUBLIC",
   "updated": "2011-02-02T20:34:20.146Z",
   "created": "2011-02-02T20:34:20.146Z",
   "volumeCount": 2,
   "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
  },
  ...
 ]
}

İsteğe bağlı sorgu parametreleri

Bir kullanıcının herkese açık kitap raflarının listesini alırken standart sorgu parametrelerini kullanabilirsiniz.

Belirli bir herkese açık kitaplığı alma

URI'ye aşağıdaki biçimde bir HTTPGET isteği göndererek belirli bir herkese açık kitaplığı alabilirsiniz:

https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf

userId ve shelf yol parametrelerini, almak istediğiniz kullanıcıyı ve kitap rafını belirten kimliklerle değiştirin. Daha fazla bilgi için Google Kitaplar Kimlikleri bölümüne bakın.

İstek

Örnek:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey

Kullanıcının herkese açık kitap raflarıyla ilgili bilgileri alması için kullanıcının kimliğinin doğrulanması gerekmediğinden, GET isteğini Authorization HTTP üst bilgisiyle sağlamanız gerekmez.

Yanıt

İstek başarılı olursa sunucu 200 OK HTTP durum kodu ve kitap rafı kaynağıyla yanıt verir:

200 OK

{
  "kind": "books#bookshelf",
  "id": 3,
  "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
  "title": "Reading now",
  "description": "",
  "access": "PUBLIC",
  "updated": "2011-02-02T20:34:20.146Z",
  "created": "2011-02-02T20:34:20.146Z",
  "volumeCount": 2,
  "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
}

İsteğe bağlı sorgu parametreleri

Belirli bir herkese açık kitaplığı alırken standart sorgu parametrelerini kullanabilirsiniz.

Herkese açık bir kitap rafındaki ciltlerin listesini alma

Bir kullanıcının herkese açık kitaplığındaki ciltlerin listesini, aşağıdaki biçimde bir URI isteği HTTP GET isteği göndererek alabilirsiniz:

https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes

İstek

Örnek:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey

userId ve shelf yol parametrelerini, almak istediğiniz kullanıcıyı ve kitap rafını belirten kimliklerle değiştirin. Daha fazla bilgi için Google Kitaplar Kimlikleri bölümüne bakın.

Kullanıcının herkese açık kitap raflarıyla ilgili bilgileri alması için kullanıcının kimliğinin doğrulanması gerekmediğinden, GET isteğini Authorization HTTP üst bilgisiyle sağlamanız gerekmez.

Yanıt

İstek başarılı olursa sunucu bir 200 OK HTTP durum kodu ve kullanıcının kitap raflarının listesiyle yanıt verir:

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

İsteğe bağlı sorgu parametreleri

Herkese açık bir kitap rafındaki ciltlerin listesini alırken, standart sorgu parametrelerine ek olarak aşağıdaki sorgu parametresini kullanabilirsiniz.

Sayfalara ayırma

İsteğin parametrelerinde iki değer belirterek birimler listesini sayfalara ayırabilirsiniz:

  • startIndex: Koleksiyonda başlatılacak konum. İlk öğenin dizini 0'dır.
  • maxResults: Döndürülecek maksimum sonuç sayısı. Varsayılan değer 10, izin verilen maksimum değer 40'tır.

"Kitaplığım"daki kitap raflarıyla çalışma

Tüm "Kitaplığım" istekleri, kimliği doğrulanmış kullanıcının verileri için geçerlidir.

Kitap raflarımın listesini alma

URI'ya aşağıdaki biçimde bir HTTP GET isteği göndererek kimliği doğrulanmış kullanıcının tüm kitap raflarının listesini alabilirsiniz: 

https://www.googleapis.com/books/v1/mylibrary/bookshelves

İstek

Örnek:

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey
Authorization: /* auth token here */

Not: "Kitaplığım" kitap raflarının listesini alabilmek için kullanıcının kimliği doğrulanmalıdır. Bu nedenle, GET isteğiyle birlikte Authorization HTTP başlığını sağlamanız gerekir.

Yanıt

İstek başarılı olursa sunucu, 200 OK HTTP durum kodu ve kimliği doğrulanmış geçerli kullanıcı için tüm kitap raflarının listesiyle yanıt verir:

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   "kind": "books#bookshelf",
   "id": 0,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/0",
   "title": "Favorites",
   "access": "PRIVATE",
   "updated": "2011-04-22T04:03:15.416Z",
   "created": "2011-04-22T04:03:15.416Z",
   "volumeCount": 0,
   "volumesLastUpdated": "2011-04-22T04:03:17.000Z"
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "access": "PUBLIC",
   "updated": "2010-11-11T19:44:22.377Z",
   "created": "2010-11-11T19:44:22.377Z",
   "volumeCount": 1,
   "volumesLastUpdated": "2010-11-11T19:44:22.341Z"
  }
 ]
}

İsteğe bağlı sorgu parametreleri

Kimliği doğrulanmış kullanıcının kitap raflarının listesini alırken standart sorgu parametrelerini kullanabilirsiniz.

Kitap rafımdaki ciltlerin listesini alma

URI'ya aşağıdaki biçimde bir HTTP GET isteği göndererek kimliği doğrulanmış kullanıcının kitaplığındaki birimlerin listesini alabilirsiniz:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes

shelf path parametresini kitap rafının kimliğiyle değiştirin. Kitap rafı kimlikleriyle ilgili daha fazla bilgi için Google Kitaplar Kimlikleri bölümüne bakın.

İstek

Örnek:

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey
Authorization: /* auth token here */

Not: "Kitaplığım" birimlerinin listesini alabilmek için kullanıcının kimliği doğrulanmalıdır. Bu nedenle GET isteğini Authorization HTTP üst bilgisiyle birlikte sağlamanız gerekir.

Yanıt

İstek başarılı olursa sunucu, 200 OK HTTP durum kodu ve kitap rafı hacimlerinin listesiyle yanıt verir:

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

İsteğe bağlı sorgu parametreleri

Standart sorgu parametrelerine ek olarak, kimliği doğrulanmış kullanıcının kitap raflarından birindeki cilt listesini alırken aşağıdaki sorgu parametresini kullanabilirsiniz.

Sayfalara ayırma

İsteğin parametrelerinde iki değer belirterek birimler listesini sayfalara ayırabilirsiniz:

  • startIndex: Koleksiyonda başlatılacak konum. İlk öğenin dizini 0'dır.
  • maxResults: Döndürülecek maksimum sonuç sayısı. Varsayılan değer 10'dur.

Kitaplığıma cilt ekleme

Kimliği doğrulanmış kullanıcının kitap rafına birim eklemek için URI'ye aşağıdaki biçimde bir HTTP POST isteği gönderin:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume

shelf path parametresini kitap rafının kimliğiyle değiştirin. Kitap rafı kimlikleriyle ilgili daha fazla bilgi için Google Kitaplar Kimlikleri bölümüne bakın.

İsteğin tek bir gerekli sorgu parametresi var:

İstek

"Sık Kullanılanlar" kitap rafına "Algernon için Çiçek" ifadesini eklemek için bir örnek:

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/addVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

Not: Bir kitaplıkta değişiklik yapabilmek için kullanıcının kimliği doğrulanmalıdır. Bu nedenle, POST isteğiyle Authorization HTTP üst bilgisini sağlamanız gerekir. Ancak bu POST için veri gerekmez.

Yanıt

İstek başarılı olursa sunucu, 204 No Content HTTP durum koduyla yanıt verir.

İsteğe bağlı sorgu parametreleri

Kimliği doğrulanmış kullanıcının kitap raflarından birine cilt eklerken standart sorgu parametrelerini kullanabilirsiniz.

Kitaplıktan bir cildi kaldırma

Kimliği doğrulanmış kullanıcının kitaplığındaki bir birimi kaldırmak için URI'ya aşağıdaki biçimde bir HTTP POST gönderin:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume

shelf path parametresini kitap rafının kimliğiyle değiştirin. Kitap rafı kimlikleriyle ilgili daha fazla bilgi için Google Kitaplar Kimlikleri bölümüne bakın.

İsteğin tek bir gerekli sorgu parametresi var:

İstek

"Sık kullanılanlar" kitaplığından "Algernon Çiçekleri"ni içeren bir örnek aşağıda verilmiştir:

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/removeVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

Not: Bir kitaplıkta değişiklik yapabilmek için kullanıcının kimliği doğrulanmalıdır. Bu nedenle, POST isteğiyle Authorization HTTP üst bilgisini sağlamanız gerekir. Ancak bu POST için veri gerekmez.

Yanıt

İstek başarılı olursa sunucu bir 204 No Content durum koduyla yanıt verir.

İsteğe bağlı sorgu parametreleri

Kimliği doğrulanmış kullanıcının kitap raflarının birinden bir birim kaldırırken standart sorgu parametrelerini kullanabilirsiniz.

Kitaplığımdaki tüm ciltleri temizleme

Kimliği doğrulanmış kullanıcının kitaplığındaki tüm ciltleri kaldırmak için URI'ye aşağıdaki biçimde bir HTTP POST gönderin:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes

shelf path parametresini kitap rafının kimliğiyle değiştirin. Kitap rafı kimlikleriyle ilgili daha fazla bilgi için Google Kitaplar Kimlikleri bölümüne bakın.

İstek

"Favoriler" kitap rafını temizlemeyle ilgili bir örneği aşağıda bulabilirsiniz:

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/clearVolumes?key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

Not: Bir kitaplıkta değişiklik yapabilmek için kullanıcının kimliği doğrulanmalıdır. Bu nedenle, POST isteğiyle Authorization HTTP üst bilgisini sağlamanız gerekir. Ancak bu POST için veri gerekmez.

Yanıt

İstek başarılı olursa sunucu 204 No Content durum koduyla yanıt verir.

İsteğe bağlı sorgu parametreleri

Kimliği doğrulanmış kullanıcının kitap raflarındaki tüm ciltleri temizlerken standart sorgu parametrelerini kullanabilirsiniz.

Sorgu parametresi referansı

Books API ile kullanabileceğiniz sorgu parametreleri bu bölümde özetlenmiştir.Tüm parametre değerleri URL kodlamalı olmalıdır.

Standart sorgu parametreleri

Tüm Books API işlemleri için geçerli olan sorgu parametreleri, Sistem Parametreleri bölümünde belgelenmiştir.

API'ye özel sorgu parametreleri

Books API'deki yalnızca belirli işlemler için geçerli olan istek parametreleri aşağıdaki tabloda özetlenmiştir.

Parametre Anlamı Notlar Uygulanabilirlik
download İndirme kullanılabilirliğine göre hacimlerle kısıtlayın.
  • Şu anda epub değeri desteklenmektedir.
  • İndirme erişimi için satın alma gerekebilir.
filter Arama sonuçlarını hacim türüne ve kullanılabilirliğe göre filtreleyin.
  • Desteklenen filtreler şunlardır:
    • filter=partial - Sonuçları, metnin en az bir kısmının önizlenebildiği hacimlerle sınırlandırın.
    • filter=full - Sonuçları, metnin tamamının görüntülenebilir olduğu birimlerle sınırlandırın.
    • filter=free-ebooks - Sonuçları ücretsiz Google e-Kitaplarıyla sınırlandırın.
    • filter=paid-ebooks - Sonuçları, satın alma fiyatı olan Google e-Kitaplar ile sınırlandırın.
    • filter=ebooks - Sonuçları, ücretli veya ücretsiz Google e-Kitaplarıyla sınırlandırın.E-kitap haricindeki örnekler, sınırlı önizlemede olup satışa sunulmayan yayıncı içerikleri veya dergiler olabilir.

 
langRestrict Döndürülen birimleri, belirtilen dille etiketlenmiş birimlerle kısıtlar.
  • langRestrict öğesini "en" veya "fr" gibi iki harfli bir ISO-639-1 koduyla (ör. "en" veya "fr") belirterek arama sonuçlarını belirli bir dile sahip arama sonuçlarıyla sınırlandırın.
maxResults Bu istekle birlikte döndürülecek maksimum öğe sayısı.
  • Bir koleksiyondaki tüm öğelerle ilgili tüm isteklerde, isteğin parametrelerinde startIndex ve maxResults değerlerini belirterek sonuçları sayfalara ayırabilirsiniz.
  • Varsayılan: maxResults=10
  • İzin verilen maksimum değer: maxResults=40.
orderBy

Hacim arama sonuçlarının sırası.

  • Varsayılan olarak, bir arama isteği maxResults sonuçları döndürür. Burada maxResults, sayfalara ayırmada kullanılan parametre olup en alakalı olana göre sıralanır.
  • orderBy parametresini şu değerlerden biri olacak şekilde ayarlayarak sıralamayı değiştirebilirsiniz:
    • orderBy=relevance - Arama sonuçlarını en alakalı olandan en aza doğru döndürür (varsayılan).
    • orderBy=newest - Arama sonuçlarını, en yeni yayınlanma tarihinden en eskiye doğru sırayla döndürür.
printType Kitaplarla veya dergilerle kısıtlayın.
  • Desteklenen değerler:
    • printType=all - Tüm ses düzeyi içerik türlerini döndürür (kısıtlama yoktur). Bu, varsayılan ayardır.
    • printType=books - Yalnızca kitapları iade et.
    • printType=magazines - Yalnızca dergileri döndür.
projection Döndürülen birim bilgilerini belirli alanlar alt kümesiyle sınırlayın.
  • Desteklenen tahminler:
    • projection=full: Tüm cilt meta verilerini içerir (varsayılan).
    • projection=lite: Yalnızca cilt ve erişim meta verilerinin konusunu içerir.
q Tam metin sorgu dizesi.
  • Sorgu oluştururken, arama terimlerini "+" ile ayırarak q=term1+term2_term3 biçiminde listeleyin. (Alternatif olarak, bunları boşlukla ayırabilirsiniz, ancak tüm sorgu parametresi değerlerinde olduğu gibi boşlukların URL kodlamalı olması gerekir.) API, arama terimlerinin tümüyle eşleşen tüm girişleri döndürür (terimler arasında AND kullanımı gibi). Google'ın web araması gibi API de alt dizeleri değil, tam kelimeleri (ve aynı köke sahip ilgili kelimeleri) arar.
  • Tam ifade aramak için kelime öbeğini tırnak içine alın: q="exact phrase".
  • Belirli bir terimle eşleşen girişleri hariç tutmak için q=-term formunu kullanın.
  • Arama terimleri büyük/küçük harfe duyarlı değildir.
  • Örnek: Tam olarak "Elizabeth Bennet" kelime öbeğini ve "Darcy" kelimesini içeren ancak "Austen" kelimesini içermeyen tüm girişleri aramak için şu sorgu parametresi değerini kullanın:
    q="Elizabeth+Bennet"+Darcy-Austen
  • Belirli alanlarda arama yapmak için arama terimlerinde belirtebileceğiniz özel (büyük/küçük harfe duyarlı) anahtar kelimeler bulunur. Örneğin:
    • intitle: Bu anahtar kelimeden sonraki metnin başlıkta bulunduğu sonuçları döndürür.
    • inauthor: Bu anahtar kelimeden sonraki metnin yazarda bulunduğu sonuçları döndürür.
    • inpublisher: Bu anahtar kelimeden sonraki metnin yayıncıda bulunduğu sonuçları döndürür.
    • subject: Bu anahtar kelimeden sonra gelen metnin, hacmin kategori listesinde listelendiği sonuçları döndürür.
    • isbn: Bu anahtar kelimeden sonraki metnin ISBN numarası olduğu sonuçları döndürür.
    • lccn: Bu anahtar kelimeden sonra gelen metnin Kongre Kütüphanesi Kontrol Numarası olduğu sonuçları döndürür.
    • oclc: Bu anahtar kelimeden sonra gelen metnin Çevrimiçi Bilgisayar Kütüphanesi Merkezi numarası olduğu sonuçları döndürür.
startIndex Koleksiyonda sonuç listesinin başlatılacağı konum.
  • Bir koleksiyondaki tüm öğelerle ilgili tüm isteklerde, isteğin parametrelerinde startIndex ve maxResults değerlerini belirterek sonuçları sayfalara ayırabilirsiniz.
  • İlk öğenin dizini 0'dır.
volumeId İstekle ilişkili birimi tanımlar.
  • Bir kitap rafına eklenecek veya kitap rafından kaldırılacak ses düzeyini belirtir.