Esta página foi traduzida pela API Cloud Translation.

Como usar a API

Conteúdo

Introdução
Como trabalhar com volumes
1. Como realizar uma pesquisa
2. Como recuperar um volume específico
Como trabalhar com estantes de livros
Como trabalhar com as estantes em "Minha biblioteca"
Referência do parâmetro de consulta
1. Parâmetros de consulta padrão
2. Parâmetros de consulta específicos da API

Introdução

Este documento é destinado a desenvolvedores que querem criar apps que podem interagir com a API Books. A missão do Google Livros é digitalizar o conteúdo de livros do mundo e torná-lo mais fácil de ser encontrado na Web. A API Books é uma maneira de pesquisar e acessar esse conteúdo, além de criar e visualizar personalizações relacionadas a ele.

Se você não conhece os conceitos do Google Livros, leia Como começar antes de começar a codificar.

Como autorizar solicitações e identificar seu aplicativo

Cada solicitação que seu aplicativo envia à API Books precisa identificar o aplicativo para o Google. Há duas maneiras de identificar o aplicativo: usando o token OAuth 2.0, que também autoriza a solicitação, e/ou usando a chave de API do aplicativo. Veja como determinar a melhor opção para você:

Se a solicitação exige autorização, como uma solicitação de dados particulares de um indivíduo, o aplicativo precisa fornecer um token OAuth 2.0 com a solicitação. Ele também pode fornecer a chave de API, mas isso não é obrigatório.
Se a solicitação não exige autorização, como uma solicitação de dados públicos, o aplicativo precisa fornecer a chave de API, um token OAuth 2.0 ou ambos, dependendo do que for mais conveniente para você.

Sobre protocolos de autorização

O aplicativo deve obrigatoriamente usar o OAuth 2.0 para autorizar solicitações. Não há outros protocolos de autorização compatíveis. Se o aplicativo usa o Fazer login com o Google, alguns aspectos da autorização são administrados para você.

Autorizar solicitações com OAuth 2.0

As solicitações para a API Books relacionadas a dados de usuários não públicos precisam ser autorizadas por um usuário autenticado.

Os detalhes do processo de autorização ou “fluxo” para o OAuth 2.0 variam um pouco, dependendo do tipo de aplicativo que você está criando. O processo geral a seguir se aplica a todos os tipos de aplicativo:

Ao criar seu aplicativo, registre-o usando o Console de APIs do Google. Em seguida, o Google fornece informações que serão usadas mais tarde, como um ID e uma chave secreta do cliente.
Ative a API Books no Console de APIs do Google. Se ela não estiver no Console de APIs, pule essa etapa.
Quando seu aplicativo precisar de acesso aos dados do usuário, ele solicitará ao Google um determinado escopo do acesso.
O Google exibe uma tela de consentimento ao usuário, pedindo para que o aplicativo seja autorizado a solicitar alguns dos dados dele.
Se o usuário aprovar, o Google fornecerá ao aplicativo um token de acesso de curta duração.
O aplicativo solicita dados de usuário, anexando o token de acesso à solicitação.
Se o Google determinar que a solicitação e o token são válidos, ele retornará os dados solicitados.

Alguns fluxos incluem etapas adicionais, como atualizar tokens para adquirir novos tokens de acesso. Para mais informações sobre fluxos de vários tipos de aplicativos, acesse a documentação OAuth 2.0 do Google.

Confira as informações de escopo do OAuth 2.0 para a API Books:

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

Para solicitar acesso usando o OAuth 2.0, seu aplicativo precisa de informações do escopo, bem como informações fornecidas pelo Google durante o registro do aplicativo, como o ID e a chave secreta do cliente.

Dica: as bibliotecas cliente de APIs do Google cuidam de parte do processo de autorização para você. Elas estão disponíveis para uma grande variedade de linguagens de programação. Verifique a página com bibliotecas e amostras para mais detalhes.

Como receber e usar uma chave de API

As solicitações de dados públicos à API Books precisam incluir um identificador, que pode ser uma chave de API ou um token de acesso.

Para adquirir uma chave de API:

