Índice
Introdução
Este documento é destinado a desenvolvedores que querem criar aplicativos que possam interagir com a API Books. A missão do Google Livros é digitalizar o conteúdo de livros do mundo todo e torná-lo mais detectável na Web. A API Books é uma maneira de pesquisar e acessar esse conteúdo, além de criar e ver a personalização em torno desse conteúdo.
Se você não conhece os conceitos do Google Livros, leia Primeiros passos antes de começar a programar.
Como autorizar solicitações e identificar o aplicativo
Todas as solicitações que seu aplicativo envia à API Books precisam identificá-lo 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 exigir autorização, como uma solicitação de dados particulares de um indivíduo, o aplicativo precisará fornecer um token do OAuth 2.0 com a solicitação. O aplicativo também pode fornecer a chave de API, mas 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. Nenhum outro protocolo de autorização é aceito. Se o aplicativo usa o recurso 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 para 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 necessárias mais tarde, como uma chave secreta e um ID 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 para o 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 ver informações detalhadas sobre fluxos de vários tipos de aplicativos, consulte a documentação do OAuth 2.0 do Google.
Estas são 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, você precisa das informações do escopo, bem como as 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 ser acompanhadas por 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 adequadas para 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 chave de API no Console clicando em Criar credenciais > Chave de API. Para restringir a chave antes de usá-la na produção, clique em Restringir chave e selecione 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.
A chave de API é segura para ser incorporada a URLs sem precisar de codificação.
IDs do Google Livros
Você precisa especificar campos de ID em determinadas chamadas de métodos de API. Há três tipos de IDs usados no Google Livros:
- IDs de volume: strings exclusivas fornecidas a cada volume que o Google Livros conhece. Um exemplo de ID de volume é
_LettPDhwR0C. É possível usar a API para ver o ID do volume fazendo uma solicitação que retorna um recurso de volume. O ID do volume está no campoid. - IDs de estante: são valores numéricos fornecidos a uma estante em uma biblioteca do usuário. O Google fornece algumas estantes predefinidas para cada usuário com os
seguintes IDs:
- Favoritos: 0
- Comprado: 1
- Para ler: 2
- Leitura agora: 3
- Lidos: 4
- Avaliado em: 5
- Vistos recentemente: 6
- Meus e-books: 7
- Livros para você: 8 Se não houver recomendações para o usuário, essa estante não existe.
id. - User-IDs: 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 é extraí-lo do selfLink em um recurso do Bitbucket recuperado com uma solicitação autenticada. Os usuários também podem encontrar seu próprio ID no site Livros. Um usuário não pode receber o ID de outro usuário por meio da API ou do site de livros. O outro usuário precisa compartilhar essas informações explicitamente por e-mail, por exemplo.
IDs no site do Google Livros
Os códigos usados com a API Books são os mesmos usados no site do Google Livros.
- ID do volume
Ao visualizar um volume específico no site, você pode encontrar o ID do volume no parâmetro de URL
id. Veja um exemplo:https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard
- ID da estante
Ao visualizar uma estante específica no site, é possível encontrar o ID da estante no parâmetro de URL
as_coll. Veja um 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 visualizar sua biblioteca no site, você poderá encontrar o ID do usuário no parâmetro de URL
uid. Veja um exemplo:https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list
Configuração de localização do usuário
O Google Livros respeita direitos autorais, contratos e outras restrições legais associadas à localização do usuário final. Como resultado, talvez alguns usuários não consigam acessar o conteúdo de livros de determinados países. Por exemplo, alguns livros são "previewable" somente nos Estados Unidos. Omitimos esses links de visualização 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
É possível fazer uma pesquisa de volumes enviando uma solicitação GET HTTP
para o seguinte URI:
https://www.googleapis.com/books/v1/volumes?q=search+terms
Esta solicitação tem um único parâmetro obrigatório:
q: pesquise volumes que tenham essa string de texto. Existem palavras-chave especiais que você pode especificar 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 esta palavra-chave está 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 Central de bibliotecas de computadores on-line.
Solicitação
Veja um exemplo de pesquisa de Daniel Keyes' "Flores para Algernon":
GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey
Observação: a pesquisa 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, cada
volume incluirá informações específicas do usuário, como o status da compra.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com um
código de status HTTP 200 OK e o volume será resultante:
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, é possível usar os seguintes parâmetros de consulta ao fazer uma pesquisa de volumes.
Formato de download
Use o parâmetro download para restringir os resultados retornados a volumes que tenham um formato de download disponível de epub, definindo com o valor epub.
O exemplo a seguir pesquisa livros com um download de EPUB disponível:
GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey
Filtragem
Você pode usar o parâmetro filter para restringir ainda mais os resultados retornados, definindo-o com um dos seguintes valores:
partial: retorna resultados em que pelo menos partes do texto são visualizáveis.full: retorna apenas resultados em que todo o texto é visível.free-ebooks: retorna apenas resultados do Google e-books sem custo financeiro.paid-ebooks: retorna somente resultados do Google e-books com um preço.ebooks: retorna somente resultados do Google e-books, pagos ou sem custo financeiro. Exemplos de e-books que não são e-books são conteúdos de editores disponíveis em visualização limitada e não à venda, ou em revistas.
O exemplo a seguir restringe os resultados da pesquisa àqueles disponíveis como e-books 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 o início. 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 com um dos seguintes valores:
all: não restringe por tipo de impressão (padrão).books: retorna apenas resultados de 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
Projection
Você pode 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 alguns campos. Consulte as descrições de campos marcadas com asteriscos duplos na Referência de volume para descobrir quais campos estão incluídos.
O exemplo a seguir retorna resultados da pesquisa com informações de volume limitado:
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 para os termos de pesquisa.
É possível mudar a ordem definindo o parâmetro orderBy como um destes valores:
relevance: retorna os resultados em ordem de relevância dos termos de pesquisa (padrão).newest: retorna os resultados na ordem mais recente para menos publicados.
O exemplo a seguir lista os resultados por data de publicação, da mais recente à mais antiga:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey
Como recuperar um volume específico
É possível recuperar informações de um volume específico enviando uma solicitação GET HTTP para o URI de 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 IDs de volume.
Solicitação
Veja 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, 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, o volume incluirá informações específicas do usuário, como
o status da compra.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com o código de status HTTP 200 OK e o recurso 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 particular para determinar
quais recursos estão disponíveis para um e-book. Um epub é um e-book com formato de texto corrido. 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 um exemplo do livro ou se o usuário
puder ler o livro por ter comprado o livro ou por ser de domínio
público no local do usuário. Um pdf para livros do Google indica uma
versão digitalizada de páginas do e-book com detalhes semelhantes. Por exemplo, se ele está
disponível e um link de download. O Google recomenda arquivos epub para
e-readers e SmartPhones, porque 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
e-book do Google.
Parâmetros de consulta opcionais
Além dos parâmetros de consulta padrão, é possível usar o parâmetro de consulta a seguir ao recuperar um volume específico.
Projection
Você pode 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 alguns campos. Consulte as descrições de campos marcadas com asteriscos duplos na Referência de volume para descobrir quais campos estão incluídos.
O exemplo a seguir retorna informações de volume limitado para um único volume:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey
Trabalhando com estantes
Recuperar uma lista das estantes públicas do usuário
Você pode recuperar uma lista das estantes públicas de um usuário enviando uma solicitação
GET HTTP 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 cujas estantes 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 estantes públicas, você não precisa fornecer o cabeçalho HTTP Authorization com a solicitação GET.
Resposta
Se a solicitação for bem-sucedida, o servidor 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
Você pode usar os parâmetros de consulta padrão ao recuperar a lista de estantes públicas de um usuário.
Como recuperar uma estante de livros pública específica
É possível recuperar uma estante pública específica enviando uma solicitação HTTP
GET 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 estante pelos IDs que especificam o usuário e a estante 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 estantes públicas, você não precisa fornecer o cabeçalho HTTP Authorization com a solicitação GET.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com o
código de status HTTP 200 OK e o recurso Paging:
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 recuperar uma estante pública específica.
Como recuperar uma lista de volumes em uma estante de livros pública
É possível recuperar uma lista de volumes na estante pública de um usuário enviando uma solicitação GET HTTP para o 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 estante pelos IDs que especificam o usuário e a estante 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 estantes públicas, você não precisa fornecer o cabeçalho HTTP Authorization com a solicitação GET.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com um código de status HTTP
200 OK e a lista das estantes 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, é possível usar o seguinte parâmetro de consulta ao recuperar uma lista de volumes em uma estante de livros 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 o início. 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.
Trabalhando com estantes em "Minha biblioteca"
Todas as solicitações de "Minha biblioteca" se aplicam aos dados do usuário autenticado.
Recuperando uma lista das minhas estantes
Você pode recuperar uma listagem de todas as estantes de usuários autenticados 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
"quot;My Library"". Portanto, é necessário fornecer o cabeçalho HTTP Authorization com a solicitação GET.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com o código de status HTTP
200 OK e a lista de todas as estantes do usuário autenticado atualmente:
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
Você pode usar os parâmetros de consulta padrão ao recuperar a lista das estantes do usuário autenticado.
Recuperar uma lista de volumes na minha estante
É possível recuperar uma lista dos volumes na estante de usuários autenticados enviando uma solicitação GET HTTP para o URI com o seguinte formato:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes
Substitua o parâmetro de caminho Prateleira pelo ID da estante. Consulte a seção IDs do Google Livros para mais informações sobre IDs de estante.
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 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 responderá com o
código de status HTTP 200 OK e a lista de volumes da estante:
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 seguinte parâmetro de consulta ao recuperar uma lista de volumes em uma das estantes de livros autenticadas dos usuários.
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 o início. O índice do primeiro item é 0.maxResults: o número máximo de resultados a serem retornados. O padrão é 10.
Como adicionar um volume à minha estante
Para adicionar um volume à estante de usuários autenticados, 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 da estante pelo ID da estante. Consulte a seção IDs do Google Livros para mais informações sobre IDs de estante.
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
Veja um exemplo para adicionar "Flores para Algernon" à estante de livros "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 estante. Portanto, forneça o cabeçalho HTTP Authorization com a solicitação POST. No entanto, nenhum dado é necessário com este
POST.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com o Código de status HTTP
204 No Content.
Parâmetros de consulta opcionais
Você pode usar os parâmetros de consulta padrão ao adicionar um volume a uma das estantes do usuário autenticado.
Remover um volume da minha estante
Para remover um volume da estante de usuários autenticados, 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 Prateleira pelo ID da estante. Consulte a seção IDs do Google Livros para mais informações sobre IDs de estante.
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
Veja um exemplo de como remover &flores para Algernon" da estante de 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
Observação: o usuário precisa ser autenticado para fazer modificações em uma estante. Portanto, forneça o cabeçalho HTTP Authorization com a solicitação POST. No entanto, nenhum dado é necessário com este
POST.
Resposta
Se a solicitação for bem-sucedida, o servidor responderá com um código de status 204 No Content.
Parâmetros de consulta opcionais
Você pode usar os parâmetros de consulta padrão ao remover um volume de uma das estantes dos usuários autenticados.
Removendo todos os volumes da minha estante
Para remover todos os volumes da estante de usuários autenticados, envie um POST HTTP ao URI com o seguinte formato:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes
Substitua o parâmetro de caminho Prateleira pelo ID da estante. Consulte a seção IDs do Google Livros para mais informações sobre IDs de estante.
Solicitação
Este é um exemplo para limpar a estante de livros "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
Observação: o usuário precisa ser autenticado para fazer modificações em uma estante. Portanto, forneça o cabeçalho HTTP Authorization com a solicitação POST. No entanto, nenhum dado é necessário com este
POST.
Resposta
Se a solicitação for bem-sucedida, o servidor 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 de livros autenticadas dos usuários.
Referência de parâmetros de consulta
Os parâmetros de consulta que você pode usar com a API Books são resumidos nesta seção.Todos os valores de parâmetro precisam ser codificados para uso em URL.
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 somente 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 por disponibilidade de download. |
|
|
filter |
Filtre os resultados da pesquisa por tipo de volume e disponibilidade. |
|
|
langRestrict |
Restringe os volumes retornados aos que são marcados com o idioma especificado. |
|
|
maxResults |
O número máximo de elementos a serem retornados com essa solicitação. |
|
|
orderBy |
Ordem dos resultados da pesquisa de volume. |
|
|
printType |
Restringir a livros ou revistas. |
|
|
projection |
Restrinja as informações de volume retornadas a um subconjunto de campos. |
|
|
q |
String de consulta de texto completo. |
|
|
startIndex |
A posição na coleção em que a lista de resultados será iniciada. |
|
|
volumeId |
Identifica um volume associado à solicitação. |
|