Menggunakan API

Daftar Isi

  1. Pengantar
    1. Autentikasi dan otorisasi
    2. ID Google Buku
    3. Menetapkan Lokasi Pengguna
  2. Menggunakan volume
    1. Melakukan penelusuran
    2. Mengambil volume tertentu
  3. Bekerja dengan rak buku
    1. Mengambil daftar rak buku publik pengguna
    2. Mengambil rak buku publik tertentu
    3. Mengambil daftar volume di rak buku publik
  4. Menggunakan rak buku di "Koleksi Saya"
    1. Mengambil daftar rak buku saya
    2. Mengambil daftar volume di rak buku saya
    3. Menambahkan volume ke rak buku saya
    4. Menghapus volume dari rak buku saya
    5. Menghapus semua volume dari rak buku saya
  5. Referensi parameter kueri
    1. Parameter kueri standar
    2. Parameter kueri khusus API

Pengantar

Dokumen ini ditujukan bagi developer yang ingin menulis aplikasi yang dapat berinteraksi dengan Books API. Google Buku memiliki misi untuk mendigitalkan konten buku di seluruh dunia dan membuatnya lebih mudah ditemukan di Web. Books API adalah cara untuk menelusuri dan mengakses konten tersebut, serta membuat dan melihat personalisasi seputar konten tersebut.

Jika Anda belum memahami konsep Google Buku, Anda harus membaca Memulai sebelum mulai membuat kode.

Memberi otorisasi permintaan dan mengidentifikasi aplikasi Anda

Setiap permintaan yang dikirimkan aplikasi Anda ke Books API harus mengidentifikasi aplikasi Anda ke Google. Ada dua cara untuk mengidentifikasi aplikasi Anda: menggunakan token OAuth 2.0 (yang juga mengizinkan permintaan) dan/atau menggunakan kunci API aplikasi. Berikut cara menentukan opsi yang akan digunakan:

  • Jika permintaan memerlukan otorisasi (seperti permintaan untuk data pribadi individu), aplikasi harus memberikan token OAuth 2.0 dengan permintaan tersebut. Aplikasi juga dapat memberikan kunci API, tetapi tidak harus.
  • Jika permintaan tidak memerlukan otorisasi (seperti permintaan untuk data publik), aplikasi harus memberikan kunci API atau token OAuth 2.0, atau keduanya—opsi apa pun yang paling nyaman bagi Anda.

Tentang protokol otorisasi

Aplikasi Anda harus menggunakan OAuth 2.0 untuk mengizinkan permintaan. Tidak ada protokol otorisasi lain yang didukung. Jika aplikasi Anda menggunakan Login dengan Google, beberapa aspek otorisasi akan ditangani untuk Anda.

Mengizinkan permintaan dengan OAuth 2.0

Permintaan ke Books API untuk data pengguna non-publik harus diizinkan oleh pengguna terautentikasi.

Detail proses otorisasi, atau "alur", untuk OAuth 2.0 bervariasi bergantung pada jenis aplikasi yang Anda tulis. Proses umum berikut berlaku untuk semua jenis aplikasi:

  1. Saat membuat aplikasi, Anda mendaftarkannya menggunakan Konsol Google API. Selanjutnya, Google menyediakan informasi yang akan Anda perlukan nanti, seperti ID klien dan rahasia klien.
  2. Aktifkan Books API di Konsol API Google. (Jika API tidak tercantum di Konsol API, lewati langkah ini.)
  3. Saat memerlukan akses ke data pengguna, aplikasi Anda akan meminta cakupan akses tertentu kepada Google.
  4. Google menampilkan layar izin kepada pengguna, yang meminta mereka mengizinkan aplikasi Anda untuk meminta beberapa data.
  5. Jika pengguna menyetujui, Google akan memberikan token akses berumur singkat ke aplikasi Anda.
  6. Aplikasi Anda meminta data pengguna, dengan menambahkan token akses ke permintaan.
  7. Jika Google menentukan bahwa permintaan Anda dan token tersebut valid, data yang diminta akan ditampilkan.