Abra a página Credenciais no Console da API.
Essa API aceita dois tipos de credenciais. Crie as credenciais que sejam adequadas ao seu projeto:
- OAuth 2.0: sempre que seu aplicativo solicitar dados particulares do usuário, ele deverá enviar um token OAuth 2.0 junto da solicitação. Primeiro, seu aplicativo envia um ID de cliente e, possivelmente, uma chave secreta do cliente para obter um token. É possível gerar credenciais OAuth 2.0 para aplicativos da Web, contas de serviço ou aplicativos instalados.
  
  Para mais informações, acesse a documentação do OAuth 2.0.
- Chaves de API: uma solicitação que não fornece um token OAuth 2.0 precisa enviar uma chave de API. A chave identifica seu projeto e fornece acesso à API, à cota e aos relatórios.
  
  A API é compatível com diversos tipos de restrições em chaves de API. Se a chave de API de que você precisa ainda não existe, crie uma no Console clicando em Criar credenciais > Chave de API. É possível restringir a chave antes de usá-la na produção clicando em Restringir chave e selecionando uma das Restrições.

Para proteger as chaves de API, siga as práticas recomendadas para usar as chaves de API com segurança.

Depois que você tiver uma chave de API, seu aplicativo poderá anexar o parâmetro de consulta key=yourAPIKey a todos os URLs de solicitação.

É seguro incorporar a chave de API a URLs. Não é necessário codificá-la.

IDs do Google Livros

É necessário especificar campos de ID com determinadas chamadas de método de API. Há três tipos de documentos de identificação usados no Google Livros:

IDs de volume: strings exclusivas atribuídas a cada volume que o Google Livros conhece. Um exemplo de ID de volume é _LettPDhwR0C. É possível usar a API para receber o ID do volume fazendo uma solicitação que retorna um recurso de volume. Encontre o ID do volume no campo id.
IDs de biblioteca: valores numéricos atribuídos a uma biblioteca na biblioteca de um usuário. O Google fornece algumas prateleiras predefinidas para todos os usuários com os seguintes IDs:
- Favoritos: 0
- Comprado: 1
- Para ler: 2
- Lendo agora: 3
- Lido: 4
- Revisado: 5
- Acesso recente: 6
- Meus e-books: 7
- Livros para você: 8 Se não tivermos recomendações para o usuário, essa seção não vai existir.
As prateleiras personalizadas têm IDs maiores que 1.000. Um ID de estante é exclusivo para um determinado usuário. Ou seja, dois usuários podem ter uma estante com o mesmo ID que se refere a estantes diferentes. É possível usar a API para receber o ID da biblioteca fazendo uma solicitação que retorna um recurso da biblioteca. O ID está no campo id.
IDs de usuário: valores numéricos exclusivos atribuídos a cada usuário. Esses valores não são necessariamente o mesmo valor de ID usado em outros serviços do Google. Atualmente, a única maneira de recuperar o ID do usuário é extraindo-o do selfLink em um recurso da Bookshelf recuperado com uma solicitação autenticada. Os usuários também podem conferir o próprio ID no site do Livros. Um usuário não pode receber o ID de outro usuário pela API ou pelo site do Livros. O outro usuário precisa compartilhar essas informações explicitamente, por e-mail, por exemplo.

IDs no site do Google Livros

Os IDs usados com a API Books são os mesmos usados no site do Google Books.

ID do volume

Ao acessar um volume específico no site, você pode encontrar o ID do volume no parâmetro de URL id. Exemplo:
```
https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard
```
ID da biblioteca

Ao visualizar uma estante específica no site, você pode encontrar o ID da estante no parâmetro de URL as_coll. Exemplo:
```
https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary
```
ID do usuário

Ao acessar sua biblioteca no site, você pode encontrar o ID do usuário no parâmetro de URL uid. Exemplo:
```
https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list
```

Como definir a localização do usuário

