Cette page a été traduite par l'API Cloud Translation.

Utiliser l'API

Sommaire

Présentation
Utiliser des volumes
1. Effectuer une recherche
2. Récupérer un volume spécifique
Utiliser les étagères
Utiliser les bibliothèques dans "Ma bibliothèque"
Référence des paramètres de requête
1. Paramètres de requête standards
2. Paramètres de requête spécifiques à l'API

Introduction

Ce document s'adresse aux développeurs qui souhaitent écrire des applications pouvant interagir avec l'API Livres. Google Livres a pour mission de numériser le contenu des livres du monde entier et de le rendre plus visible sur le Web. L'API Books permet de rechercher et d'accéder à ce contenu, ainsi que de créer et d'afficher des personnalisations autour de ce contenu.

Si vous ne connaissez pas les concepts de Google Livres, lisez la section Premiers pas avant de commencer à coder.

Autoriser les requêtes et identifier votre application

Chaque requête que votre application envoie à l'API Books doit identifier votre application auprès de Google. Pour cela, vous pouvez procéder de deux manières : à l'aide d'un jeton OAuth 2.0 (qui autorise également la requête) et/ou à l'aide de la clé API de l'application. Voici comment déterminer l'option à utiliser :

Si la demande nécessite une autorisation (par exemple, s'il s'agit d'une demande de données privées d'un individu), l'application doit fournir un jeton OAuth 2.0 avec la requête. L'application peut également fournir sa clé API, mais ce n'est pas obligatoire.
Si la demande ne nécessite pas d'autorisation (par exemple, s'il s'agit d'une demande de données publiques), l'application doit fournir soit la clé API, soit un jeton OAuth 2.0, soit les deux, selon ce qui vous convient le mieux.

À propos des protocoles d'autorisation

Votre application doit autoriser les requêtes via le protocole OAuth 2.0. Les autres protocoles d'autorisation ne sont pas acceptés. Si votre application utilise la fonctionnalité Se connecter avec Google, certains aspects de l'autorisation sont traités pour vous.

Autoriser des requêtes avec OAuth 2.0

Les requêtes adressées à l'API Books portant sur des données utilisateur non publiques doivent être autorisées par un utilisateur authentifié.

Les détails de la procédure d'autorisation (ou "flux") concernant OAuth 2.0 varient légèrement selon le type d'application que vous développez. La procédure générale suivante s'applique à tous les types d'applications :

Lorsque vous créez votre application, vous l'enregistrez dans la console d'API Google. Google fournit ensuite des informations dont vous aurez besoin ultérieurement, dont un ID client et un code secret du client.
Activez l'API Books dans la console Google APIs. Si l'API ne figure pas dans la console, ignorez cette étape.
Lorsque votre application doit accéder à des données utilisateur, elle demande à Google un champ d'application d'accès particulier.
Google affiche alors un écran d'autorisation, dans lequel l'utilisateur est invité à autoriser votre application à demander certaines de ses données.
Si l'utilisateur accepte, Google attribue à votre application un jeton d'accès temporaire.
Votre application demande des données utilisateur en joignant le jeton d'accès à la requête.
Dès lors que Google valide la requête et le jeton, les données demandées sont renvoyées.

Certains flux comportent des étapes supplémentaires, comme l'utilisation de jetons d'actualisation en vue de l'acquisition de nouveaux jetons d'accès. Pour en savoir plus sur les flux concernant divers types d'applications, consultez la documentation OAuth 2.0 de Google.

Voici les informations sur le champ d'application OAuth 2.0 pour l'API Books:

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

