API 사용

콘텐츠

소개

이 문서는 Books API와 상호작용할 수 있는 애플리케이션을 작성하려는 개발자를 대상으로 합니다. Google 도서의 목표는 전 세계의 도서 콘텐츠를 디지털화하여 웹에서의 검색 가능성을 높이는 것입니다. Books API를 사용하면 콘텐츠를 검색하고 액세스할 수 있을 뿐만 아니라 콘텐츠에 관한 맞춤설정을 만들고 확인할 수 있습니다.

Google 도서 개념에 익숙하지 않은 경우 코딩을 시작하기 전에 시작하기를 읽어야 합니다.

요청 승인 및 애플리케이션 식별

애플리케이션에서 Books API로 전송하는 모든 요청은 Google에 애플리케이션을 식별하는 데 필요합니다. 애플리케이션을 식별하는 방법에는 OAuth 2.0 토큰을 사용하거나(이 토큰은 요청도 승인함) 애플리케이션의 API 키를 사용하는 두 가지 방법이 있습니다. 다음과 같은 방법으로 사용할 옵션을 결정합니다.

  • 요청에 승인이 필요한 경우 (예: 개별 사용자의 비공개 데이터 요청) 애플리케이션은 요청과 함께 OAuth 2.0 토큰을 제공해야 합니다. 애플리케이션은 API 키를 제공할 수도 있지만 꼭 그럴 필요는 없습니다.
  • 요청에 승인이 필요하지 않은 경우(예: 공개 데이터 요청) 애플리케이션은 API 키 또는 OAuth 2.0 토큰 중 하나 또는 둘 다를 편의에 따라 제공해야 합니다.

승인 프로토콜 정보

요청을 승인하려면 애플리케이션에서 OAuth 2.0을 사용해야 합니다. 다른 승인 프로토콜은 지원되지 않습니다. 애플리케이션에서 Google 계정으로 로그인을 사용하는 경우 승인의 일부 절차는 자동으로 처리됩니다.

OAuth 2.0을 사용하여 요청 승인

Books API에 대한 비공개 사용자 데이터 요청은 인증된 사용자의 승인을 받아야 합니다.

OAuth 2.0의 승인 과정 세부사항('흐름')은 만들고 있는 애플리케이션의 종류에 따라 다소 다릅니다. 다음의 일반적인 과정은 모든 애플리케이션 유형에 적용됩니다.

  1. 애플리케이션을 만들 때 Google API 콘솔을 사용하여 애플리케이션을 등록합니다. 이렇게 하면 Google에서 클라이언트 ID 및 클라이언트 보안 비밀번호와 같이 나중에 필요한 정보를 제공합니다.
  2. Google API 콘솔에서 Books API를 활성화합니다. API 콘솔의 목록에 이 API가 없다면 이 단계를 건너뜁니다.
  3. 애플리케이션에서 사용자 데이터에 액세스해야 하는 경우 Google에 특정 액세스 범위를 요청합니다.
  4. Google에서 사용자에게 애플리케이션의 데이터 요청을 승인할 것인지 물어보는 동의 화면을 표시합니다.
  5. 사용자가 승인하면 Google에서 애플리케이션에 제한 시간이 있는 단기 액세스 토큰을 제공합니다.
  6. 애플리케이션에서 액세스 토큰을 첨부하여 사용자 데이터를 요청합니다.
  7. Google에서 사용자의 요청과 토큰이 유효하다고 판단하면 요청된 데이터를 반환합니다.

일부 흐름에는 새로운 액세스 토큰을 얻기 위해 갱신 토큰을 사용하는 등의 추가 단계가 포함됩니다. 다양한 유형의 애플리케이션 흐름에 관한 자세한 내용은 Google의 OAuth 2.0 문서를 참조하세요.

다음은 도서 API에 대한 OAuth 2.0 범위 정보입니다.

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

OAuth 2.0을 사용하여 액세스를 요청하려면 애플리케이션에 범위 정보와 함께 애플리케이션을 등록할 때 Google에서 제공하는 정보(예: 클라이언트 ID, 클라이언트 보안 비밀)가 필요합니다.