O Google Livros respeita os direitos autorais, contratos e outras restrições legais associadas ao local do usuário final. Por isso, alguns usuários talvez não consigam acessar o conteúdo de livros de determinados países. Por exemplo, alguns livros têm visualização apenas nos Estados Unidos. Esses links de visualização são omitidos para usuários em outros países. Portanto, os resultados da API são restritos com base no endereço IP do seu servidor ou aplicativo cliente.

Como trabalhar com volumes

Como realizar uma pesquisa

Para fazer uma pesquisa de volumes, envie uma solicitação GET HTTP para o seguinte URI:

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

Essa solicitação tem um único parâmetro obrigatório:

q: pesquisa volumes que contêm essa string de texto. Há palavras-chave especiais que podem ser especificadas nos termos de pesquisa para pesquisar em campos específicos, como:
- intitle: Retorna resultados em que o texto após essa palavra-chave é encontrado no título.
- inauthor: Retorna resultados em que o texto após essa palavra-chave é encontrado no autor.
- inpublisher: Retorna resultados em que o texto após essa palavra-chave é encontrado no editor.
- subject: Retorna resultados em que o texto após essa palavra-chave está listado na lista de categorias do volume.
- isbn: Retorna resultados em que o texto após essa palavra-chave é o número ISBN.
- lccn: Retorna resultados em que o texto após essa palavra-chave é o número de controle da Biblioteca do Congresso.
- oclc: Retorna resultados em que o texto após essa palavra-chave é o número da Online Computer Library Center.

Solicitação

Confira um exemplo de pesquisa por "Flowers for Algernon", de Daniel Keyes:

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

Observação: a realização de uma pesquisa não exige autenticação. Portanto, não é necessário fornecer o cabeçalho HTTP Authorization com a solicitação GET. No entanto, se a chamada for feita com autenticação, cada Volume vai incluir informações específicas do usuário, como o status de compra.

Resposta

Se a solicitação for bem-sucedida, o servidor vai responder com um código de status HTTP 200 OK e os resultados do 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
}

Parâmetros de consulta opcionais

Além dos parâmetros de consulta padrão, você pode usar os parâmetros de consulta a seguir ao realizar uma pesquisa de volumes.

Formato de download

Use o parâmetro download para restringir os resultados retornados a volumes que têm um formato de download disponível de epub definindo o como o valor epub.

O exemplo a seguir pesquisa livros com um download ePub disponível:

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

Filtragem

É possível usar o parâmetro filter para restringir ainda mais os resultados retornados definindo-o como um dos seguintes valores:

partial: retorna resultados em que pelo menos partes do texto podem ser visualizados.
full: retorna apenas resultados em que todo o texto é visível.
free-ebooks: retorna apenas resultados que são Google eBooks sem custo financeiro.
paid-ebooks: retorna apenas resultados que são Google e-books com um preço.
ebooks: retorna apenas resultados que são Google eBooks, pagos ou sem custo financeiro. Exemplos de conteúdo que não são e-books são conteúdo de editores disponível em visualização limitada e não para venda, ou revistas.

O exemplo a seguir restringe os resultados da pesquisa a eBooks sem custo financeiro:

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

Paginação

É possível paginar a lista de volumes especificando dois valores nos parâmetros da solicitação:

startIndex: a posição na coleção em que começar. O índice do primeiro item é 0.
maxResults: o número máximo de resultados a serem retornados. O padrão é 10, e o valor máximo permitido é 40.

Tipo de impressão

É possível usar o parâmetro printType para restringir os resultados retornados a um tipo específico de impressão ou publicação, definindo-o como um dos seguintes valores:

all: não restringe por tipo de impressão (padrão).
books: retorna apenas resultados que são livros.
magazines: retorna resultados que são revistas.

O exemplo a seguir restringe os resultados da pesquisa a revistas:

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

Projeção

É possível usar o parâmetro projection com um dos seguintes valores para especificar um conjunto predefinido de campos de volume a serem retornados:

full: retorna todos os campos de volume.
lite: retorna apenas determinados campos. Consulte as descrições de campo marcadas com dois asteriscos na Referência do volume para saber quais campos estão incluídos.

O exemplo a seguir retorna resultados de pesquisa com informações de volume limitadas:

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

Classificação