Pour demander l'accès via OAuth 2.0, vous avez besoin du champ d'application ainsi que des informations fournies par Google lors de l'enregistrement de l'application (l'ID client et le code secret du client, par exemple).

Conseil : Les bibliothèques clientes des API Google peuvent gérer une partie de la procédure d'autorisation à votre place. Elles sont proposées pour une grande variété de langages de programmation. Pour en savoir plus, explorez les bibliothèques clientes et les exemples de code présentés sur la page Installer les bibliothèques clientes.

Obtenir et utiliser une clé API

Les requêtes adressées à l'API Livres qui interrogent des données publiques doivent être accompagnées d'un identifiant, qui peut être une clé API ou un jeton d'accès.

Pour obtenir une clé API :

Ouvrez la page Identifiants dans la console API.
Deux types d'identifiants sont disponibles pour cette API. Créez les identifiants adaptés à votre projet :
- OAuth 2.0 : chaque fois que votre application demande des données utilisateur privées, elle doit envoyer un jeton OAuth 2.0 en même temps que la requête. Votre application envoie d'abord un identifiant client, puis éventuellement un code secret du client pour obtenir un jeton. Vous pouvez générer des identifiants OAuth 2.0 pour des applications Web, des comptes de service ou des applications installées.
  
  Pour en savoir plus, consultez la documentation OAuth 2.0.
- Clés API : une demande qui ne fournit pas de jeton OAuth 2.0 doit envoyer une clé API. Cette clé identifie votre projet et vous donne accès à l'API, aux quotas et aux rapports.
  
  L'API propose plusieurs types de restrictions applicables aux clés API. Si la clé API requise n'existe pas déjà, créez-en une dans la console en cliquant sur Créer des identifiants > Clé API. Vous pouvez restreindre la clé avant de l'utiliser en production en cliquant sur Restreindre la clé et en sélectionnant l'une des restrictions.

Pour sécuriser vos clés API, suivez les bonnes pratiques pour utiliser des clés API en toute sécurité.

Une fois la clé API obtenue, votre application peut ajouter le paramètre de requête key=yourAPIKey à toutes les URL de requête.

La clé API peut s'intégrer aux URL en toute sécurité et ne nécessite pas d'encodage.

ID Google Livres

Vous devez spécifier des champs d'ID avec certains appels de méthode d'API. Trois types d'ID sont utilisés dans Google Livres:

ID de volume : chaînes uniques attribuées à chaque volume connu par Google Livres. Voici un exemple d'ID de volume : _LettPDhwR0C. Vous pouvez utiliser l'API pour obtenir l'ID de volume en effectuant une requête qui renvoie une ressource Volume. Vous trouverez l'ID de volume dans son champ id.
ID de bibliothèque : valeurs numériques attribuées à une bibliothèque dans la bibliothèque d'un utilisateur. Google fournit des sections prédéfinies pour chaque utilisateur avec les ID suivants :
- Favoris: 0
- Achetés: 1
- À lire: 2
- En cours de lecture: 3
- Déjà lus: 4
- Examiné: 5
- Consultés récemment: 6
- Mes e-books: 7
- Livres pour vous: 8 Si nous n'avons aucune recommandation pour l'utilisateur, cette étagère n'existe pas.
Les étagères personnalisées ont des ID supérieurs à 1 000. Un identifiant de bibliothèque est unique pour un utilisateur donné. Autrement dit, deux utilisateurs peuvent avoir une bibliothèque avec le même identifiant qui fait référence à des bibliothèques différentes. Vous pouvez utiliser l'API pour obtenir l'ID de la bibliothèque en effectuant une requête qui renvoie une ressource Bookshelf. Vous trouverez l'ID de la bibliothèque dans son champ id.
ID utilisateur : valeurs numériques uniques attribuées à chaque utilisateur. Ces valeurs ne correspondent pas nécessairement à la même valeur d'ID utilisée dans d'autres services Google. Actuellement, le seul moyen de récupérer l'ID utilisateur est de l'extraire du selfLink dans une ressource Bookshelf récupérée avec une requête authentifiée. Les utilisateurs peuvent également obtenir leur propre ID utilisateur sur le site Books. Un utilisateur ne peut pas obtenir l'ID utilisateur d'un autre utilisateur via l'API ou le site Books. L'autre utilisateur doit partager ces informations explicitement, par e-mail, par exemple.

ID sur le site Google Livres

Les ID que vous utilisez avec l'API Books sont les mêmes que ceux utilisés sur le site Google Books.

ID du volume

Lorsque vous consultez un volume particulier sur le site, vous pouvez trouver son ID dans le paramètre d'URL id. Voici un exemple :
```
https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard
```
ID de l'étagère

Lorsque vous consultez une bibliothèque particulière sur le site, vous pouvez trouver son ID dans le paramètre d'URL as_coll. Voici un exemple :
```
https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary
```
ID utilisateur

Lorsque vous consultez votre bibliothèque sur le site, vous pouvez trouver l'ID utilisateur dans le paramètre d'URL uid. Voici un exemple :
```
https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list
```

Définir la position de l'utilisateur

Google Livres respecte les droits d'auteur, les contrats et les autres restrictions légales associées à la localisation de l'utilisateur final. Par conséquent, il se peut que certains utilisateurs ne puissent pas accéder au contenu des livres dans certains pays. Par exemple, certains livres ne sont disponibles en aperçu que dans les États-Unis. Nous omettons ces liens d'aperçu pour les utilisateurs d'autres pays. Par conséquent, les résultats de l'API sont limités en fonction de l'adresse IP de votre serveur ou de votre application cliente.

Utiliser des volumes

Effectuer une recherche

Vous pouvez effectuer une recherche de volumes en envoyant une requête HTTP GET à l'URI suivant:

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

Cette requête comporte un seul paramètre obligatoire:

q : recherchez les volumes contenant cette chaîne de texte. Vous pouvez spécifier des mots clés spéciaux dans les termes de recherche pour effectuer des recherches dans des champs particuliers, par exemple :
- intitle: : renvoie les résultats pour lesquels le texte suivant ce mot clé est trouvé dans le titre.
- inauthor: Renvoie les résultats dans lesquels le texte suivant ce mot clé est trouvé dans l'auteur.
- inpublisher: : renvoie les résultats pour lesquels le texte suivant ce mot clé est trouvé dans l'éditeur.
- subject: : renvoie les résultats pour lesquels le texte suivant ce mot clé figure dans la liste des catégories du volume.
- isbn: : renvoie les résultats pour lesquels le texte suivant ce mot clé est le numéro ISBN.
- lccn: Renvoie les résultats pour lesquels le texte suivant ce mot clé correspond au numéro de contrôle de la Bibliothèque du Congrès.
- oclc: Renvoie les résultats pour lesquels le texte suivant ce mot clé correspond au numéro OCLC.

Requête

Voici un exemple de recherche de "Flowers for Algernon" de Daniel Keyes :

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

Remarque: L'exécution d'une recherche ne nécessite pas d'authentification. Vous n'avez donc pas besoin de fournir l'en-tête HTTP Authorization avec la requête GET. Toutefois, si l'appel est effectué avec authentification, chaque volume inclura des informations spécifiques à l'utilisateur, telles que l'état de l'achat.

Réponse

Si la requête aboutit, le serveur répond par un code d'état HTTP 200 OK et les résultats du 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
}