팁: Google API 클라이언트 라이브러리가 사용자를 대신하여 일부 승인 과정을 처리할 수 있습니다. 여러 가지 프로그래밍 언어로 제공되므로 자세한 내용은 라이브러리 및 샘플 페이지를 참조하세요.

API 키 획득 및 사용

Books API for Public Data 요청에는 식별자가 함께 제공되어야 합니다. 식별자는 API 키 또는 액세스 토큰일 수 있습니다.

API 키를 획득하려면 다음 안내를 따르세요.

  1. API 콘솔에서 사용자 인증 정보 페이지를 엽니다.
  2. 이 API는 두 가지 유형의 사용자 인증 정보를 지원합니다. 프로젝트에 적합한 사용자 인증 정보를 만듭니다.
    • OAuth 2.0: 애플리케이션에서 비공개 사용자 데이터를 요청할 때마다 요청과 함께 OAuth 2.0 토큰을 보내야 합니다. 애플리케이션은 먼저 토큰을 획득하기 위해 클라이언트 ID나 클라이언트 보안 비밀번호를 보냅니다. 웹 애플리케이션, 서비스 계정, 설치된 애플리케이션의 OAuth 2.0 사용자 인증 정보를 생성할 수 있습니다.

      자세한 내용은 OAuth 2.0 문서를 참조하세요.

    • API 키: OAuth 2.0 토큰을 제공하지 않는 요청은 API 키를 전송해야 합니다. 키는 프로젝트를 식별하고 API 액세스, 할당량, 보고서를 제공합니다.

      API는 여러 유형의 API 키 제한 사항을 지원합니다. 필요한 API 키가 아직 없는 경우 사용자 인증 정보 만들기 > API 키를 클릭하여 Console에서 API 키를 만듭니다. 프로덕션 단계에서 사용하기 전에 키 제한을 클릭하고 제한사항 중 하나를 선택하여 키를 제한할 수 있습니다.

API 키를 안전하게 보호하려면 API 키를 안전하게 사용하기 위한 권장사항을 따르세요.

API 키가 있으면 애플리케이션은 모든 요청 URL에 쿼리 매개변수 key=yourAPIKey를 추가할 수 있습니다.

API 키는 URL에 포함하기에 안전합니다. 인코딩이 전혀 필요하지 않습니다.

Google 도서 ID

특정 API 메서드 호출로 ID 필드를 지정해야 합니다. Google 도서에서 사용하는 ID 유형에는 세 가지가 있습니다.

  • 볼륨 ID - Google 도서가 인식하는 각 볼륨에 지정된 고유 문자열입니다. 볼륨 ID의 예는 _LettPDhwR0C입니다. API를 사용하여 볼륨 리소스를 반환하는 요청을 통해 볼륨 ID를 가져올 수 있습니다. 볼륨 ID는 id 필드에서 확인할 수 있습니다.
  • 서가 ID - 사용자 라이브러리의 서가에 지정된 숫자 값입니다. Google은 모든 사용자에게 다음과 같은 ID로 미리 정의된 서가를 제공합니다.
    • 즐겨찾기: 0
    • 구매일: 1
    • 읽을 메시지: 2
    • 지금 읽기: 3
    • 읽은 도서: 4
    • 검토됨: 5
    • 최근에 본 항목: 6
    • 내 eBook: 7
    • 추천 도서: 8 사용자를 위한 추천 도서가 없다면 이 서가는 존재하지 않습니다.
    맞춤 서가의 ID가 1,000개를 초과합니다. 서가 ID는 특정 사용자에게 고유합니다. 즉, 사용자 2명이 동일한 서가를 사용하여 서로 다른 서가를 참조할 수 있습니다. API를 사용하여 서가 리소스를 반환하는 요청을 통해 서가 ID를 가져올 수 있습니다. 서가 ID는 id 필드에서 찾을 수 있습니다.
  • 사용자 ID - 각 사용자에게 할당된 고유한 숫자 값입니다. 이러한 값은 다른 Google 서비스에서 사용되는 ID 값과 반드시 동일하지는 않습니다. 현재 사용자 ID를 검색하는 유일한 방법은 인증된 요청으로 검색된 북마크 리소스의 자체 링크에서 사용자 ID를 추출하는 것입니다. 사용자는 도서 사이트에서 자신의 사용자 ID를 얻을 수도 있습니다. 사용자는 API 또는 도서 사이트를 통해 다른 사용자의 사용자 ID를 얻을 수 없습니다. 예를 들어 다른 사용자는 이메일로 이 정보를 명시적으로 공유해야 합니다.

