Recherchez des livres sur Goodreads. Envoyez un mot-clé comme dune ou pride and prejudice, et une page facultative. La réponse est { results, pagination }. Chaque carte a un id numérique. Passez-le à /v2/goodreads/book. Pour Dune, l'id est 44767458.
Les comptes d'une carte peuvent être abrégés. 1.7 million ratings devient 1700000. L'endpoint livre renvoie le compte exact de la page livre.
GET https://api.piloterr.com/v2/goodreads/search?query=dune
GET https://api.piloterr.com/v2/goodreads/search?query=dune&page=2
GET https://api.piloterr.com/v2/goodreads/search?query=https://www.goodreads.com/search?q=dune&page=2
GET et POST prennent les mêmes paramètres. La page 1 de dune contient 44767458 / Dune de Frank Herbert. pagination.next vaut https://www.goodreads.com/search?q=dune&page=2. La page 2 utilise cette URL, annonce pagination.page 2, et ses ids ne répètent pas la page 1. Son next est l'URL Goodreads de la page 3.
| Paramètre |
Obligatoire |
Exemple |
query |
oui |
dune |
page |
non |
2 |
query est obligatoire. Une URL Goodreads doit être une recherche. Un autre hôte renvoie 400. page est facultatif, défaut 1, entier supérieur ou égal à 1. Si vous envoyez une URL de recherche et page, page remplace la page de l'URL.
pagination.page est la page imprimée par Goodreads (Page N of M) ou, à défaut, la valeur page de l'URL. pagination.total_pages est ce M, par exemple 100 pour dune. pagination.total_results vaut null. pagination.per_page est le nombre de cartes, 20 sur une page dune pleine.
pagination.next est l'URL Goodreads du lien Next, par exemple https://www.goodreads.com/search?q=dune&page=2. Il vaut null seulement sur la dernière page, quand le lien est absent. Suivez next, ou renvoyez le mot-clé avec page incrémenté. Les ids sont uniques sur une page et ne reviennent pas sur la page suivante.
| Champ |
Type |
Sens |
results[].id |
string |
Id numérique, par exemple 44767458 |
results[].title |
string |
Titre |
results[].url |
string |
https://www.goodreads.com/book/show/{id} |
results[].series |
string ou null |
Série sur la carte, par exemple Dune (Series #1) |
results[].authors |
array |
Auteurs |
results[].rating |
number ou null |
Note moyenne |
results[].ratings_count |
number ou null |
Notes. Un libellé abrégé prend le plancher affiché : 1.7 million devient 1700000 |
results[].reviews_count |
number ou null |
Critiques, même règle d'abréviation |
results[].image |
string ou null |
Couverture |
pagination.page |
integer |
Page courante |
pagination.per_page |
integer ou null |
Cartes de la page |
pagination.total_results |
null |
Non affiché |
pagination.total_pages |
integer ou null |
Nombre de pages imprimé |
pagination.next |
string ou null |
URL Goodreads suivante |
La fiche de 44767458 reprend le même id et le même titre. Le libellé de série peut différer (Dune #1 sur la fiche, Dune (Series #1) sur la carte) parce que les deux pages n'impriment pas la même chaîne.
- Résoudre le titre Dune vers l'id
44767458 avant de lire l'ISBN, le nombre de pages et le total exact de notes.
- Suivre
pagination.next pour dune et collecter les auteurs sans répéter les ids de la page 1.
- Comparer les notes abrégées de
pride and prejudice en page 1, puis ouvrir la fiche pour le compte exact.
| Code |
Sens |
400 |
Requête vide, page inférieure à 1, ou domaine hors goodreads.com |
401 |
Clé API absente |
404 |
La page n'est pas une recherche de livres |
500 |
Échec de la récupération |
Goodreads Book