Paramètres de requête facultatifs

En plus des paramètres de requête standards, vous pouvez utiliser les paramètres de requête suivants lorsque vous effectuez une recherche de volumes.

Format de téléchargement

Vous utilisez le paramètre download pour limiter les résultats renvoyés aux volumes dont le format de téléchargement disponible est epub en définissant sur la valeur epub.

L'exemple suivant recherche des livres pour lesquels un téléchargement au format EPUB est disponible:

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

Filtrage

Vous pouvez utiliser le paramètre filter pour limiter davantage les résultats renvoyés en le définissant sur l'une des valeurs suivantes:

partial : renvoie des résultats dont au moins une partie du texte peut être prévisualisée.
full : renvoie uniquement les résultats pour lesquels tout le texte est visible.
free-ebooks : renvoie uniquement les résultats correspondant à des e-books Google sans frais.
paid-ebooks : ne renvoie que les résultats correspondant à des e-books Google avec un prix.
ebooks : renvoie uniquement les résultats qui sont des e-books Google, payants ou sans frais. Il peut s'agir, par exemple, de contenus d'éditeurs disponibles en aperçu limité et non disponibles à la vente, ou de magazines.

L'exemple suivant limite les résultats de recherche à ceux disponibles en tant qu'e-books sans frais:

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

Pagination

Vous pouvez paginer la liste des volumes en spécifiant deux valeurs dans les paramètres de la requête:

startIndex : position dans la collection à partir de laquelle commencer. L'indice du premier élément est 0.
maxResults : nombre maximal de résultats à renvoyer. La valeur par défaut est 10 et la valeur maximale autorisée est 40.

Type d'impression

Vous pouvez utiliser le paramètre printType pour limiter les résultats renvoyés à un type d'impression ou de publication spécifique en le définissant sur l'une des valeurs suivantes:

all : ne limite pas par type d'impression (valeur par défaut).
books : renvoie uniquement les résultats correspondant à des livres.
magazines : renvoie des résultats qui sont des magazines.

L'exemple suivant limite les résultats de recherche aux magazines:

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

Projection