Google 도서 사이트의 ID

Books API에서 사용하는 ID는 Google Books 사이트에서 사용되는 ID와 동일합니다.

  • 볼륨 ID

    사이트의 특정 볼륨을 볼 때 id URL 매개변수에서 볼륨 ID를 확인할 수 있습니다. 예를 들면 다음과 같습니다.

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

  • 서가 ID

    사이트의 특정 서가를 볼 때 as_coll URL 매개변수에서 서가 ID를 찾을 수 있습니다. 예를 들면 다음과 같습니다.

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

  • 사용자 ID

    사이트에서 라이브러리를 볼 때 uid URL 매개변수에서 사용자 ID를 찾을 수 있습니다. 예를 들면 다음과 같습니다.

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

사용자 위치 설정

Google 도서는 최종 사용자의 위치와 관련된 저작권, 계약 및 기타 법적 제한을 따릅니다. 따라서 일부 사용자는 특정 국가의 책 콘텐츠에 액세스하지 못할 수 있습니다. 예를 들어 특정 도서는 미국에서만 '미리보기 가능'합니다. 다른 국가의 사용자에게는 이러한 미리보기 링크가 생략되어 있습니다. 따라서 서버나 클라이언트 애플리케이션의 IP 주소에 따라 API 결과가 제한됩니다.

볼륨 작업

검색하기

다음 URI에 HTTP GET 요청을 전송하여 볼륨 검색을 수행할 수 있습니다.

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

이 요청에는 필수 매개변수가 하나 있습니다.

  • q - 이 텍스트 문자열이 포함된 볼륨을 검색합니다. 검색어에서 특정 필드를 검색하기 위해 지정할 수 있는 특수 키워드는 다음과 같습니다.
    • intitle: 제목에 이 키워드 다음에 오는 텍스트가 있는 결과를 반환합니다.
    • inauthor: 이 키워드 뒤에 오는 텍스트가 작성자에 있는 결과를 반환합니다.
    • inpublisher: 이 키워드 다음에 오는 텍스트가 게시자에 있는 경우의 결과를 반환합니다.
    • subject:: 이 키워드 다음에 오는 텍스트가 볼륨의 카테고리 목록에 나열된 결과를 반환합니다.
    • isbn:: 이 키워드 다음에 오는 텍스트가 ISBN 숫자인 결과를 반환합니다.
    • lccn: 이 키워드 다음에 오는 텍스트가 미국 의회 도서관 제어 번호인 결과를 반환합니다.
    • oclc:: 이 키워드 뒤에 있는 텍스트가 온라인 컴퓨터 라이브러리 센터 번호인 결과를 반환합니다.

요청

다음은 다니엘 키스와 'Algernon의 꽃'을 검색하는 예입니다.

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

참고: 검색을 수행할 때 인증이 필요하지 않으므로 Authorization HTTP 헤더를 GET 요청과 함께 제공할 필요가 없습니다. 하지만 인증으로 호출하면 각 볼륨에는 구매 상태와 같은 사용자별 정보가 포함됩니다.

응답

요청이 성공하면 서버는 200 OK HTTP 상태 코드와 볼륨 결과로 응답합니다.

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
}

선택적 쿼리 매개변수

볼륨 검색을 수행할 때 표준 쿼리 매개변수 외에도 다음 쿼리 매개변수를 사용할 수 있습니다.

다운로드 형식

download 매개변수를 사용하여 epub 값으로 설정하여 반환된 결과를 사용 가능한 다운로드 형식이 epub인 볼륨으로 제한할 수 있습니다.

다음 예는 epub 다운로드가 가능한 도서를 검색합니다.

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