Beberapa alur mencakup langkah tambahan, seperti penggunaan token refresh untuk memperoleh token akses baru. Informasi selengkapnya tentang alur untuk berbagai jenis aplikasi dapat dilihat di dokumentasi OAuth 2.0 Google.

Berikut informasi cakupan OAuth 2.0 untuk Books API:

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

Untuk meminta akses menggunakan OAuth 2.0, aplikasi Anda memerlukan informasi cakupan, serta informasi yang disediakan oleh Google saat Anda mendaftarkan aplikasi (seperti ID klien dan rahasia klien).

Tips: Library klien Google API dapat menangani beberapa proses otorisasi secara otomatis. Library klien ini tersedia untuk berbagai bahasa pemrograman. Periksa halaman yang menjelaskan library beserta contohnya untuk mendapatkan informasi lebih mendetail.

Mendapatkan dan menggunakan kunci API

Permintaan ke Books API untuk data publik harus disertai dengan ID, yang dapat berupa kunci API atau token akses.

Untuk mendapatkan kunci API:

  1. Buka halaman Kredensial di Konsol API.
  2. API ini mendukung dua jenis kredensial. Buat kredensial yang sesuai untuk project Anda:

    • OAuth 2.0: Setiap kali aplikasi Anda meminta data pengguna pribadi, aplikasi tersebut harus mengirimkan token OAuth 2.0 bersama dengan permintaan. Aplikasi Anda pertama-tama mengirimkan client ID dan, mungkin, secret klien untuk mendapatkan token. Anda dapat membuat kredensial OAuth 2.0 untuk aplikasi web, akun layanan, atau aplikasi terinstal.

      Untuk informasi selengkapnya, lihat dokumentasi OAuth 2.0.

    • Kunci API: Permintaan yang tidak memberikan token OAuth 2.0 harus mengirimkan kunci API. Kunci ini mengidentifikasi project Anda dan memberikan akses, kuota, dan laporan API.

      API ini mendukung beberapa jenis pembatasan pada kunci API. Jika kunci API yang Anda perlukan belum ada, buat kunci API di Konsol dengan mengklik Create credentials  > API key. Anda dapat membatasi kunci sebelum menggunakannya dalam produksi dengan mengklik Batasi kunci dan memilih salah satu Batasan.

Untuk menjaga keamanan kunci API Anda, ikuti praktik terbaik untuk menggunakan kunci API dengan aman.

Setelah memiliki kunci API, aplikasi Anda dapat menambahkan parameter kueri key=yourAPIKey ke semua URL permintaan.

Kunci API aman untuk disematkan di URL; kunci API tidak memerlukan encoding apa pun.

ID Google Buku

Anda harus menentukan kolom ID dengan panggilan metode API tertentu. Ada tiga jenis ID yang digunakan dalam Google Buku:

  • ID Volume - String unik yang diberikan ke setiap volume yang diketahui Google Buku. Contoh ID volume adalah _LettPDhwR0C. Anda dapat menggunakan API untuk mendapatkan ID volume dengan membuat permintaan yang menampilkan resource Volume; Anda dapat menemukan ID volume di kolom id-nya.
  • ID Rak Buku - Nilai numerik yang diberikan ke rak buku di library pengguna. Google menyediakan beberapa galeri yang telah ditentukan sebelumnya untuk setiap pengguna dengan ID berikut:
    • Favorit: 0
    • Dibeli: 1
    • Untuk Dibaca: 2
    • Sedang Membaca: 3
    • Sudah Dibaca: 4
    • Ditinjau: 5
    • Baru Dilihat: 6
    • eBook Saya: 7
    • Buku untuk Anda: 8 Jika kami tidak memiliki rekomendasi untuk pengguna, galeri ini tidak akan ada.
    Galeri kustom memiliki ID lebih besar dari 1.000. ID rak buku bersifat unik untuk pengguna tertentu, yaitu, dua pengguna dapat memiliki rak buku dengan ID yang sama yang merujuk ke rak buku yang berbeda. Anda dapat menggunakan API untuk mendapatkan ID rak buku dengan membuat permintaan yang menampilkan resource Bookshelf; Anda dapat menemukan ID rak buku di kolom id-nya.
  • ID Pengguna - Nilai numerik unik yang ditetapkan untuk setiap pengguna. Nilai ini tidak harus sama dengan nilai ID yang digunakan di layanan Google lainnya. Saat ini, satu-satunya cara untuk mengambil ID pengguna adalah dengan mengekstraknya dari selfLink di resource Bookshelf yang diambil dengan permintaan yang diautentikasi. Pengguna juga dapat memperoleh ID pengguna mereka sendiri dari situs Buku. Pengguna tidak dapat mendapatkan ID pengguna untuk pengguna lain melalui API atau situs Buku; pengguna lain harus membagikan informasi tersebut secara eksplisit, misalnya melalui email.

