API SRU Catalogue général

Présentation

Le service SRU (Search/Retrieve via URL) du Catalogue général permet d’interroger le Catalogue général de la BnF via de simples requêtes HTTP et de récupérer l’ensemble des notices du catalogue général (bibliographiques ou d'autorité) dans différents formats encapsulés dans du XML.

Il est accessible à tous sans authentification. Il est interrogeable manuellement depuis n’importe quel navigateur Internet ou intégrable dans du code informatique (web service RESTful ; protocole HTTP en mode GET ou POST).

Pour faciliter l'utilisation des critères et la construction des requêtes, un formulaire a été mis en place.

Le service SRU Catalogue répond à la norme 1.2 du protocole SRU disponible sur le site de la Bibliothèque du Congrès.

Console

Construction des requêtes

Ce service permet de récupérer toutes les notices bibliographiques et d’autorité du Catalogue général de la BnF en interrogeant celui-ci via un grand nombre de critères de recherche, comme par exemple :

• pour les notices bibliographiques : mots, auteur, titre, sujet, type de document, numéro de notice, ARK, ISBN… ;
• pour les notices d’autorité : mots, forme retenue ou rejetée, type de notice, numéro de notice, ARK, ISNI…

Structure des requêtes et critères

Toutes les requêtes doivent débuter par : 

https://catalogue.bnf.fr/api/SRU?version=1.2&operation=searchRetrieve&query=

C’est dans le paramètre "query" (&query=...) que la requête s'exprime, grâce à des critères.

Pour accéder à la liste des critères disponibles : 

• page explicative (xml) ;
• tableau des critères (pdf) ;
• ou directement sur le formulaire de construction de requêtes.

Relations entre termes d'un critère

Pour chaque critère, on peut chercher 'tous les mots' (relation "all"), 'un des mots' (relation "any"), ou une 'expression exacte' (relation "adj").

Par exemple, pour chercher les notices bibliographiques contenant tous les mots "Julien" et "Gracq" (critère "bib.anywhere" avec relation "all"), il faut utiliser la requête suivante :

https://catalogue.bnf.fr/api/SRU?version=1.2&operation=searchRetrieve&query=bib.anywhere all "julien gracq"

Les critères de date permettent d'autres relations : supérieur à (>), supérieur ou égal à (>=), égal à (=), inférieur à (>), inférieur ou égal à (<=), entre (within).

Le détail des relations disponibles pour chaque critère est disponible dans le tableau des critères (pdf), ainsi que dans des menus déroulants sur le formulaire de construction de requêtes.

Combinaisons de critères

Il est possible de combiner plusieurs critères grâce aux opérateurs "and", "or" ou "not".

Par exemple, la requête : https://catalogue.bnf.fr/api/SRU?version=1.2&operation=searchRetrieve&query=(bib.author all "romain gary") and (bib.title all "la promesse de l'aube") not (bib.doctype any "g h v")

permet de retrouver tous les documents "La promesse de l'aube"de Romain Gary qui ne sont ni des enregistrements sonores, ni des images animées, ni des spectacles.

Classement des résultats 

Il est possible de paramétrer le classement des résultats au moment de lancer la requête :

• tri par auteurs, de façon croissante A..Z (en ajoutant à la requête "sortBy Aut/sort.ascending") ou décroissante Z..A ("sortBy Aut/sort.descending")
• tri par titres, croissants A..Z ("sortBy Tit/sort.ascending") ou décroissants Z..A ("sortBy Tit/sort.descending")
• tri par dates, croissantes ("sortBy Dat/sort.ascending") ou décroissantes ("sortBy Dat/sort.descending").

Exemple : 

Sur le formulaire de construction de requête, ces tris sont accessibles via un menu déroulant "Tri", au pied du formulaire (sous le menu déroulant "Format en sortie").

Formats de sortie

Les notices peuvent être renvoyées en UNIMARC, en Intermarc ou en Dublin Core (uniquement pour les notices bibliographiques), encapsulé dans du XML (marcXchange 2.0 - ISO25577). L'encodage est l'UTF-8.

Le format par défaut est le format UNIMARC.

Il est possible de choisir parmi 5 schémas de sortie en utilisant le paramètre recordSchema dans la requête :

• UNIMARC (avec ou sans analytiques - sous-notices) / pour les notices bibliographiques et notices d'autorités :
  • unimarcXchange
  • unimarcXchange-anl
    (voir la notice exemple dans le Catalogue général)
• Intermarc (avec ou sans analytiques - sous-notices) / pour les notices bibliographiques et notices d'autorités :
  • intermarcXchange
  • intermarcXchange-anl
    (voir la notice exemple dans le Catalogue général)
• Dublin Core (uniquement pour les notices bibliographiques) :
  • dublincore

Réponses et résultats

Structure des réponses XML

Conformément à la norme SRU 1.2, la réponse à une requête est renvoyée par le serveur sous forme XML. Cette réponse comporte : 

• la version du SRU implémenté (1.2), dans <srw:version> ;
• le rappel de la requête effectuée, dans <srw:echoedSearchRetrieveRequest> ;
• le nombre de résultats, dans <srw:numberOfRecords> ;
• et l'ensemble des notices correspondant à la requête, encapsulées dans l'élément <srw:records>, chaque notice étant elle-même encapsulée dans un élément <srw:record>.

Les notices obtenues sont, selon le format de sortie demandé, soit directement en Dublin Core (nativement XML), soit en UNIMARC ou Intermarc encapsulés dans du marcXchange 2.0 (ISO25577). Le MarcXchange fournit, pour chaque notice, l'identifiant pérenne de la notice (ark), le format MARC utilisé (UNIMARC ou Intermarc), et le type de notice (bibliographic ou authority), puis chacune des zones MARC de la notice avec en attribut l'étiquette de la zone MARC.

Pour accéder à la documentation des format Intermarc, UNIMARC et Dublin Core, voir les rubriques dédiées en pied de page.

Pour plus d'information, consultez l'annexe de la documentation complète du service SRU (màj : 2019). Les développeurs y trouveront notamment comment récupérer ces éléments d'information au moyen de XPath (pp. 13-17).

Tri des résultats

Il est possible de paramétrer le classement des résultats tel qu'il s'affichera dans la réponse XML, en utilisant un tri au moment de lancer la requête :

• tri par auteurs, de façon croissante A..Z (en ajoutant à la requête "sortBy Aut/sort.ascending") ou décroissante Z..A ("sortBy Aut/sort.descending")
• tri par titres, croissants A..Z ("sortBy Tit/sort.ascending") ou décroissants Z..A ("sortBy Tit/sort.descending")
• tri par dates, croissantes ("sortBy Dat/sort.ascending") ou décroissantes ("sortBy Dat/sort.descending").

Exemple d'un tri par date croissante.

Sur le formulaire de construction de requête, ces tris sont accessibles via un menu déroulant "Tri", au pied du formulaire (sous le menu déroulant "Format en sortie").

Exploitation des pages de résultats

Pour parcourir l'ensemble des résultats et les récupérer 100 par 100 :

• Pour récupérer les 100 premières notices bibliographiques de l'Univers "Musique", de type "enregistrement sonore", la requête est : 
  https://catalogue.bnf.fr/api/SRU?version=1.2&operation=searchRetrieve&query=(bib.set any "music") and (bib.doctype any "g")&startRecord=1&maximumRecords=100
• Pour récupérer les 100 notices suivantes (on démarre à la 101ième et on demande les 100 suivantes) : 
  https://catalogue.bnf.fr/api/SRU?version=1.2&operation=searchRetrieve&query=(bib.set any "music") and (bib.doctype any "g")&startRecord=101&maximumRecords=100

Exemples de requêtes

Pour débuter dans l'utilisation du service SRU, il peut être utile de commencer à effectuer des recherches avancées sur le Catalogue général (notices bibliographiques et notices d'autorité), et de comparer les requêtes SRU possibles.