filter 매개변수를 다음 값 중 하나로 설정하여 반환된 결과를 추가로 제한할 수 있습니다.

  • partial - 텍스트 일부분을 미리 볼 수 있는 결과를 반환합니다.
  • full - 모든 텍스트를 볼 수 있는 결과만 반환합니다.
  • free-ebooks - 무료 Google eBook인 결과만 반환합니다.
  • paid-ebooks - 가격이 포함된 Google eBook 검색결과만 반환합니다.
  • ebooks - 유료 또는 무료 Google eBook 검색결과만 반환합니다. eBook이 아닌 예로는 제한된 미리보기로 제공되고 판매용으로 제공되지 않는 게시자 콘텐츠 또는 잡지가 있습니다.

다음 예에서는 무료 eBook으로 사용 가능한 결과로 검색결과를 제한합니다.

GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey
페이지로 나누기

요청의 매개변수에 두 값을 지정하여 볼륨 목록을 페이지로 나눌 수 있습니다.

  • startIndex - 컬렉션에서 시작할 위치입니다. 첫 번째 항목의 색인은 0입니다.
  • maxResults - 반환할 최대 결과 수입니다. 기본값은 10이고 최대 허용 값은 40입니다.

printType 매개변수를 사용하여 반환된 결과를 다음 값 중 하나로 설정하여 특정 인쇄 또는 게시 유형으로 제한할 수 있습니다.

  • all - 인쇄 유형에 따라 제한되지 않습니다 (기본값).
  • books - 도서인 결과만 반환합니다.
  • magazines - 잡지 검색결과를 반환합니다.

다음 예는 검색결과를 잡지로 제한합니다.

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

projection 매개변수를 다음 값 중 하나와 함께 사용하여 사전 정의된 볼륨 필드 집합을 지정할 수 있습니다.

  • full - 모든 볼륨 필드를 반환합니다.
  • lite - 특정 필드만 반환합니다. 포함된 필드를 확인하려면 볼륨 참조에서 이중 별표로 표시된 필드 설명을 참조하세요.

다음 예시는 볼륨 정보가 제한된 검색결과를 반환합니다.

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

기본적으로 볼륨 검색 요청은 maxResults 결과를 반환합니다. 여기서 maxResults는 페이지로 나누기에 사용되는 매개변수이며 검색어와의 관련성을 기준으로 정렬됩니다.

orderBy 매개변수를 다음 값 중 하나로 설정하여 순서를 변경할 수 있습니다.

  • relevance - 검색어와의 관련성 순으로 결과를 반환합니다 (기본값).
  • newest - 최근 게시된 항목 순으로 결과를 반환합니다.

다음 예는 게시 날짜순으로 결과를 나열합니다(최신 데이터부터 가장 오래된 날짜까지).

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

특정 볼륨 검색

볼륨 리소스 URI에 HTTP GET 요청을 전송하여 특정 볼륨의 정보를 검색할 수 있습니다.

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

volumeId 경로 매개변수를 검색할 볼륨의 ID로 바꿉니다. 볼륨 ID에 대한 자세한 내용은 Google 도서 ID 섹션을 참조하세요.

요청

다음은 단일 볼륨을 가져오는 GET 요청의 예입니다.

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

참고: 볼륨 정보를 가져올 때 인증이 필요하지 않으므로 Authorization HTTP 헤더를 GET 요청과 함께 제공할 필요가 없습니다. 그러나 인증으로 호출하면 볼륨에는 구매 상태와 같은 사용자별 정보가 포함됩니다.

응답

요청에 성공하면 서버가 200 OK HTTP 상태 코드와 요청된 볼륨 리소스로 응답합니다.

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"
 }
}
액세스 정보