ID di situs Google Buku

ID yang Anda gunakan dengan Books API adalah ID yang sama dengan yang digunakan di situs Google Buku.

  • ID Volume

    Saat melihat volume tertentu di situs, Anda dapat menemukan ID volume di parameter URL id. Berikut ini contohnya: 

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

  • ID Bookshelf

    Saat melihat rak buku tertentu di situs, Anda dapat menemukan ID rak buku di parameter URL as_coll. Berikut ini contohnya: 

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

  • ID Pengguna

    Saat melihat library di situs, Anda dapat menemukan ID pengguna di parameter URL uid. Berikut ini contohnya: 

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

Menetapkan Lokasi Pengguna

Google Buku menghormati hak cipta, kontrak, dan batasan hukum lainnya yang terkait dengan lokasi pengguna akhir. Akibatnya, beberapa pengguna mungkin tidak dapat mengakses konten buku dari negara tertentu. Misalnya, buku tertentu hanya dapat "dilihat pratinjaunya" di Amerika Serikat; kami menghapus link pratinjau tersebut untuk pengguna di negara lain. Oleh karena itu, hasil API dibatasi berdasarkan alamat IP server atau aplikasi klien Anda.

Menggunakan volume

Menjalankan penelusuran

Anda dapat melakukan penelusuran volume dengan mengirimkan permintaan GET HTTP ke URI berikut:

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

Permintaan ini memiliki satu parameter wajib:

  • q - Menelusuri volume yang berisi string teks ini. Ada kata kunci khusus yang dapat Anda tentukan dalam istilah penelusuran untuk menelusuri di kolom tertentu, seperti:
    • intitle: Menampilkan hasil dengan teks yang mengikuti kata kunci ini ditemukan dalam judul.
    • inauthor: Menampilkan hasil dengan teks yang mengikuti kata kunci ini ditemukan di penulis.
    • inpublisher: Menampilkan hasil tempat teks yang mengikuti kata kunci ini ditemukan di penayang.
    • subject: Menampilkan hasil dengan teks yang mengikuti kata kunci ini tercantum dalam daftar kategori volume.
    • isbn: Menampilkan hasil dengan teks yang mengikuti kata kunci ini adalah nomor ISBN.
    • lccn: Menampilkan hasil dengan teks yang mengikuti kata kunci ini adalah Nomor Kontrol Perpustakaan Kongres.
    • oclc: Menampilkan hasil dengan teks yang mengikuti kata kunci ini adalah nomor Pusat Perpustakaan Komputer Online.

Permintaan

Berikut adalah contoh penelusuran "Flowers for Algernon" karya Daniel Keyes: 

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

Catatan: Melakukan penelusuran tidak memerlukan autentikasi, sehingga Anda tidak perlu memberikan header HTTP Authorization dengan permintaan GET. Namun, jika panggilan dilakukan dengan autentikasi, setiap Volume akan menyertakan informasi khusus pengguna, seperti status yang dibeli.

Respons

Jika permintaan berhasil, server akan merespons dengan kode status HTTP 200 OK dan hasil volume:

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
}

Parameter kueri opsional

Selain parameter kueri standar, Anda dapat menggunakan parameter kueri berikut saat melakukan penelusuran volume.

Format Download