Por padrão, uma solicitação de pesquisa de volumes retorna resultados maxResults, em que maxResults é o parâmetro usado na paginação (acima), ordenado por relevância aos termos de pesquisa.

É possível mudar a ordem definindo o parâmetro orderBy como um destes valores:

relevance: retorna resultados na ordem da relevância dos termos de pesquisa (padrão).
newest: retorna resultados em ordem da mais recente para a menos recente.

O exemplo a seguir lista os resultados por data de publicação, da mais recente para a mais antiga:

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

Como recuperar um volume específico

Para recuperar informações de um volume específico, envie uma solicitação GET HTTP para o URI do recurso de volume:

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

Substitua o parâmetro de caminho volumeId pelo ID do volume a ser recuperado. Consulte a seção IDs do Google Livros para mais informações sobre os IDs de volume.

Solicitação

Confira um exemplo de solicitação GET que recebe um único volume:

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

Observação: a recuperação de informações de volume não requer autenticação. Portanto, você não precisa fornecer o cabeçalho HTTP Authorization com a solicitação GET. No entanto, se a chamada for feita com autenticação, o Volume vai incluir informações específicas do usuário, como o status de compra.

Resposta

Se a solicitação for bem-sucedida, o servidor vai responder com o código de status HTTP 200 OK e o recurso de volume solicitado:

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

Informações de acesso

A seção accessInfo é de interesse especial para determinar quais recursos estão disponíveis para um e-book. Um epub é um e-book com formato de texto fluido. A seção epub terá uma propriedade isAvailable indicando se esse tipo de e-book está disponível. Ele terá um link de download se houver uma amostra do livro ou se o usuário puder ler o livro porque o comprou ou porque ele está em domínio público no local do usuário. Um pdf para o Google Livros indica uma versão de páginas digitalizadas do e-book com detalhes semelhantes, como se ele está disponível e um link de download. O Google recomenda arquivos epub para e-readers e smartphones, já que as páginas digitalizadas podem ser difíceis de ler nesses dispositivos. Se não houver uma seção accessInfo, o volume não estará disponível como um Google e-book.

Parâmetros de consulta opcionais

Além dos parâmetros de consulta padrão, você pode usar o parâmetro de consulta a seguir ao recuperar um volume específico.

Projeção

É possível usar o parâmetro projection com um dos seguintes valores para especificar um conjunto predefinido de campos de volume a serem retornados:

full: retorna todos os campos de volume.
lite: retorna apenas determinados campos. Consulte as descrições de campo marcadas com dois asteriscos na Referência do volume para saber quais campos estão incluídos.

O exemplo a seguir retorna informações limitadas de um único volume:

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

Como trabalhar com estantes

Como recuperar uma lista de bibliotecas públicas de um usuário

É possível recuperar uma lista de bibliotecas públicas de um usuário enviando uma solicitação HTTP GET para o URI com o seguinte formato:

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

Substitua o parâmetro de caminho userId pelo ID do usuário que tem as bibliotecas que você quer recuperar. Consulte a seção IDs do Google Livros para mais informações sobre IDs de usuários.

Solicitação

Exemplo:

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

Como um usuário não precisa ser autenticado para recuperar informações sobre bibliotecas públicas, não é necessário fornecer o cabeçalho HTTP Authorization com a solicitação GET.

Resposta

Se a solicitação for bem-sucedida, o servidor vai responder com o código de status HTTP 200 OK e a lista de estantes:

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

Parâmetros de consulta opcionais

É possível usar os parâmetros de consulta padrão ao extrair a lista de bibliotecas públicas de um usuário.

Como recuperar uma estante pública específica

É possível recuperar uma estante pública específica enviando uma solicitação GET HTTP para o URI com o seguinte formato:

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

Substitua os parâmetros de caminho userId e shelf pelos IDs que especificam o usuário e a biblioteca que você quer recuperar. Consulte a seção IDs do Google Livros para mais informações.

Solicitação

Exemplo:

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

Como um usuário não precisa ser autenticado para recuperar informações sobre bibliotecas públicas, não é necessário fornecer o cabeçalho HTTP Authorization com a solicitação GET.