accessInfo 섹션은 eBook에 사용할 수 있는 기능을 결정하는 데 특히 관심이 있습니다. epub은 맞춤 텍스트 형식 eBook이며 epub 섹션에는 이러한 유형의 eBook을 사용할 수 있는지를 나타내는 isAvailable 속성이 있습니다. 도서 샘플이 있거나 사용자가 도서를 구매했거나 사용자 위치의 공개 도메인이므로 도서를 읽을 수 있는 경우 다운로드 링크가 표시됩니다. Google 도서의 pdf은 eBook의 스캔 페이지 버전을 나타내며, 제공 여부 및 다운로드 링크와 같은 세부정보가 포함되어 있습니다. eReader 및 스마트폰에는 epub 파일을 사용하는 것이 좋습니다. 이러한 기기에서는 스캔된 페이지가 읽기 어려울 수 있습니다. accessInfo 섹션이 없으면 볼륨을 Google eBook으로 사용할 수 없습니다.

선택적 쿼리 매개변수

특정 볼륨을 가져올 때 표준 쿼리 매개변수 외에도 다음 쿼리 매개변수를 사용할 수 있습니다.

투영

projection 매개변수를 다음 값 중 하나와 함께 사용하여 사전 정의된 볼륨 필드 집합을 지정할 수 있습니다.

  • full - 모든 볼륨 필드를 반환합니다.
  • lite - 특정 필드만 반환합니다. 포함된 필드를 확인하려면 볼륨 참조에서 이중 별표로 표시된 필드 설명을 참조하세요.

다음 예에서는 단일 볼륨에 대해 제한된 볼륨 정보를 반환합니다.

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

서가에서 작업하기

사용자의 공개 서가 목록을 가져오는 중

다음 형식으로 URI에 HTTP GET 요청을 전송하여 사용자의 공개 서가 목록을 검색할 수 있습니다.

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

userId 경로 매개변수를 검색하려는 서가의 사용자 ID로 바꿉니다. 사용자 ID에 대한 자세한 내용은 Google 도서 ID 섹션을 참조하세요.

요청

예를 들면 다음과 같습니다.

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

공개 서가에 관한 정보를 가져오기 위해 사용자를 인증할 필요가 없으므로 GET 요청과 함께 Authorization HTTP 헤더를 제공할 필요가 없습니다.

응답

요청에 성공하면 서버가 200 OK HTTP 상태 코드와 서가 목록으로 응답합니다.

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

선택적 쿼리 매개변수

사용자의 공개 서가 목록을 가져올 때 표준 쿼리 매개변수를 사용할 수 있습니다.

특정 공개 서가 검색

다음 형식으로 URI에 HTTP GET 요청을 전송하여 특정 공개 서가를 검색할 수 있습니다.

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

userIdshlf 경로 매개변수를 검색할 사용자와 서가를 지정하는 ID로 바꿉니다. 자세한 내용은 Google 도서 ID 섹션을 참고하세요.

요청

예를 들면 다음과 같습니다.

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

공개 서가에 관한 정보를 가져오기 위해 사용자를 인증할 필요가 없으므로 GET 요청과 함께 Authorization HTTP 헤더를 제공할 필요가 없습니다.

응답

요청에 성공하면 서버가 200 OK HTTP 상태 코드와 compose 리소스로 응답합니다.

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

선택적 쿼리 매개변수

특정 공개 서가를 가져올 때 표준 쿼리 매개변수를 사용할 수 있습니다.

공개 서가에서 볼륨 목록 가져오기

HTTP GET 요청을 다음 형식으로 포함하는 URI를 전송하여 사용자의 공개 서가에 있는 볼륨 목록을 가져올 수 있습니다.

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

요청

예를 들면 다음과 같습니다.

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

userIdshlf 경로 매개변수를 검색할 사용자와 서가를 지정하는 ID로 바꿉니다. 자세한 내용은 Google 도서 ID 섹션을 참고하세요.

공개 서가에 관한 정보를 가져오기 위해 사용자를 인증할 필요가 없으므로 GET 요청과 함께 Authorization HTTP 헤더를 제공할 필요가 없습니다.

응답

요청에 성공하면 서버가 200 OK HTTP 상태 코드와 사용자의 서가 목록으로 응답합니다.

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
}

선택적 쿼리 매개변수

공개 서가의 볼륨 목록을 검색할 때는 표준 쿼리 매개변수 외에도 다음 쿼리 매개변수를 사용할 수 있습니다.