Anda menggunakan parameter download untuk membatasi hasil yang ditampilkan ke volume yang memiliki format download epub yang tersedia dengan menetapkan ke nilai epub.

Contoh berikut menelusuri buku dengan download epub yang tersedia:

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

Anda dapat menggunakan parameter filter untuk membatasi hasil yang ditampilkan lebih lanjut dengan menetapkannya ke salah satu nilai berikut:

  • partial - Menampilkan hasil dengan setidaknya sebagian teks dapat dilihat pratinjaunya.
  • full - Hanya menampilkan hasil jika semua teks dapat dilihat.
  • free-ebooks - Hanya menampilkan hasil yang merupakan Google eBook gratis.
  • paid-ebooks - Hanya menampilkan hasil yang merupakan eBook Google dengan harga.
  • ebooks - Hanya menampilkan hasil yang merupakan eBook Google, berbayar atau gratis. Contoh non-eBook adalah konten penayang yang tersedia dalam pratinjau terbatas dan tidak dijual, atau majalah.

Contoh berikut membatasi hasil penelusuran pada hasil yang tersedia sebagai eBook gratis:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey
Penomoran halaman

Anda dapat membuat penomoran halaman daftar volume dengan menentukan dua nilai dalam parameter untuk permintaan:

  • startIndex - Posisi dalam koleksi tempat untuk memulai. Indeks item pertama adalah 0.
  • maxResults - Jumlah hasil maksimum yang akan ditampilkan. Nilai defaultnya adalah 10, dan nilai maksimum yang diizinkan adalah 40.

Anda dapat menggunakan parameter printType untuk membatasi hasil yang ditampilkan ke jenis cetak atau publikasi tertentu dengan menetapkannya ke salah satu nilai berikut:

  • all - Tidak membatasi menurut jenis pencetakan (default).
  • books - Hanya menampilkan hasil yang berupa buku.
  • magazines - Menampilkan hasil yang berupa majalah.

Contoh berikut membatasi hasil penelusuran ke majalah:

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

Anda dapat menggunakan parameter projection dengan salah satu nilai berikut untuk menentukan kumpulan kolom Volume yang telah ditentukan sebelumnya untuk ditampilkan:

  • full - Menampilkan semua kolom Volume.
  • lite - Hanya menampilkan kolom tertentu. Lihat deskripsi kolom yang ditandai dengan tanda bintang ganda di Referensi volume untuk mengetahui kolom mana yang disertakan.

Contoh berikut menampilkan hasil penelusuran dengan informasi volume terbatas:

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

Secara default, permintaan penelusuran volume menampilkan hasil maxResults, dengan maxResults adalah parameter yang digunakan dalam penomoran halaman (di atas), yang diurutkan berdasarkan relevansi dengan istilah penelusuran.

Anda dapat mengubah pengurutan dengan menetapkan parameter orderBy  menjadi salah satu nilai berikut:

  • relevance - Menampilkan hasil berdasarkan urutan relevansi istilah penelusuran (ini adalah default).
  • newest - Menampilkan hasil dalam urutan terbaru hingga paling lama dipublikasikan.

Contoh berikut mencantumkan hasil berdasarkan tanggal publikasi, dari yang terbaru hingga terlama:

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

Mengambil volume tertentu

Anda dapat mengambil informasi untuk volume tertentu dengan mengirim permintaan GET HTTP ke URI resource Volume:

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

Ganti parameter jalur volumeId dengan ID volume yang akan diambil. Lihat bagian ID Google Buku untuk mengetahui informasi selengkapnya tentang ID volume.

Permintaan

Berikut adalah contoh permintaan GET yang mendapatkan satu volume:

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

Catatan: Pengambilan informasi volume tidak memerlukan autentikasi, sehingga Anda tidak perlu memberikan header HTTP Authorization dengan permintaan GET. Namun, jika panggilan dilakukan dengan autentikasi, Volume akan menyertakan informasi khusus pengguna, seperti status yang dibeli.

Respons

Jika permintaan berhasil, server akan merespons dengan kode status HTTP 200 OK dan resource Volume yang diminta:

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"
 }
}
Info Akses