Vous pouvez utiliser le paramètre projection avec l'une des valeurs suivantes pour spécifier un ensemble prédéfini de champs Volume à renvoyer:

full : renvoie tous les champs Volume.
lite : ne renvoie que certains champs. Consultez les descriptions des champs marqués par deux astérisques dans la section Référence du volume pour savoir quels champs sont inclus.

L'exemple suivant renvoie des résultats de recherche avec des informations sur le volume limitées:

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

Tri

Par défaut, une requête de recherche de volumes renvoie des résultats maxResults, où maxResults est le paramètre utilisé dans la pagination (ci-dessus), classés par pertinence par rapport aux termes de recherche.

Vous pouvez modifier l'ordre en définissant le paramètre orderBy sur l'une des valeurs suivantes:

relevance : renvoie les résultats par ordre de pertinence des termes de recherche (valeur par défaut).
newest : renvoie les résultats dans l'ordre de publication, du plus récent au moins récent.

L'exemple suivant liste les résultats par date de publication, du plus récent au plus ancien:

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

Récupérer un volume spécifique

Vous pouvez récupérer des informations sur un volume spécifique en envoyant une requête HTTP GET à l'URI de la ressource Volume:

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

Remplacez le paramètre de chemin d'accès volumeId par l'ID du volume à récupérer. Pour en savoir plus sur les ID de volume, consultez la section ID Google Books.

Requête

Voici un exemple de requête GET qui récupère un seul volume:

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

Remarque: La récupération d'informations sur le volume ne nécessite pas d'authentification. Vous n'avez donc pas besoin de fournir l'en-tête HTTP Authorization avec la requête GET. Toutefois, si l'appel est effectué avec une authentification, le volume inclura des informations spécifiques à l'utilisateur, telles que l'état de l'achat.

Réponse

Si la requête aboutit, le serveur répond avec le code d'état HTTP 200 OK et la ressource Volume demandée:

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

Informations d'accès

La section accessInfo est particulièrement utile pour déterminer les fonctionnalités disponibles pour un e-book. Un epub est un e-book au format de texte courant. La section epub comporte une propriété isAvailable indiquant si ce type d'e-book est disponible. Un lien de téléchargement s'affiche si un extrait du livre est disponible ou si l'utilisateur peut le lire, soit parce qu'il l'a acheté, soit parce qu'il est dans le domaine public dans la région de l'utilisateur. Un pdf pour Google Livres indique une version de l'e-book avec des pages numérisées, avec des informations similaires, comme s'il est disponible et un lien de téléchargement. Google recommande les fichiers epub pour les liseuses et les smartphones, car les pages numérisées peuvent être difficiles à lire sur ces appareils. Si aucune section accessInfo n'est disponible, le volume n'est pas disponible en tant que livre numérique Google.

Paramètres de requête facultatifs

En plus des paramètres de requête standards, vous pouvez utiliser le paramètre de requête suivant lorsque vous récupérez un volume spécifique.

Projection

Vous pouvez utiliser le paramètre projection avec l'une des valeurs suivantes pour spécifier un ensemble prédéfini de champs Volume à renvoyer:

full : renvoie tous les champs Volume.
lite : ne renvoie que certains champs. Consultez les descriptions des champs marqués par deux astérisques dans la section Référence du volume pour savoir quels champs sont inclus.

L'exemple suivant renvoie des informations limitées sur un seul volume:

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

Utiliser des bibliothèques

Récupérer la liste des bibliothèques publiques d'un utilisateur

Vous pouvez récupérer la liste des bibliothèques publiques d'un utilisateur en envoyant une requête GET HTTP à l'URI au format suivant:

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

Remplacez le paramètre de chemin userId par l'ID de l'utilisateur dont vous souhaitez récupérer les bibliothèques. Pour en savoir plus sur les ID utilisateur, consultez la section ID Google Livres.

Requête

Voici un exemple :

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

Étant donné qu'un utilisateur n'a pas besoin d'être authentifié pour récupérer des informations sur les bibliothèques publiques, vous n'avez pas besoin de fournir l'en-tête HTTP Authorization avec la requête GET.

Réponse

Si la requête aboutit, le serveur répond avec le code d'état HTTP 200 OK et la liste des bibliothèques:

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

Paramètres de requête facultatifs

Vous pouvez utiliser les paramètres de requête standards lorsque vous récupérez la liste des bibliothèques publiques d'un utilisateur.

Récupérer une bibliothèque publique spécifique