페이지로 나누기

요청의 매개변수에 두 값을 지정하여 볼륨 목록을 페이지로 나눌 수 있습니다.

  • startIndex - 컬렉션에서 시작할 위치입니다. 첫 번째 항목의 색인은 0입니다.
  • maxResults - 반환할 최대 결과 수입니다. 기본값은 10이고 최대 허용 값은 40입니다.

'내 라이브러리'에서 서가 작업하기

모든 '내 라이브러리' 요청은 인증된 사용자의 데이터에 적용됩니다.

내 서가 목록 가져오기

다음 형식으로 URI에 HTTP GET 요청을 전송하여 인증된 모든 서가의 목록을 검색할 수 있습니다.

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

요청

예를 들면 다음과 같습니다.

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

참고: '내 라이브러리' 서가 목록을 검색하려면 사용자는 인증을 받아야 합니다. 따라서 Authorization HTTP 헤더에 GET 요청을 제공해야 합니다.

응답

요청에 성공하면 서버가 200 OK HTTP 상태 코드와 현재 인증된 사용자의 모든 서가 목록으로 응답합니다.

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

선택적 쿼리 매개변수

인증된 사용자의 서가 목록을 가져올 때 표준 쿼리 매개변수를 사용할 수 있습니다.

서가의 볼륨 목록 가져오기

다음 형식으로 URI에 HTTP GET 요청을 전송하여 인증된 사용자의 서가에 있는 볼륨 목록을 검색할 수 있습니다.

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

Shelf 경로 매개변수를 서가의 ID로 바꿉니다. 서가 ID에 대한 자세한 내용은 Google 도서 ID 섹션을 참조하세요.

요청

예를 들면 다음과 같습니다.

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

참고: 사용자는 '내 라이브러리' 볼륨 목록을 가져오려면 인증을 받아야 합니다. 따라서 Authorization HTTP 헤더와 GET 요청을 제공해야 합니다.

응답

요청에 성공하면 서버가 200 OK HTTP 상태 코드와 서가 볼륨 목록으로 응답합니다.

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
}

선택적 쿼리 매개변수

표준 쿼리 매개변수 외에도 인증된 사용자의 서가 중 하나에서 볼륨 목록을 검색할 때 다음 쿼리 매개변수를 사용할 수 있습니다.

페이지로 나누기

요청의 매개변수에 두 값을 지정하여 볼륨 목록을 페이지로 나눌 수 있습니다.

  • startIndex - 컬렉션에서 시작할 위치입니다. 첫 번째 항목의 색인은 0입니다.
  • maxResults - 반환할 최대 결과 수입니다. 기본값은 10입니다.

서가에 볼륨 추가

인증된 사용자의 서가에 볼륨을 추가하려면 URI에 HTTP POST 요청을 다음 형식으로 전송합니다.

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

Shelf 경로 매개변수를 서가의 ID로 바꿉니다. 서가 ID에 대한 자세한 내용은 Google 도서 ID 섹션을 참조하세요.

요청에는 하나의 필수 쿼리 매개변수가 있습니다.

  • volumeId - 볼륨의 ID 볼륨 ID에 대한 자세한 내용은 Google 도서 ID 섹션을 참고하세요.

요청

다음은 "즐겨찾기에 'Algernon'을 위한 꽃'을 추가하는 예입니다.

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

참고: 사용자가 서가를 수정하려면 인증이 완료되어야 하므로 Authorization HTTP 헤더에 POST 요청을 제공해야 합니다. 그러나 이 POST에는 데이터가 필요하지 않습니다.

응답

요청에 성공하면 서버가 204 No Content HTTP 상태 코드로 응답합니다.

선택적 쿼리 매개변수

인증된 사용자의 서가 중 하나에 볼륨을 추가할 때 표준 쿼리 매개변수를 사용할 수 있습니다.

서가에서 볼륨 삭제

인증된 사용자의 서가에서 볼륨을 삭제하려면 다음 형식으로 HTTP POST를 URI에 전송합니다.

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

Shelf 경로 매개변수를 서가의 ID로 바꿉니다. 서가 ID에 대한 자세한 내용은 Google 도서 ID 섹션을 참조하세요.