Bagian accessInfo sangat menarik untuk menentukan fitur yang tersedia untuk eBook. epub adalah eBook dalam format teks yang mengalir, bagian epub akan memiliki properti isAvailable yang menunjukkan apakah jenis eBook ini tersedia. Halaman ini akan memiliki link download jika ada sampel untuk buku tersebut atau jika pengguna dapat membaca buku karena telah membelinya atau karena buku tersebut merupakan domain publik di lokasi pengguna. pdf untuk buku Google menunjukkan versi halaman yang dipindai dari eBook dengan detail serupa seperti apakah tersedia dan link download. Google merekomendasikan file epub untuk eReader dan SmartPhone, karena halaman yang dipindai mungkin sulit dibaca di perangkat ini. Jika tidak ada bagian accessInfo, volume tidak tersedia sebagai eBook Google.

Parameter kueri opsional

Selain parameter kueri standar, Anda dapat menggunakan parameter kueri berikut saat mengambil volume tertentu.

Proyeksi

Anda dapat menggunakan parameter projection dengan salah satu nilai berikut untuk menentukan kumpulan kolom Volume yang telah ditentukan sebelumnya untuk ditampilkan:

  • full - Menampilkan semua kolom Volume.
  • lite - Hanya menampilkan kolom tertentu. Lihat deskripsi kolom yang ditandai dengan tanda bintang ganda di Referensi volume untuk mengetahui kolom mana yang disertakan.

Contoh berikut menampilkan informasi volume terbatas untuk satu volume:

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

Menggunakan rak buku

Mengambil daftar rak buku publik pengguna

Anda dapat mengambil daftar rak buku publik pengguna dengan mengirimkan permintaan GET HTTP ke URI dengan format berikut:

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

Ganti parameter jalur userId dengan ID pengguna yang rak bukunya ingin Anda ambil. Lihat bagian ID Google Buku untuk mengetahui informasi selengkapnya tentang ID pengguna.

Permintaan

Berikut ini contohnya:

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

Karena pengguna tidak perlu diautentikasi untuk mengambil informasi terkait rak buku publik, Anda tidak perlu memberikan header HTTP Authorization dengan permintaan GET.

Respons

Jika permintaan berhasil, server akan merespons dengan kode status HTTP 200 OK dan daftar rak buku:

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"
  },
  ...
 ]
}

Parameter kueri opsional

Anda dapat menggunakan parameter kueri standar saat mengambil daftar rak buku publik pengguna.

Mengambil rak buku publik tertentu

Anda dapat mengambil rak buku publik tertentu dengan mengirimkan permintaan GET HTTP ke URI dengan format berikut:

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

Ganti parameter jalur userId dan shelf dengan ID yang menentukan pengguna dan rak buku yang ingin Anda ambil. Lihat bagian ID Google Buku untuk mengetahui informasi selengkapnya.

Permintaan

Berikut ini contohnya:

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

Karena pengguna tidak perlu diautentikasi untuk mengambil informasi terkait rak buku publik, Anda tidak perlu memberikan header HTTP Authorization dengan permintaan GET.

Respons

Jika permintaan berhasil, server akan merespons dengan kode status HTTP 200 OK dan resource rak buku:

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"
}

Parameter kueri opsional

Anda dapat menggunakan parameter kueri standar saat mengambil rak buku publik tertentu.

Mengambil daftar volume di rak buku publik

Anda dapat mengambil daftar volume di rak buku publik pengguna dengan mengirimkan permintaan GET HTTP ke URI dengan format berikut:

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

Permintaan

Berikut ini contohnya:

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

Ganti parameter jalur userId dan shelf dengan ID yang menentukan pengguna dan rak buku yang ingin Anda ambil. Lihat bagian ID Google Buku untuk mengetahui informasi selengkapnya.

Karena pengguna tidak perlu diautentikasi untuk mengambil informasi terkait rak buku publik, Anda tidak perlu memberikan header HTTP Authorization dengan permintaan GET.

Respons