Resposta

Se a solicitação for bem-sucedida, o servidor vai responder com o código de status HTTP 200 OK e o recurso de biblioteca:

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

Parâmetros de consulta opcionais

É possível usar os parâmetros de consulta padrão ao extrair uma estante pública específica.

Recuperando uma lista de volumes em uma estante pública

É possível extrair uma lista de volumes na biblioteca pública de um usuário enviando uma solicitação HTTP GET para um URI com o seguinte formato:

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

Solicitação

Exemplo:

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

Substitua os parâmetros de caminho userId e shelf pelos IDs que especificam o usuário e a biblioteca que você quer recuperar. Consulte a seção IDs do Google Livros para mais informações.

Como um usuário não precisa ser autenticado para recuperar informações sobre bibliotecas públicas, não é necessário fornecer o cabeçalho HTTP Authorization com a solicitação GET.

Resposta

Se a solicitação for bem-sucedida, o servidor vai responder com um código de status HTTP 200 OK e a lista de bibliotecas do usuário:

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
}

Parâmetros de consulta opcionais

Além dos parâmetros de consulta padrão, você pode usar o parâmetro de consulta a seguir ao recuperar uma lista de volumes em uma estante pública.

Paginação

É possível paginar a lista de volumes especificando dois valores nos parâmetros da solicitação:

startIndex: a posição na coleção em que começar. O índice do primeiro item é 0.
maxResults: o número máximo de resultados a serem retornados. O padrão é 10, e o valor máximo permitido é 40.

Como usar as estantes em "Minha biblioteca"

Todas as solicitações "Minha biblioteca" se aplicam aos dados do usuário autenticado.

Como extrair uma lista das minhas estantes

É possível recuperar uma lista de todas as bibliotecas do usuário autenticado enviando uma solicitação HTTP GET para o URI com o seguinte formato:

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

Solicitação

Exemplo:

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

Observação: o usuário precisa ser autenticado para recuperar uma lista de estantes de "Minha biblioteca". Portanto, é necessário fornecer o cabeçalho HTTP Authorization com a solicitação GET.

Resposta

Se a solicitação for bem-sucedida, o servidor vai responder com o código de status HTTP 200 OK e a lista de todas as bibliotecas do usuário autenticado atual:

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

Parâmetros de consulta opcionais

É possível usar os parâmetros de consulta padrão ao extrair a lista das bibliotecas do usuário autenticado.

Recuperando uma lista de volumes na minha estante

É possível recuperar uma lista dos volumes na estante do usuário autenticado enviando uma solicitação HTTP GET para o URI com o seguinte formato:

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

Substitua o parâmetro de caminho shelf pelo ID da estante. Consulte a seção IDs do Google Livros para mais informações sobre os IDs de biblioteca.

Solicitação

Exemplo:

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

Observação: o usuário precisa ser autenticado para recuperar uma lista de volumes da "Minha biblioteca". Portanto, é necessário fornecer o cabeçalho HTTP Authorization com a solicitação GET.

Resposta

Se a solicitação for bem-sucedida, o servidor vai responder com o código de status HTTP 200 OK e a lista de volumes da biblioteca:

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
}

Parâmetros de consulta opcionais

Além dos parâmetros de consulta padrão, você pode usar o parâmetro de consulta a seguir ao recuperar uma lista de volumes em uma das estantes do usuário autenticado.

Paginação

É possível paginar a lista de volumes especificando dois valores nos parâmetros da solicitação:

startIndex: a posição na coleção em que começar. O índice do primeiro item é 0.
maxResults: o número máximo de resultados a serem retornados. O padrão é 10.

Adicionar um volume à minha estante

Para adicionar um volume à biblioteca do usuário autenticado, envie uma solicitação POST HTTP para o URI com o seguinte formato:

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

Substitua o parâmetro de caminho shelf pelo ID da estante. Consulte a seção IDs do Google Livros para mais informações sobre os IDs de biblioteca.

A solicitação tem um único parâmetro de consulta obrigatório:

volumeId: o ID do volume. Consulte a seção IDs do Google Livros para mais informações sobre IDs de volume.