요청에는 하나의 필수 쿼리 매개변수가 있습니다.

  • volumeId - 볼륨의 ID 볼륨 ID에 관한 자세한 내용은 Google 도서 ID 섹션을 참고하세요.

요청

다음은 "즐겨찾기"에서 'Algernon'용 꽃을 삭제하는 예입니다.

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

참고: 사용자가 서가를 수정하려면 인증이 완료되어야 하므로 Authorization HTTP 헤더에 POST 요청을 제공해야 합니다. 그러나 이 POST에는 데이터가 필요하지 않습니다.

응답

요청에 성공하면 서버가 204 No Content 상태 코드로 응답합니다.

선택적 쿼리 매개변수

인증된 사용자의 서가 중 하나에서 볼륨을 삭제할 때는 표준 쿼리 매개변수를 사용할 수 있습니다.

서가에서 모든 볼륨 삭제

인증된 사용자의 서가에서 모든 볼륨을 삭제하려면 다음 형식으로 URI에 HTTP POST를 전송합니다.

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

Shelf 경로 매개변수를 서가의 ID로 바꿉니다. 서가 ID에 대한 자세한 내용은 Google 도서 ID 섹션을 참조하세요.

요청

다음은 '즐겨찾기' 북마크를 삭제하는 예입니다.

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
  

참고: 사용자가 서가를 수정하려면 인증이 완료되어야 하므로 Authorization HTTP 헤더에 POST 요청을 제공해야 합니다. 그러나 이 POST에는 데이터가 필요하지 않습니다.

응답

요청이 성공하면 서버가 204 No Content 상태 코드로 응답합니다.

선택적 쿼리 매개변수

인증된 사용자의 서가 중 하나에서 모든 볼륨을 삭제할 때 표준 쿼리 매개변수를 사용할 수 있습니다.

쿼리 매개변수 참조

이 섹션에는 Books API에서 사용할 수 있는 쿼리 매개변수가 요약되어 있습니다.모든 매개변수 값은 URL로 인코딩되어야 합니다.

표준 쿼리 매개변수

모든 Books API 작업에 적용되는 쿼리 매개변수는 시스템 매개변수에 설명되어 있습니다.

API별 쿼리 매개변수

다음 표에는 Books API의 특정 작업에만 적용되는 요청 매개변수가 요약되어 있습니다.

매개변수 의미 메모 적용 대상
download 다운로드 가용성에 따라 볼륨 제한
  • 현재 유일하게 지원되는 값은 epub입니다.
  • 다운로드를 이용하려면 구매가 필요할 수 있습니다.
filter 볼륨 유형 및 사용 가능 여부로 검색결과를 필터링합니다.
  • 지원되는 필터는 다음과 같습니다.
    • filter=partial - 텍스트의 일부분을 미리 볼 수 있는 볼륨으로 결과를 제한합니다.
    • filter=full - 모든 텍스트가 표시되는 볼륨으로 결과를 제한합니다.
    • filter=free-ebooks - 무료 Google eBook으로 검색결과를 제한합니다.
    • filter=paid-ebooks - 구매 가격이 표시된 Google eBook으로 검색결과를 제한합니다.
    • filter=ebooks - 검색결과를 Google eBook(유료 또는 무료)으로 제한합니다.eBook이 아닌 예로는 제한된 미리보기로 제공되고 판매용으로 제공되지 않는 출판사 콘텐츠 또는 잡지가 있습니다.

 

langRestrict 지정된 언어로 태그가 지정된 볼륨으로 반환되는 볼륨을 제한합니다.
  • langRestrict를 2자리 ISO-639-1 코드(예: 'ko' 또는 'fr')로 지정하여 검색결과를 특정 언어의 검색결과로 제한합니다.
maxResults 이 요청으로 반환할 최대 요소 수입니다.
  • 컬렉션의 모든 항목에 대한 요청의 경우 요청의 매개변수에 startIndexmaxResults를 지정하여 결과를 페이지로 나눌 수 있습니다.
  • 기본값: maxResults=10
  • 최대 허용 값: maxResults=40.