L'utilisation du formulaire de construction de requête permet d'élaborer et d'exécuter rapidement des requêtes.

Les exemples ci-dessous peuvent également permettre de mieux comprendre le fonctionnement du service.

Points de vigilance

• Contextes bib et aut : 
  Les recherches dans les contextes 'bibliographique' (préfixe "bib.") ou 'autorité' (préfixe "aut.") ne peuvent être combinées.
  Cependant, certains critères permettent directement des combinaisons (voir la catégorie "Notices liées" dans le tableau des critères), par exemple : bib.author2bib qui permet de renvoyer toutes les notices bibliographiques liées à une notice d'autorité en tant qu'auteur.
• Notion de notices d'autorité validées : 
  Par défaut, seules les notices d'autorité de référence sont interrogeables (notices 'validées' par la BnF). Le critère 'aut.status' doit être utilisé pour élargir à l'ensemble des notices d'autorité.
• Spectacles et autorités Dewey non converties en UNIMARC :
  Pour les notices de spectacle et les notices d'autorité Dewey, il n'est pas fourni de conversion en UNIMARC.
• Pour récupérer les données Gallica via le SRU :  
  En UNIMARC, les zones 856 donnent les liens ark vers les documents dans Gallica lorsqu'ils ont fait l'objet d'une numérisation (exemple dans BnF Catalogue général ou en SRU). Par contre, ces liens ne sont pas présents en Intermarc. Le critère bib.digitized permet de demander s'il existe une version numérisée à la BnF.

Documentation

L'ensemble de la documentation BnF associé à ce service est :

• Tableau des critères SRU [fichier .pdf – 308 Ko – 07/2026 – 7 p.]
• Petit manuel pour construire vos requêtes SRU avec beaucoup d'exemples [fichier .pdf – 337 Ko – 24/01/19 – 8 p.]
• Documentation complète du service SRU de la BnF [fichier .pdf – 349 Ko – 24/01/19 – 17 p.]

Voir également la page BnF expliquant les principes du protocole SRU et la norme SRU sur le site de la Bibliothèque du Congrès.