Contenus
Introduction
Ce document est destiné aux développeurs qui souhaitent écrire des applications capables d'interagir avec l'API Livres. Google Livres a pour mission de numériser le contenu mondial des livres et de le rendre plus visible sur le Web. L'API Livres permet de rechercher du contenu et d'y accéder, ainsi que de créer et d'afficher des personnalisations autour de ce contenu.
Si vous ne connaissez pas les concepts de Google Livres, consultez la page Premiers pas avant de commencer à coder.
Autoriser les requêtes et identifier votre application
Chaque requête envoyée à l'API Livres par votre application doit permettre à Google de l'identifier. 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 requête nécessite une autorisation (par exemple, une requête concernant des données personnelles), l'application doit fournir un jeton OAuth 2.0. L'application peut également fournir la 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 Livres pour 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 Livres 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 d'autres étapes, comme l'utilisation de jetons d'actualisation afin d'obtenir 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 relatives au champ d'application OAuth 2.0 pour l'API Livres:
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 pour 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 dont vous avez besoin n'existe pas déjà, créez une clé API 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 ID avec certains appels de méthode API. Il existe trois types d'ID utilisés dans Google Livres:
- ID de volume : chaînes uniques donné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 de volume. Vous pouvez trouver l'ID de volume dans son champid. - ID d'étagère : valeurs numériques attribuées à une étagère dans une bibliothèque d'utilisateur. Google fournit des étagères prédéfinies pour chaque utilisateur avec les ID suivants :
- Favoris: 0
- Achats: 1
- À lire: 2
- En cours de lecture: 3
- Déjà lu: 4
- Avis: 5
- Consultés récemment: 6
- Mes e-books: 7
- Livres pour vous: 8 Si nous ne proposons aucune recommandation à l'utilisateur, cette étagère n'existe pas.
id. - ID utilisateur : valeurs numériques uniques attribuées à chaque utilisateur. Ces valeurs ne sont pas nécessairement identiques à celles utilisées dans d'autres services Google. Actuellement, le seul moyen d'extraire l'ID utilisateur consiste à l'extraire de l'élément "selfLink" d'une ressource d'étagère récupérée avec une requête authentifiée. Les utilisateurs peuvent également obtenir leur propre ID utilisateur sur le site de Google Livres. Un utilisateur ne peut pas obtenir l'ID utilisateur d'un autre utilisateur via l'API ou le site Google Livres. L'autre utilisateur doit partager explicitement cette information, par e-mail, par exemple.
Identifiants sur le site Google Livres
Les ID que vous utilisez avec l'API Livres sont les mêmes que ceux utilisés sur le site Google Livres.
- ID du volume
Lorsque vous consultez un volume particulier sur le site, vous pouvez trouver l'ID de volume 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 d'étagère
Lorsque vous consultez une étagère spécifique 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éfinition de la localisation de l'utilisateur
Google Livres respecte les droits d'auteur, les contrats et les autres restrictions légales associées à l'emplacement de l'utilisateur final. Par conséquent, certains utilisateurs risquent de ne pas pouvoir accéder au contenu de livres de certains pays. Par exemple, certains livres ne peuvent être prévisualisés qu'aux États-Unis. Nous oignons de tels 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 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: recherche 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 contenant le texte qui suit ce mot clé dans le titre.inauthor:Renvoie les résultats contenant le texte qui suit ce mot clé dans l'auteur.inpublisher:Renvoie les résultats contenant le texte qui suit ce mot clé dans l'éditeur.subject:Renvoie les résultats lorsque le texte qui suit ce mot clé est répertorié dans la liste des catégories du volume.isbn:Renvoie les résultats où le texte qui suit ce mot clé correspond au numéro ISBN.lccn:Renvoie les résultats pour lesquels le texte qui suit 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 qui suit ce mot clé correspond au numéro du centre de bibliothèque en ligne.
Demande
Voici un exemple de recherche sur"Daniel Keyes" (fleurs pour Algernon) :
GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey
Remarque: L'authentification 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 inclut des informations spécifiques à l'utilisateur, telles que l'état acheté.
Réponse
Si la requête aboutit, le serveur renvoie 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
Outre les paramètres de requête standards, vous pouvez utiliser les paramètres de requête suivants lorsque vous recherchez des volumes.
Format de téléchargement
Utilisez le paramètre download pour limiter les résultats affichés aux volumes ayant un format de téléchargement disponible de epub en définissant sur la valeur epub.
L'exemple suivant recherche les livres avec un téléchargement EPUB 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 restreindre davantage les résultats renvoyés en le définissant sur l'une des valeurs suivantes:
partial: renvoie les résultats dont au moins certaines parties du texte peuvent être prévisualisées.full: renvoie uniquement les résultats où tout le texte est visible.free-ebooks: renvoie uniquement les résultats correspondant à des e-books Google offerts.paid-ebooks: renvoie uniquement les résultats qui sont des e-books Google avec un prix.ebooks: renvoie uniquement les résultats Google eBooks, payants ou offerts. 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 offerts:
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 à laquelle la collection doit commencer. L'index 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 fait pas de restriction par type d'impression (par défaut).books: renvoie uniquement les résultats correspondant à des livres.magazines: renvoie les résultats correspondant à 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 de volume à afficher:
full: renvoie tous les champs de volume.lite: renvoie uniquement certains champs. Pour savoir quels champs sont inclus, consultez les descriptions des champs marquées d'astérisques dans les références de volume.
L'exemple suivant renvoie des résultats de recherche avec des informations de volume limité:
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 ordre de 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 (option par défaut).newest: renvoie les résultats du plus récent au moins récent.
L'exemple suivant répertorie les résultats par date de publication, de la plus récente à la plus ancienne:
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 les informations d'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. Consultez la section ID Google Livres pour en savoir plus sur les ID de volume.
Demande
Voici un exemple de requête GET qui reçoit un seul volume:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey
Remarque: La récupération des informations de 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é par authentification, le volume inclut des informations spécifiques à l'utilisateur, telles que l'état d'achat.
Réponse
Si la requête aboutit, le serveur renvoie le code d'état HTTP 200 OK et la ressource de 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 sur l'accès
La section accessInfo est particulièrement intéressante pour déterminer les fonctionnalités disponibles pour un e-book. epub est un e-book au format texte flottant. La section epub comporte une propriété isAvailable indiquant si ce type d'e-book est disponible.
Un lien de téléchargement sera disponible s'il existe un extrait pour le livre ou si l'utilisateur peut le lire, soit parce qu'il l'a acheté, soit parce qu'il appartient au domaine public à l'emplacement de l'utilisateur. Un pdf pour Google Livres indique une version numérisée de l'e-book avec des détails similaires, par exemple si celui-ci est disponible et un lien de téléchargement. Google recommande l'utilisation de fichiers epub pour les liseuses et les smartphones, car les pages numérisées peuvent être difficiles à lire sur ces appareils.
S'il n'y a pas de section accessInfo, le volume n'est pas disponible dans l'e-book Google.
Paramètres de requête facultatifs
Outre les 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 de volume à afficher:
full: renvoie tous les champs de volume.lite: renvoie uniquement certains champs. Pour savoir quels champs sont inclus, consultez les descriptions des champs marquées d'astérisques dans les références de volume.
L'exemple suivant renvoie des informations de volume limité pour un seul volume:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey
Utiliser des étagères
Récupération de la liste des étagères publiques d'un utilisateur
Vous pouvez récupérer la liste des étagères publiques d'un utilisateur en envoyant une requête HTTP GET à 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 étagères. Consultez la section ID Google Livres pour en savoir plus sur les ID utilisateur.
Demande
Par 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 les informations concernant les étagères 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 renvoie le code d'état HTTP 200 OK et la liste des étagères:
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 étagères publiques d'un utilisateur.
Récupérer une étagère publique spécifique
Vous pouvez récupérer une étagère 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 bookshelf par les ID spécifiant l'utilisateur et l'étagère que vous souhaitez récupérer. Pour en savoir plus, consultez la section ID Google Livres.
Demande
Par exemple :
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey
Étant donné qu'un utilisateur n'a pas besoin d'être authentifié pour récupérer les informations concernant les étagères 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 renvoie le code d'état HTTP 200 OK et la ressource étagère:
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 étagère publique spécifique.
Récupérer une liste de volumes sur une étagère publique
Vous pouvez récupérer la liste des volumes d'une étagère publique d'un utilisateur en envoyant une requête HTTP GET à l'URI au format suivant:
https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes
Demande
Par exemple :
GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey
Remplacez les paramètres de chemin userId et bookshelf par les ID spécifiant l'utilisateur et l'étagère que vous souhaitez récupérer. Pour en savoir plus, consultez la section ID Google Livres.
Étant donné qu'un utilisateur n'a pas besoin d'être authentifié pour récupérer les informations concernant les étagères 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 renvoie un code d'état HTTP 200 OK et la liste des étagères 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
Outre les 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 étagère publique.
Pagination
Vous pouvez paginer la liste des volumes en spécifiant deux valeurs dans les paramètres de la requête:
startIndex: position à laquelle la collection doit commencer. L'index 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 des étagères dans "Ma bibliothèque"
Toutes les requêtes "Ma bibliothèque" s'appliquent aux données des utilisateurs authentifiés.
Récupération d'une liste de mes étagères
Vous pouvez récupérer la liste de toutes les étagères des utilisateurs authentifiés en envoyant une requête HTTP GET à l'URI au format suivant:
https://www.googleapis.com/books/v1/mylibrary/bookshelves
Demande
Par 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 une liste de 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 étagères de l'utilisateur actuellement authentifié:
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 étagères des utilisateurs authentifiés.
Récupérer une liste de volumes sur mon étagère
Vous pouvez récupérer la liste des volumes sur l'étagère des utilisateurs authentifiés 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 étagère par l'ID de l'étagère. Consultez la section ID Google Livres pour en savoir plus sur les ID d'étagère.
Demande
Par 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 une liste de volumes "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 des volumes étagère:
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
Outre les 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 étagères des utilisateurs authentifiés.
Pagination
Vous pouvez paginer la liste des volumes en spécifiant deux valeurs dans les paramètres de la requête:
startIndex: position à laquelle la collection doit commencer. L'index du premier élément est 0.maxResults: nombre maximal de résultats à renvoyer. La valeur par défaut est 10.
Ajouter un volume à mon étagère
Pour ajouter un volume à l'étagère des utilisateurs authentifiés, 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 étagère par l'ID de l'étagère. Consultez la section ID Google Livres pour en savoir plus sur les ID d'étagère.
La requête comporte un seul paramètre de requête obligatoire:
volumeId: ID du volume. Consultez la section ID Google Livres pour en savoir plus sur les ID de volume.
Demande
Voici un exemple d'ajout de "Fleurs pour 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 étagère. Vous devez donc fournir l'en-tête HTTP Authorization avec la requête POST. Toutefois, aucune donnée n'est requise avec ce POST.
Réponse
Si la requête aboutit, le serveur renvoie 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 étagères des utilisateurs authentifiés.
Supprimer un volume de mon étagère
Pour supprimer un volume de l'étagère des utilisateurs authentifiés, 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 étagère par l'ID de l'étagère. Consultez la section ID Google Livres pour en savoir plus sur les ID d'étagère.
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 Livres.
Demande
Voici un exemple pour supprimer le terme "Fleurs pour Algernon" de l'étagère "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
Remarque: L'utilisateur doit être authentifié pour apporter des modifications à une étagère. Vous devez donc fournir l'en-tête HTTP Authorization avec la requête POST. Toutefois, aucune donnée n'est requise avec ce POST.
Réponse
Si la requête aboutit, le serveur renvoie 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 étagères des utilisateurs authentifiés.
Effacer tous les volumes de mon étagère
Pour supprimer tous les volumes de l'étagère des utilisateurs authentifiés, envoyez un POST HTTP à l'URI au format suivant:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes
Remplacez le paramètre de chemin étagère par l'ID de l'étagère. Consultez la section ID Google Livres pour en savoir plus sur les ID d'étagère.
Demande
Voici un exemple pour effacer 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
Remarque: L'utilisateur doit être authentifié pour apporter des modifications à une étagère. Vous devez donc fournir l'en-tête HTTP Authorization avec la requête POST. Toutefois, aucune donnée n'est requise avec ce POST.
Réponse
Si la requête aboutit, le serveur renvoie 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 effacez tous les volumes de l'une des étagères des utilisateurs authentifiés.
Documentation de référence sur les paramètres de requête
Cette section présente les paramètres de requête que vous pouvez utiliser avec l'API Livres.Toutes les valeurs des paramètres 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 Livres sont indiqués sur la page Paramètres système.
Paramètres de requête spécifiques à l'API
Le tableau suivant récapitule les paramètres de requête qui ne s'appliquent qu'à des opérations spécifiques dans l'API Livres.
| Paramètre | Signification | Remarques | Applicabilité |
|---|---|---|---|
download |
Limiter les volumes à la disponibilité des téléchargements |
|
|
filter |
Filtrez les résultats de recherche par type de volume et disponibilité. |
|
|
langRestrict |
Limite les volumes renvoyés à ceux qui comportent la balise spécifiée. |
|
|
maxResults |
Nombre maximal d'éléments à renvoyer avec cette requête. |
|
|
orderBy |
Ordre des résultats de recherche de volume. |
|
|
printType |
Restreindre aux livres ou aux magazines |
|
|
projection |
Limiter les informations de volume renvoyées à un sous-ensemble de champs. |
|
|
q |
Chaîne de requête en texte intégral. |
|
|
startIndex |
Position dans la collection à laquelle commencer la liste des résultats. |
|
|
volumeId |
Identifie le volume associé à la requête. |
|