Vous pouvez récupérer une bibliothèque publique spécifique en envoyant une requête HTTP GET à l'URI au format suivant:

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

Remplacez les paramètres de chemin userId et shelf par les ID qui spécifient l'utilisateur et la bibliothèque que vous souhaitez récupérer. Pour en savoir plus, consultez la section ID Google Books.

Requête

Voici un exemple :

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

Réponse

Si la requête aboutit, le serveur répond avec le code d'état HTTP 200 OK et la ressource de bibliothèque:

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

Paramètres de requête facultatifs

Vous pouvez utiliser les paramètres de requête standards lorsque vous récupérez une bibliothèque publique spécifique.

Récupération d'une liste de volumes sur une bibliothèque publique

Vous pouvez récupérer la liste des volumes de la bibliothèque publique d'un utilisateur en envoyant une requête HTTP GET à un URI au format suivant:

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

Requête

Voici un exemple :

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

Réponse

Si la requête aboutit, le serveur répond avec un code d'état HTTP 200 OK et la liste des bibliothèques de l'utilisateur:

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
}

Paramètres de requête facultatifs

En plus des paramètres de requête standards, vous pouvez utiliser le paramètre de requête suivant lorsque vous récupérez une liste de volumes sur une bibliothèque publique.

Pagination

Vous pouvez paginer la liste des volumes en spécifiant deux valeurs dans les paramètres de la requête:

startIndex : position dans la collection à partir de laquelle commencer. L'indice du premier élément est 0.
maxResults : nombre maximal de résultats à renvoyer. La valeur par défaut est 10 et la valeur maximale autorisée est 40.

Utiliser les étagères dans "Ma bibliothèque"

Toutes les requêtes "Ma bibliothèque" s'appliquent aux données de l'utilisateur authentifié.

Récupérer la liste de mes bibliothèques

Vous pouvez récupérer la liste de toutes les bibliothèques de l'utilisateur authentifié en envoyant une requête HTTP GET à l'URI au format suivant:

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

Requête

Voici un exemple :

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

Remarque: L'utilisateur doit être authentifié pour récupérer la liste des bibliothèques "Ma bibliothèque". Vous devez donc fournir l'en-tête HTTP Authorization avec la requête GET.

Réponse

Si la requête aboutit, le serveur renvoie le code d'état HTTP 200 OK et la liste de toutes les bibliothèques de l'utilisateur authentifié actuel:

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

Paramètres de requête facultatifs

Vous pouvez utiliser les paramètres de requête standards lorsque vous récupérez la liste des bibliothèques de l'utilisateur authentifié.

Récupérer la liste des volumes de ma bibliothèque

Vous pouvez récupérer la liste des volumes sur la bibliothèque de l'utilisateur authentifié en envoyant une requête HTTP GET à l'URI au format suivant:

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

Remplacez le paramètre de chemin shelf par l'ID de la bibliothèque. Pour en savoir plus sur les ID de bibliothèque, consultez la section ID Google Books.

Requête

Voici un exemple :

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

Remarque: L'utilisateur doit être authentifié pour récupérer la liste des volumes de "Ma bibliothèque". Vous devez donc fournir l'en-tête HTTP Authorization avec la requête GET.

Réponse

Si la requête aboutit, le serveur répond avec le code d'état HTTP 200 OK et la liste des volumes de la bibliothèque:

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
}

Paramètres de requête facultatifs

En plus des paramètres de requête standards, vous pouvez utiliser le paramètre de requête suivant lorsque vous récupérez une liste de volumes sur l'une des bibliothèques de l'utilisateur authentifié.

Pagination

Vous pouvez paginer la liste des volumes en spécifiant deux valeurs dans les paramètres de la requête:

startIndex : position dans la collection à partir de laquelle commencer. L'indice du premier élément est 0.
maxResults : nombre maximal de résultats à renvoyer. La valeur par défaut est 10.

Ajouter un volume à ma bibliothèque

Pour ajouter un volume à la bibliothèque de l'utilisateur authentifié, envoyez une requête HTTP POST à l'URI au format suivant:

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

Remplacez le paramètre de chemin shelf par l'ID de la bibliothèque. Pour en savoir plus sur les ID de bibliothèque, consultez la section ID Google Books.

La requête comporte un seul paramètre de requête obligatoire:

volumeId : ID du volume. Pour en savoir plus sur les ID de volume, consultez la section ID Google Books.