Jika permintaan berhasil, server akan merespons dengan kode status HTTP 200 OK dan daftar rak buku pengguna:

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
}

Parameter kueri opsional

Selain parameter kueri standar, Anda dapat menggunakan parameter kueri berikut saat mengambil daftar volume di rak buku publik.

Penomoran halaman

Anda dapat membuat penomoran halaman daftar volume dengan menentukan dua nilai dalam parameter untuk permintaan:

  • startIndex - Posisi dalam koleksi tempat untuk memulai. Indeks item pertama adalah 0.
  • maxResults - Jumlah hasil maksimum yang akan ditampilkan. Nilai defaultnya adalah 10, dan nilai maksimum yang diizinkan adalah 40.

Menggunakan rak buku di "Koleksi Saya"

Semua permintaan "Koleksi Saya" berlaku untuk data pengguna terautentikasi.

Mengambil daftar rak buku saya

Anda dapat mengambil listingan semua rak buku pengguna terautentikasi dengan mengirim permintaan GET HTTP ke URI dengan format berikut: 

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

Permintaan

Berikut ini contohnya:

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

Catatan: Pengguna harus diautentikasi untuk mengambil listingan rak buku "Pustaka Saya". Jadi, Anda harus memberikan header HTTP Authorization dengan permintaan GET.

Respons

Jika permintaan berhasil, server akan merespons dengan kode status HTTP 200 OK dan daftar semua galeri buku untuk pengguna yang diautentikasi saat ini:

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"
  }
 ]
}

Parameter kueri opsional

Anda dapat menggunakan parameter kueri standar saat mengambil daftar galeri buku pengguna yang diautentikasi.

Mengambil daftar volume di rak buku saya

Anda dapat mengambil listingan volume di rak buku pengguna yang diautentikasi dengan mengirim permintaan GET HTTP ke URI dengan format berikut:

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

Ganti parameter jalur rak dengan ID rak buku. Lihat bagian ID Google Buku untuk mengetahui informasi selengkapnya tentang ID rak buku.

Permintaan

Berikut ini contohnya:

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

Catatan: Pengguna harus diautentikasi untuk mengambil listingan volume "Koleksi Saya". Jadi, Anda harus memberikan header HTTP Authorization dengan permintaan GET.

Respons

Jika permintaan berhasil, server akan merespons dengan kode status HTTP 200 OK dan daftar volume rak buku:

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
}

Parameter kueri opsional

Selain parameter kueri standar, Anda dapat menggunakan parameter kueri berikut saat mengambil daftar volume di salah satu rak buku pengguna yang diautentikasi.

Penomoran halaman

Anda dapat membuat penomoran halaman daftar volume dengan menentukan dua nilai dalam parameter untuk permintaan:

  • startIndex - Posisi dalam koleksi tempat untuk memulai. Indeks item pertama adalah 0.
  • maxResults - Jumlah hasil maksimum yang akan ditampilkan. Defaultnya adalah 10.

Menambahkan volume ke rak buku saya

Untuk menambahkan volume ke rak buku pengguna terautentikasi, kirim permintaan POST HTTP ke URI dengan format berikut:

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

Ganti parameter jalur rak dengan ID rak buku. Lihat bagian ID Google Buku untuk mengetahui informasi selengkapnya tentang ID rak buku.

Permintaan memiliki satu parameter kueri yang diperlukan:

  • volumeId - ID volume. Lihat bagian ID Google Buku untuk mengetahui informasi selengkapnya tentang ID volume.

Permintaan

Berikut adalah contoh untuk menambahkan "Flowers for Algernon" ke rak buku "Favorit":

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

Catatan: Pengguna harus diautentikasi untuk melakukan perubahan pada rak buku, sehingga Anda harus memberikan header HTTP Authorization dengan permintaan POST. Namun, tidak ada data yang diperlukan dengan POST ini.

Respons

Jika permintaan berhasil, server akan merespons dengan kode status HTTP 204 No Content.

Parameter kueri opsional

Anda dapat menggunakan parameter kueri standar saat menambahkan volume ke salah satu rak buku pengguna yang diautentikasi.