Solicitação

Confira um exemplo de como adicionar "Flowers for Algernon" à estante "Favoritos":

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

Observação: o usuário precisa ser autenticado para fazer modificações em uma biblioteca. Portanto, forneça o cabeçalho HTTP Authorization com a solicitação POST. No entanto, nenhum dado é necessário com esse POST.

Resposta

Se a solicitação for bem-sucedida, o servidor vai responder com o código de status HTTP 204 No Content.

Parâmetros de consulta opcionais

É possível usar os parâmetros de consulta padrão ao adicionar um volume a uma das bibliotecas do usuário autenticado.

Como remover um volume da minha estante

Para remover um volume da estante do usuário autenticado, envie um POST HTTP para o URI com o seguinte formato:

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

Substitua o parâmetro de caminho shelf pelo ID da estante. Consulte a seção IDs do Google Livros para mais informações sobre os IDs de biblioteca.

A solicitação tem um único parâmetro de consulta obrigatório:

volumeId: o ID do volume. Consulte a seção IDs do Google Livros para mais informações sobre IDs de volume.

Solicitação

Confira um exemplo de como remover "Flowers for Algernon" da seção "Favoritos":

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

Resposta

Se a solicitação for bem-sucedida, o servidor vai responder com um código de status 204 No Content.

Parâmetros de consulta opcionais

É possível usar os parâmetros de consulta padrão ao remover um volume de uma das estantes do usuário autenticado.

Limpar todos os volumes da minha estante

Para remover todos os volumes da estante do usuário autenticado, envie um HTTP POST para o URI com o seguinte formato:

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

Substitua o parâmetro de caminho shelf pelo ID da estante. Consulte a seção IDs do Google Livros para mais informações sobre os IDs de biblioteca.

Solicitação

Confira um exemplo para limpar a estante "Favoritos":

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

Resposta

Se a solicitação for bem-sucedida, o servidor vai responder com um código de status 204 No Content.

Parâmetros de consulta opcionais

É possível usar os parâmetros de consulta padrão ao limpar todos os volumes de uma das estantes do usuário autenticado.

Referência de parâmetros de consulta

Os parâmetros de consulta que você pode usar com a API Books estão resumidos nesta seção. Todos os valores de parâmetro precisam ser codificados para uso em URLs.

Parâmetros de consulta padrão

Os parâmetros de consulta que se aplicam a todas as operações da API Books estão documentados em Parâmetros do sistema.

Parâmetros de consulta específicos da API

Os parâmetros de solicitação que se aplicam apenas a operações específicas na API Books estão resumidos na tabela a seguir.