Requête

Voici un exemple d'ajout de "Flowers for Algernon" à l'étagère "Favoris" :

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

Remarque: L'utilisateur doit être authentifié pour apporter des modifications à une bibliothèque. Vous devez donc fournir l'en-tête HTTP Authorization avec la requête POST. Cependant, aucune donnée n'est requise avec cette POST.

Réponse

Si la requête aboutit, le serveur répond avec le code d'état HTTP 204 No Content.

Paramètres de requête facultatifs

Vous pouvez utiliser les paramètres de requête standards lorsque vous ajoutez un volume à l'une des bibliothèques de l'utilisateur authentifié.

Supprimer un volume de ma bibliothèque

Pour supprimer un volume de la bibliothèque de l'utilisateur authentifié, envoyez un POST HTTP à l'URI au format suivant:

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

Remplacez le paramètre de chemin shelf par l'ID de la bibliothèque. Pour en savoir plus sur les ID de bibliothèque, consultez la section ID Google Books.

La requête comporte un seul paramètre de requête obligatoire:

volumeId : ID du volume. Pour en savoir plus sur les ID de volume, consultez la section ID Google Books.

Requête

Voici un exemple pour supprimer "Flowers for Algernon" de la bibliothèque "Favoris" :

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

Réponse

Si la requête aboutit, le serveur répond avec un code d'état 204 No Content.

Paramètres de requête facultatifs

Vous pouvez utiliser les paramètres de requête standards lorsque vous supprimez un volume de l'une des bibliothèques de l'utilisateur authentifié.

Supprimer tous les volumes de ma bibliothèque

Pour supprimer tous les volumes de la bibliothèque de l'utilisateur authentifié, envoyez un POST HTTP à l'URI avec le format suivant:

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

Remplacez le paramètre de chemin shelf par l'ID de la bibliothèque. Pour en savoir plus sur les ID de bibliothèque, consultez la section ID Google Books.

Requête

Voici un exemple pour vider l'étagère "Favoris" :

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

Réponse

Si la requête aboutit, le serveur répond par un code d'état 204 No Content.

Paramètres de requête facultatifs

Vous pouvez utiliser les paramètres de requête standards pour effacer tous les volumes de l'une des bibliothèques de l'utilisateur authentifié.

Référence des paramètres de requête

Les paramètres de requête que vous pouvez utiliser avec l'API Books sont résumés dans cette section. Toutes les valeurs de paramètre doivent être encodées au format URL.

Paramètres de requête standards

Les paramètres de requête qui s'appliquent à toutes les opérations de l'API Books sont répertoriés sur la page Paramètres système.

Paramètres de requête spécifiques à l'API

Les paramètres de requête qui ne s'appliquent qu'à des opérations spécifiques de l'API Books sont résumés dans le tableau suivant.