Menghapus volume dari rak buku saya

Untuk menghapus volume dari rak buku pengguna terautentikasi, kirim POST HTTP ke URI dengan format berikut:

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

Ganti parameter jalur rak dengan ID rak buku. Lihat bagian ID Google Buku untuk mengetahui informasi selengkapnya tentang ID rak buku.

Permintaan memiliki satu parameter kueri yang diperlukan:

  • volumeId - ID volume. Lihat bagian ID Google Buku untuk mengetahui informasi selengkapnya tentang ID volume.

Permintaan

Berikut adalah contoh untuk menghapus "Flowers for Algernon" dari rak buku "Favorit":

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

Catatan: Pengguna harus diautentikasi untuk melakukan perubahan pada rak buku, sehingga Anda harus memberikan header HTTP Authorization dengan permintaan POST. Namun, tidak ada data yang diperlukan dengan POST ini.

Respons

Jika permintaan berhasil, server akan merespons dengan kode status 204 No Content.

Parameter kueri opsional

Anda dapat menggunakan parameter kueri standar saat menghapus volume dari salah satu rak buku pengguna terautentikasi.

Menghapus semua volume dari rak buku saya

Untuk menghapus semua volume dari rak buku pengguna terautentikasi, kirim POST HTTP ke URI dengan format berikut:

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

Ganti parameter jalur rak dengan ID rak buku. Lihat bagian ID Google Buku untuk mengetahui informasi selengkapnya tentang ID rak buku.

Permintaan

Berikut adalah contoh untuk menghapus rak buku "Favorit":

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

Catatan: Pengguna harus diautentikasi untuk melakukan perubahan pada rak buku, sehingga Anda harus memberikan header HTTP Authorization dengan permintaan POST. Namun, tidak ada data yang diperlukan dengan POST ini.

Respons

Jika permintaan berhasil, server akan merespons dengan kode status 204 No Content.

Parameter kueri opsional

Anda dapat menggunakan parameter kueri standar saat menghapus semua volume dari salah satu rak buku pengguna yang diautentikasi.

Referensi parameter kueri

Parameter kueri yang dapat Anda gunakan dengan Books API diringkas di bagian ini.  Semua nilai parameter harus dienkode ke URL.

Parameter kueri standar

Parameter kueri yang berlaku untuk semua operasi Books API didokumentasikan di Parameter Sistem.

Parameter kueri khusus API

Parameter permintaan yang hanya berlaku untuk operasi tertentu di Books API dirangkum dalam tabel berikut.

Parameter Arti Catatan Penerapan
download Membatasi volume berdasarkan ketersediaan download.
  • Saat ini, satu-satunya nilai yang didukung adalah epub.
  • Pembelian mungkin diperlukan untuk akses download.
filter Filter hasil penelusuran menurut jenis volume dan ketersediaan.
  • Filter yang didukung adalah:
    • filter=partial - Membatasi hasil ke volume yang setidaknya sebagian teksnya dapat dilihat pratinjaunya.
    • filter=full - Membatasi hasil ke volume yang semua teksnya dapat dilihat.
    • filter=free-ebooks - Membatasi hasil pada eBook Google gratis.
    • filter=paid-ebooks - Membatasi hasil ke eBook Google dengan harga untuk pembelian.
    • filter=ebooks - Membatasi hasil ke eBook Google, berbayar atau gratis.Contoh non-eBook adalah konten penerbit yang tersedia dalam pratinjau terbatas dan tidak dijual, atau majalah.

 
langRestrict Membatasi volume yang ditampilkan ke volume yang diberi tag dengan bahasa yang ditentukan.
  • Batasi hasil penelusuran ke hasil dengan bahasa tertentu dengan menentukan langRestrict ke kode ISO-639-1 dua huruf, seperti "en" atau "fr".
maxResults Jumlah maksimum elemen yang akan ditampilkan dengan permintaan ini.
  • Untuk permintaan apa pun untuk semua item dalam koleksi, Anda dapat membuat penomoran halaman hasil dengan menentukan startIndex dan maxResults dalam parameter untuk permintaan.
  • Default: maxResults=10
  • Nilai maksimum yang diizinkan: maxResults=40.