Parâmetro	Significado	Observações	Aplicabilidade
`download`	Restringir a volumes pela disponibilidade de download.	No momento, o único valor aceito é `epub`. Pode ser necessário fazer uma compra para ter acesso ao download.	Como realizar uma pesquisa
`filter`	Filtre os resultados da pesquisa por tipo de volume e disponibilidade.	Os filtros compatíveis são: `filter=partial`: restringe os resultados a volumes em que pelo menos parte do texto pode ser visualizado. `filter=full`: restringe os resultados a volumes em que todo o texto é visível. `filter=free-ebooks`: restringe os resultados a Google e-books sem custo financeiro. `filter=paid-ebooks`: restringe os resultados a Google eBooks com um preço de compra. `filter=ebooks`: restrinja os resultados a e-books do Google, pagos ou gratuitos.Exemplos de não e-books são conteúdo do editor disponível em visualização limitada e não para venda, ou revistas.	Como realizar uma pesquisa
`langRestrict`	Restringe os volumes retornados aos que estão marcados com o idioma especificado.	Restringir os resultados da pesquisa a um determinado idioma especificando `langRestrict` para um código ISO-639-1 de duas letras, como "en" ou "fr".	Como realizar uma pesquisa
`maxResults`	O número máximo de elementos a serem retornados com essa solicitação.	Para qualquer solicitação de todos os itens de uma coleção, é possível paginar os resultados especificando `startIndex` e `maxResults` nos parâmetros da solicitação. Padrão: `maxResults=10` Valor máximo permitido: `maxResults=40.`	Como realizar uma pesquisa Listar as estantes de livros do usuário Listar os volumes da biblioteca do usuário Listar minhas estantes Listar os volumes da minha estante
`orderBy`	Ordem dos resultados da pesquisa de volume.	Por padrão, uma solicitação de pesquisa retorna resultados `maxResults`, em que `maxResults` é o parâmetro usado na paginação, ordenado pelo mais relevante primeiro. É possível mudar a ordem definindo o parâmetro `orderBy` como um destes valores: `orderBy=relevance`: retorna os resultados da pesquisa na ordem do mais relevante para o menos relevante (padrão). `orderBy=newest`: retorna os resultados da pesquisa na ordem da data de publicação mais recente para a mais antiga.	Como realizar uma pesquisa
`printType`	Restringir a livros ou revistas.	Os valores aceitos são: `printType=all`: retorna todos os tipos de conteúdo de volume (sem restrição). Esse é o padrão. `printType=books`: retorna apenas livros. `printType=magazines`: retorna apenas revistas.	Como realizar uma pesquisa
`projection`	Restringir as informações de volume retornadas a um subconjunto de campos.	As projeções compatíveis são: `projection=full`: inclui todos os metadados do volume (padrão). `projection=lite`: inclui apenas um assunto de metadados de volume e acesso.	Como realizar uma pesquisa Como recuperar um volume Listar os volumes da biblioteca do usuário Listar os volumes da minha estante
`q`	String de consulta de texto completo.	Ao criar uma consulta, liste os termos de pesquisa separados por um "+", no formato `q=term1+term2_term3`. Você também pode separá-los com um espaço, mas, como acontece com todos os valores de parâmetro de consulta, os espaços precisam ser codificados para URL. A API retorna todas as entradas que correspondem a todos os termos de pesquisa (como usar & entre os termos). Assim como a pesquisa da Web do Google, a API pesquisa palavras completas (e palavras relacionadas com a mesma raiz), não substrings. Para pesquisar uma frase exata, coloque a frase entre aspas: `q="exact phrase"`. Para excluir entradas que correspondem a um determinado termo, use o formulário `q=-term`. Os termos de pesquisa não diferenciam maiúsculas de minúsculas. Exemplo: para pesquisar todas as entradas que contêm a frase exata `"Elizabeth Bennet"` e a palavra `"Darcy"`, mas não a palavra `"Austen"`, use o seguinte valor do parâmetro de consulta: `q="Elizabeth+Bennet"+Darcy-Austen` Há palavras-chave especiais (sensível a maiúsculas e minúsculas) que podem ser especificadas nos termos de pesquisa para pesquisar em campos específicos, como: `intitle`: retorna resultados em que o texto após essa palavra-chave é encontrado no título. `inauthor`: retorna resultados em que o texto após essa palavra-chave é encontrado no autor. `inpublisher`: retorna resultados em que o texto após essa palavra-chave é encontrado no editor. `subject`: retorna resultados em que o texto após essa palavra-chave está listado na lista de categorias do volume. `isbn`: retorna resultados em que o texto após essa palavra-chave é o número ISBN. `lccn`: retorna resultados em que o texto após essa palavra-chave é o número de controle da Biblioteca do Congresso. `oclc`: retorna resultados em que o texto após essa palavra-chave é o número da biblioteca de computador on-line.	Como realizar uma pesquisa
`startIndex`	A posição na coleção em que a lista de resultados vai começar.	Para qualquer solicitação de todos os itens de uma coleção, é possível paginar os resultados especificando `startIndex` e `maxResults` nos parâmetros da solicitação. O índice do primeiro item é 0.	Como realizar uma pesquisa Listar as estantes de livros do usuário Listar os volumes da biblioteca do usuário Listar minhas estantes Listar os volumes da minha estante
`volumeId`	Identifica um volume associado à solicitação.	Especifica o volume a ser adicionado ou removido de uma estante.	Como adicionar um volume à minha estante Remover um volume da minha estante