Paramètre	Signification	Remarques	Applicabilité
`download`	Limiter les volumes en fonction de la disponibilité du téléchargement	Actuellement, la seule valeur acceptée est `epub`. Un achat peut être requis pour accéder au téléchargement.	Effectuer une recherche
`filter`	Filtrez les résultats de recherche par type de volume et disponibilité.	Les filtres compatibles sont les suivants : `filter=partial` : limite les résultats aux volumes dont au moins une partie du texte est disponible en aperçu. `filter=full` : limite les résultats aux volumes où tout le texte est visible. `filter=free-ebooks` : limite les résultats aux livres numériques sans frais sur Google. `filter=paid-ebooks` : limite les résultats aux e-books Google avec un prix d'achat. `filter=ebooks` : limite les résultats aux livres numériques Google, payants ou gratuits.Les contenus non numériques peuvent être des contenus d'éditeurs disponibles en aperçu limité et non disponibles à la vente, ou des magazines.	Effectuer une recherche
`langRestrict`	Limite les volumes renvoyés à ceux tagués avec la langue spécifiée.	Limitez les résultats de recherche à ceux d'une certaine langue en spécifiant `langRestrict` à un code ISO-639-1 à deux lettres, comme "en" ou "fr".	Effectuer une recherche
`maxResults`	Nombre maximal d'éléments à renvoyer avec cette requête.	Pour toute requête concernant tous les éléments d'une collection, vous pouvez paginer les résultats en spécifiant `startIndex` et `maxResults` dans les paramètres de la requête. Valeur par défaut : `maxResults=10` Valeur maximale autorisée: `maxResults=40.`	Effectuer une recherche Lister les bibliothèques d'utilisateurs Lister les volumes de la bibliothèque d'un utilisateur Lister mes étagères Lister les volumes de mon étagère
`orderBy`	Ordre des résultats de recherche sur le volume.	Par défaut, une requête de recherche renvoie des résultats `maxResults`, où `maxResults` est le paramètre utilisé dans la pagination, classés par ordre de pertinence. Vous pouvez modifier l'ordre en définissant le paramètre `orderBy` sur l'une des valeurs suivantes : `orderBy=relevance` : renvoie les résultats de recherche par ordre de pertinence (par défaut). `orderBy=newest` : renvoie les résultats de recherche par ordre chronologique, du plus récent au plus ancien.	Effectuer une recherche
`printType`	Limitez-vous aux livres ou aux magazines.	Les valeurs acceptées sont les suivantes : `printType=all` : renvoie tous les types de contenus de volume (aucune restriction). Il s'agit de la valeur par défaut. `printType=books` : renvoie uniquement les livres. `printType=magazines` : renvoie uniquement les magazines.	Effectuer une recherche
`projection`	Limitez les informations sur le volume renvoyées à un sous-ensemble de champs.	Les projections acceptées sont les suivantes : `projection=full` : inclut toutes les métadonnées de volume (par défaut). `projection=lite` : n'inclut que l'objet des métadonnées de volume et d'accès.	Effectuer une recherche Récupérer un volume Lister les volumes de la bibliothèque d'un utilisateur Lister les volumes de mon étagère
`q`	Chaîne de requête en texte intégral.	Lorsque vous créez une requête, listez les termes de recherche séparés par un signe +, sous la forme `q=term1+term2_term3`. (Vous pouvez également les séparer par un espace, mais comme pour toutes les valeurs de paramètre de requête, les espaces doivent alors être encodés au format URL.) L'API renvoie toutes les entrées correspondant à tous les termes de recherche (par exemple, en utilisant AND entre les termes). Comme la recherche Web de Google, l'API recherche des mots complets (et des mots associés avec la même racine), et non des sous-chaînes. Pour rechercher une expression exacte, placez-la entre guillemets: `q="exact phrase"`. Pour exclure les entrées correspondant à un terme donné, utilisez le formulaire `q=-term`. Les termes de recherche ne sont pas sensibles à la casse. Exemple: pour rechercher toutes les entrées contenant la phrase exacte `"Elizabeth Bennet"` et le mot `"Darcy"`, mais pas le mot `"Austen"`, utilisez la valeur de paramètre de requête suivante: `q="Elizabeth+Bennet"+Darcy-Austen` Vous pouvez spécifier des mots clés spéciaux (sensibles à la casse) dans les termes de recherche pour effectuer des recherches dans des champs spécifiques, par exemple : `intitle`: renvoie les résultats dans lesquels le texte suivant ce mot clé est trouvé dans le titre. `inauthor`: renvoie les résultats dans lesquels le texte suivant ce mot clé est trouvé dans l'auteur. `inpublisher`: renvoie les résultats dans lesquels le texte suivant ce mot clé est trouvé dans l'éditeur. `subject`: renvoie les résultats pour lesquels le texte suivant ce mot clé figure dans la liste des catégories du volume. `isbn`: renvoie les résultats pour lesquels le texte suivant ce mot clé est le numéro ISBN. `lccn`: renvoie les résultats pour lesquels le texte suivant ce mot clé correspond au numéro de contrôle de la Library of Congress. `oclc`: renvoie les résultats pour lesquels le texte suivant ce mot clé correspond au numéro du Online Computer Library Center.	Effectuer une recherche
`startIndex`	Position dans la collection à partir de laquelle commencer la liste de résultats.	Pour toute requête concernant tous les éléments d'une collection, vous pouvez paginer les résultats en spécifiant `startIndex` et `maxResults` dans les paramètres de la requête. L'indice du premier élément est 0.	Effectuer une recherche Lister les bibliothèques d'utilisateurs Lister les volumes de la bibliothèque d'un utilisateur Lister mes étagères Lister les volumes de mon étagère
`volumeId`	Identifie un volume associé à la requête.	Spécifie le volume à ajouter ou à supprimer d'une bibliothèque.	Ajouter un volume à ma bibliothèque Supprimer un volume de ma bibliothèque