orderBy

Urutan hasil penelusuran volume.

  • Secara default, permintaan penelusuran menampilkan hasil maxResults, dengan maxResults adalah parameter yang digunakan dalam penomoran halaman, yang diurutkan berdasarkan yang paling relevan terlebih dahulu.
  • Anda dapat mengubah pengurutan dengan menetapkan parameter orderBy menjadi salah satu nilai berikut:
    • orderBy=relevance - Menampilkan hasil penelusuran dalam urutan dari yang paling relevan hingga yang paling tidak relevan (ini adalah default).
    • orderBy=newest - Menampilkan hasil penelusuran dalam urutan tanggal publikasi terbaru ke terlama.
printType Batasi ke buku atau majalah.
  • Nilai yang didukung adalah:
    • printType=all - Menampilkan semua jenis konten volume (tanpa batasan). Ini adalah defaultnya.
    • printType=books - Hanya menampilkan buku.
    • printType=magazines - Hanya menampilkan majalah.
projection Membatasi informasi volume yang ditampilkan ke subset kolom.
  • Proyeksi yang didukung adalah:
    • projection=full - Menyertakan semua metadata volume (default).
    • projection=lite - Hanya menyertakan subjek volume dan metadata akses.
q String kueri teks lengkap.
  • Saat membuat kueri, cantumkan istilah penelusuran yang dipisahkan dengan '+', dalam bentuk q=term1+term2_term3. (Atau, Anda dapat memisahkannya dengan spasi, tetapi seperti semua nilai parameter kueri, spasi tersebut harus dienkode ke URL.) API menampilkan semua entri yang cocok dengan semua istilah penelusuran (seperti menggunakan AND di antara istilah). Seperti penelusuran web Google, API ini menelusuri kata lengkap (dan kata terkait dengan akar yang sama), bukan substring.
  • Untuk menelusuri frasa yang sama persis, sertakan frasa dalam tanda petik: q="exact phrase".
  • Untuk mengecualikan entri yang cocok dengan istilah tertentu, gunakan formulir q=-term.
  • Istilah penelusuran tidak peka huruf besar/kecil.
  • Contoh: untuk menelusuri semua entri yang berisi frasa persis "Elizabeth Bennet" dan kata "Darcy", tetapi tidak berisi kata "Austen", gunakan nilai parameter kueri berikut:
    q="Elizabeth+Bennet"+Darcy-Austen
  • Ada kata kunci khusus (peka huruf besar/kecil) yang dapat Anda tentukan dalam istilah penelusuran untuk menelusuri di kolom tertentu, seperti:
    • intitle: Menampilkan hasil dengan teks yang mengikuti kata kunci ini ditemukan dalam judul.
    • inauthor: Menampilkan hasil dengan teks yang mengikuti kata kunci ini ditemukan di penulis.
    • inpublisher: Menampilkan hasil dengan teks yang mengikuti kata kunci ini ditemukan di penayang.
    • subject: Menampilkan hasil dengan teks yang mengikuti kata kunci ini tercantum dalam daftar kategori volume.
    • isbn: Menampilkan hasil dengan teks yang mengikuti kata kunci ini adalah nomor ISBN.
    • lccn: Menampilkan hasil dengan teks yang mengikuti kata kunci ini adalah Nomor Kontrol Library of Congress.
    • oclc: Menampilkan hasil dengan teks yang mengikuti kata kunci ini adalah nomor Online Computer Library Center.
startIndex Posisi dalam koleksi tempat daftar hasil akan dimulai.
  • Untuk permintaan apa pun untuk semua item dalam koleksi, Anda dapat membuat penomoran halaman hasil dengan menentukan startIndex dan maxResults dalam parameter untuk permintaan.
  • Indeks item pertama adalah 0.
volumeId Mengidentifikasi volume yang terkait dengan permintaan.
  • Menentukan volume yang akan ditambahkan atau dihapus dari rak buku.