orderBy

볼륨 검색결과의 순서입니다.

  • 기본적으로 검색 요청은 maxResults 결과를 반환합니다. 여기서 maxResults는 페이지로 나누기에 사용되는 매개변수이며 가장 관련성 높은 순으로 정렬됩니다.
  • orderBy 매개변수를 다음 값 중 하나로 설정하여 순서를 변경할 수 있습니다.
    • orderBy=relevance - 가장 관련성이 높은 순서대로 검색결과를 반환합니다 (기본값).
    • orderBy=newest - 최근 게시된 날짜부터 가장 오래된 날짜 순으로 검색결과를 반환합니다.
printType 도서 또는 잡지로 제한됩니다.
  • 지원되는 값은 다음과 같습니다.
    • printType=all - 모든 볼륨 콘텐츠 유형을 반환합니다 (제한 없음). 이는 기본값입니다.
    • printType=books - 도서만 반환합니다.
    • printType=magazines - 잡지만 반환합니다.
projection 필드 하위 집합으로 반환되는 볼륨 정보를 제한합니다.
  • 지원되는 프로젝션은 다음과 같습니다.
    • projection=full - 모든 볼륨 메타데이터를 포함합니다 (기본값).
    • projection=lite - 볼륨 및 액세스 메타데이터의 제목만 포함합니다.
q 전체 텍스트 쿼리 문자열입니다.
  • 쿼리를 만들 때 검색어를 q=term1+term2_term3 형식으로 '+'로 구분합니다. (또는 공백으로 값을 구분할 수 있지만, 모든 쿼리 매개변수 값과 마찬가지로 공백도 URL로 인코딩되어야 합니다.) API는 모든 검색어와 일치하는 모든 항목을 반환합니다 (예: 용어 사이에 AND 사용). Google의 웹 검색과 마찬가지로 API는 하위 문자열이 아닌 전체 단어 (및 같은 스템을 가진 관련 단어)를 검색합니다.
  • 정확한 구문을 검색하려면 문구를 따옴표로 묶습니다. q="exact phrase".
  • 지정된 용어와 일치하는 항목을 제외하려면 q=-term 양식을 사용합니다.
  • 검색어는 대소문자를 구분하지 않습니다.
  • 예: 정확한 문구("Elizabeth Bennet")와 단어("Darcy")를 포함하지만 "Austen"(이)라는 단어를 포함하지 않는 모든 항목을 검색하려면 다음 쿼리 매개변수 값을 사용합니다.
    q="Elizabeth+Bennet"+Darcy-Austen
  • 다음과 같이 특정 입력란에 검색할 수 있는 특수 키워드 (대소문자 구분)를 검색어에서 지정할 수 있습니다.
    • intitle: 이 키워드 뒤에 오는 텍스트가 제목에 있는 결과를 반환합니다.
    • inauthor: 이 키워드 다음에 오는 텍스트가 저자에 있는 결과를 반환합니다.
    • inpublisher: 이 키워드 뒤에 오는 텍스트가 게시자에 있는 결과를 반환합니다.
    • subject: 이 키워드 다음에 오는 텍스트가 볼륨의 카테고리 목록에 나열된 결과를 반환합니다.
    • isbn: 이 키워드 뒤에 오는 텍스트가 ISBN 번호인 결과를 반환합니다.
    • lccn: 이 키워드 다음에 오는 텍스트가 미국 의회도서관 제어 번호인 결과를 반환합니다.
    • oclc: 이 키워드 뒤에 있는 텍스트가 온라인 컴퓨터 라이브러리 센터 번호인 결과를 반환합니다.
startIndex 컬렉션에서 결과 목록을 시작할 위치입니다.
  • 컬렉션의 모든 항목에 대한 요청의 경우 요청의 매개변수에 startIndexmaxResults를 지정하여 결과를 페이지로 나눌 수 있습니다.
  • 첫 번째 항목의 색인은 0입니다.
volumeId 요청과 연결된 볼륨을 식별합니다.
  • 서가에서 추가하거나 삭제할 볼륨을 지정합니다.