Télécharger la description au format OpenApi JSON ou YAML

API Mir@bel

Web-service REST pour interroger Mir@bel.

Données sous Licence Ouverte, compatible ODC-BY et CC-BY 2.0. Réutilisation possible des données à condition d'en mentionner l'origine.

Les versions futures de cette API resteront compatibles avec les versions 1.* précédentes. Donc une requête pour la version actuelle de l'API restera valable dans le futur, avec une réponse éventuellement enrichie de champs supplémentaires.

  • v1.4.0 (sept 2023) Critère de recherche par grappe pour /titres.
  • v1.3.0 (juin 2023) Ajout de Titre.labellisation, Titre.sigle et Acces.ressourcesigle. Ajout de /themes, /theme/revue/{id}, /theme/titre/{id}. Critère de recherche par thème pour /titres. Correction d'un bug sur /mes/acces/changes
  • v1.2.1 (fév 2023) Les chemins /editeurs/{id} /revues/{id} et /titres/{id} gèrent les redirections
  • v1.2.0 (juin 2022) Ajout d'informations sur les éditeurs, par une extension des données du modèle Titre et la création de points d'entrée /editeurs. Le champ Titre.editeurs ne liste plus que les éditeurs actuels.
  • v1.1.6 (fév 2022) La documentation nommait "datebarriereinfo" un champ disponible sous le nom "dateinfo".
  • v1.1.5 (nov 2020) Corrige un bug sur /acces concernant les abonnements par collections.
  • v1.1.4 (sept 2020) Les critères "lacunaire" et "selection" sont booléens. Le texte recherché doit contenir 3 caractères au minimum.
  • v1.1.3 (juil 2020) Ajout de l'identifiant "bnfark". Autorise /titres et /mes/titres sans filtre. Les ISSN de titre étaient absents des titres de /revues. Corrections mineures.
  • v1.1.2 (nov 2019) Ajout de Acces.url_proxy quand pertinent. Acces.url pointe sur sa ressource à défaut d'URL spécifique. Ajout de Acces.lacunaire et Acces.selection.
  • v1.1.0 (nov 2019) Remplacement du critère lien=possession par possession=1. Ajout du critère abonnement=1. Ajout de nombreux champs dans les données renvoyées.
  • v1.0.0 (mai 2019) Première version publique.
Version 1.3.0

Licence des données

Licence ouverte : https://www.etalab.gouv.fr/licence-ouverte-open-licence

Format des réponses

Les réponses de l'API sont au format JSON.

Liste des chemins

Détail des actions

/acces/revue

GET /acces/revue

Titre
Liste des accès sur une revue
Description

Liste tous les accès sur une revue (qui peut regrouper plusieurs titres si l'historique de la revue est complexe).

La revue est identifiée par son ID dans Mir@bel, ou un ISSN, un numéro OCLC de Worldcat, etc. Au moins un critère est nécessaire. Les critères sont combinés par un ET logique (les revues valident tous les critères).

Par exemple, /acces/revue?issn=1169-1018 montrera les accès en ligne pour la revue "Population (english edition)" dont l'ancien titre a cet ISSN.

URL
GET /acces/revue
Paramètres
Nom Description Lieu Requis ? Type, format
issn

Numéro ISSN (ou ISSN-e) de la forme XXXX-XXXX

queryNonstring
partenaire

Clé privée du partenaire.

Si ce paramètre est fourni, les accès en ligne pourront avoir une diffusion "abonné" au lieu de "restreint".

queryNonstring
revueid

Identifiant numérique de la revue dans Mir@bel.

queryNoninteger
sudoc

Identifiant PPN de SUDOC.

queryNonstring
worldcat

Identifiant numérique de Worldcat.

queryNoninteger
Réponses
Code HTTP Description Schema
200

liste d'accès

[ → Acces ]
default

Erreur

Erreur

/acces/titres

GET /acces/titres

Titre
Liste des accès sur une sélection de titres
Description

Liste tous les accès sur des titres de revue (qui peuvent différer de la revue s'il y a un historique de titres).

Chaque titre est identifié par son ID dans Mir@bel, ou un ISSN, un numéro OCLC de Worldcat, etc. Au moins un critère est nécessaire. Les critères sont combinés par un ET logique (les titres valident tous les critères).

Par exemple, /acces/titres?issn=1169-1018 montrera les accès en ligne pour le titre "Population (english selection)" qui a cet ISSN.

Les critères de recherche sont les mêmes que pour /titres.

URL
GET /acces/titres
Paramètres
Nom Description Lieu Requis ? Type, format
actif

Restreindre aux titres actifs. Autrement dit, exclure les anciens titres des revues, ceux qui ont des successeurs.

queryNonboolean
id

Identifiant numérique du titre dans Mir@bel. Il est aussi possible de donner une liste de nombres séparés par des virgules, par exemple id=14,72,1044 pour sélectionner les accès de ces trois titres.

queryNoninteger
issn

Numéro ISSN (ou ISSN-e ou ISSN-l) de la forme XXXX-XXXX. Une liste d'ISSN est possible, par exemple issn=1660-7880,1776-8098.

queryNonstring
partenaire

Clé privée du partenaire.

Si ce paramètre est fourni, les accès en ligne pourront avoir une diffusion "abonné" au lieu de "restreint". Il doit aussi être donné pour utiliser les critères "possession" et "abonnement".

queryNonstring
abonnement

Restreint la liste aux titres auxquels le partenaire est abonné, via une collection ou une ressource.

Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
possession

Si possession=1, seuls les titres possédés par le partenaire seront concernés.

Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
revueid

Identifiant numérique de la revue dans Mir@bel, ou liste avec des virgules comme séparateurs.

Si ce critère est présent, les titres seront ordonnés du plus récent au plus ancien, pour rendre l'historique de titre de la revue plus lisible.

queryNoninteger
sudoc

Identifiant PPN de SUDOC.

queryNonstring
titre

Titre. Le préfixe sera ignoré ("Monde" ou "Le Monde" donne le même résultat). Une recherche en début ("Monde%") ou milieu de titre ("%monde%") est possible. Une recherche exacte portera aussi sur le sigle des titres (par exemple, "titre=AJDA").

queryNonstring
worldcat

Identifiant numérique OCN de Worldcat, ou liste d'identifiants joints par des virgules.

queryNoninteger
Réponses
Code HTTP Description Schema
200

liste d'accès

[ → Acces ]
default

Erreur

Erreur

/editeurs/{id}

GET /editeurs/{id}

Titre
Détail d'un éditeur identifié par son ID Mir@bel
Description

Les infos que Mir@bel fournit sur un éditeur identifié par son ID dans Mir@bel ou par son IdRef.

Par exemple, /editeurs/64 pour décrire l'éditeur qui a l'identifiant 64 dans Mir@bel.

URL
GET /editeurs/{id}
Paramètres
Nom Description Lieu Requis ? Type, format
id

Identifiant numérique de l'éditeur (ID interne à Mir@bel).

pathOuistring
Réponses
Code HTTP Description Schema
200

Détail d'un éditeur

{
editeur: ,
relations_titres:
[ → EditeurTitre ]
}
301

Redirection

Redirection
default

Erreur

Erreur

/editeurs/idref/{idref}

GET /editeurs/idref/{idref}

Titre
Détail d'un éditeur cherché par son IdRef
Description

Par exemple, /editeurs/idref/029524989.

URL
GET /editeurs/idref/{idref}
Paramètres
Nom Description Lieu Requis ? Type, format
idref

Identifiant IdRef de l'éditeur, de type PPN (8 chiffres suivis d'un chiffre ou de "X").

pathOuistring
Réponses
Code HTTP Description Schema
200

Détail d'un éditeur

{
editeur: ,
relations_titres:
[ → EditeurTitre ]
}
default

Erreur

Erreur

/revues/{id}

GET /revues/{id}

Titre
Détail d'une revue
Description

Pour éviter une requête supplémentaire, l'historique des titres de la revue est aussi fourni, en commençant par le plus récent.

Par exemple, /revues/3221 montrera les dates de dernière modification et de vérification de la revue, ainsi que son historique de titres. Le premier titre est le titre actif.

URL
GET /revues/{id}
Paramètres
Nom Description Lieu Requis ? Type, format
id

Identifiant numérique de la revue.

pathOuiinteger
Réponses
Code HTTP Description Schema
200

Détail d'une revue et de ses titres

{
revue:
Revue
}
301

Redirection

Redirection
default

Erreur

Erreur

/themes

GET /themes

Titre
Liste ordonnée de la thématique (taxonomie) utilisée par Mir@bel.
Description

Chaque élément de la liste renvoyée est un thème.

La liste est à plat alors que la structure est hiérarchique. Les champs "parentid" permettent de reconstruire l'arborescence.

La liste est triée selon l'ordre d'affichage, ce qui dépend d'abord de la position dans l'arbre, puis de l'ordre alphabétique des thèmes.

URL
GET /themes
Réponses
Code HTTP Description Schema
200

liste de thèmes

[ → Theme ]

 Essayer cette action

/themes/revue/{id}

GET /themes/revue/{id}

Titre
Liste ordonnée des thèmes attribués à cette revue.
Description

Chaque élément de la liste renvoyée est un thème. Par exemple, /themes/revue/88 produit la liste des thèmes de la revue d'identifiant 88.

Attention, dans Mir@bel, les thèmes sont associés à la revue, c'est-à-dire l'ensemble de ses titres.

URL
GET /themes/revue/{id}
Paramètres
Nom Description Lieu Requis ? Type, format
id

Identifiant numérique de la revue.

pathOuiinteger
Réponses
Code HTTP Description Schema
200

liste des thèmes de la revue

[ → Theme ]

/themes/titre/{id}

GET /themes/titre/{id}

Titre
Liste ordonnée des thèmes attribués à un titre.
Description

La réponse est identique celle de la revue du titre désigné. Cette action permet simplement d'éviter une requête pour remonter de l'identifiant d'un titre à celui de sa revue.

URL
GET /themes/titre/{id}
Paramètres
Nom Description Lieu Requis ? Type, format
id

Identifiant numérique du titre.

pathOuiinteger
Réponses
Code HTTP Description Schema
200

liste des thèmes de la revue de ce titre

[ → Theme ]

/titres/{id}

GET /titres/{id}

Titre
Détail d'un titre
Description

Les infos que Mir@bel fournit sur un titre par son ID dans Mir@bel.

Par exemple, /titres/14 pour trouver le titre qui a l'identifiant 14 dans Mir@bel.

URL
GET /titres/{id}
Paramètres
Nom Description Lieu Requis ? Type, format
id

Identifiant numérique du titre.

pathOuiinteger
Réponses
Code HTTP Description Schema
200

Détail d'un titre

Titre
301

Redirection

Redirection
default

Erreur

Erreur

/titres

GET /titres

Titre
Liste de titres recherchés par différents critères
Description

Liste les titres correspondant aux critères de recherche. Donner au moins un paramètre dans la requête pour sélectionner le titre.

Par exemple, /titres?issn=1660-7880 pour trouver le titre qui a l'ISSN 1660-7880, ou /titres?titre=%monde% pour lister les titres contenant "Monde", ou /titres pour l'ensemble des titres.

Les titres sont triés alphabétiquement, hors préfixes.

URL
GET /titres
Paramètres
Nom Description Lieu Requis ? Type, format
actif

Restreindre aux titres actifs.

Autrement dit, exclure les anciens titres des revues, ceux qui ont des successeurs.

queryNonboolean
grappeid

Identifiant numérique d'une grappe. Certaines grappes sont soumises à autorisation et ne seront accessibles que si le partenaire est authentifié.

queryNoninteger
id

Identifiant numérique du titre dans Mir@bel.

Il est aussi possible de donner une liste de nombres séparés par des virgules, par exemple id=14,72,1044 pour sélectionner ces trois titres.

queryNoninteger
issn

Numéro ISSN (ou ISSN-e ou ISSN-l) de la forme XXXX-XXXX.

Une liste d'ISSN est possible, par exemple issn=1660-7880,1776-8098.

queryNonstring
offset

Les réponses sont limitées à 1000 titres. Si cette limite est atteinte, ce paramètre permet de demander la suite avec offset=1000 etc.

queryNoninteger
revueid

Identifiant numérique de la revue dans Mir@bel, ou liste avec des virgules comme séparateurs.

Si ce critère est présent, les titres seront ordonnés du plus récent au plus ancien, pour rendre l'historique de titre de la revue plus lisible.

queryNoninteger
sudoc

Identifiant PPN de SUDOC.

queryNonstring
themeid

Identifiant numérique d'un thème. La thématique complète de Mir@bel, avec ces identifiants, est accessible par /themes.

queryNoninteger
titre

Titre. Le préfixe sera ignoré ("Monde" ou "Le Monde" donne le même résultat). Une recherche en début ("Monde%") ou milieu de titre ("%monde%") est possible. Une recherche exacte portera aussi sur le sigle des titres (par exemple, "titre=AJDA").

queryNonstring
worldcat

Identifiant numérique OCN de Worldcat, ou liste d'identifiants joints par des virgules.

queryNoninteger
Réponses
Code HTTP Description Schema
200

Liste de titres

[ → Titre ]
default

Erreur

Erreur

/mes/acces

GET /mes/acces

Titre
Pour un partenaire de Mir@bel, liste des accès sur ses revues
Description

Liste de tous les accès sur les revues du partenaire, sélectionnées par possession ou abonnement. Au moins l'un des deux critères ("abonnement" ou "possession") doit être présent.

L'accès est restreint aux partenaires de Mir@bel.

Exemple listant les accès en ligne sur les possessions et les abonnements /mes/acces?abonnement=1&possession=1&partenaire={HASH} (remplacer {HASH} par la clé privée du partnaire pour cette API).

URL
GET /mes/acces
Paramètres
Nom Description Lieu Requis ? Type, format
partenaire

Clé privée du partenaire

queryOuistring
abonnement

Restreint la liste aux titres auxquels le partenaire est abonné, via une collection ou une ressource.

Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
possession

Si possession=1 et abonnement=0, seuls les titres possédés par le partenaire seront concernés.

Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
Réponses
Code HTTP Description Schema
200

liste d'accès

[ → Acces ]

/mes/acces/changes

GET /mes/acces/changes

Titre
Pour un partenaire de Mir@bel, liste des modifications d'accès sur ses revues
Description

Liste les ajouts, modifications et suppressions concernant les accès des revues du partenaire, sélectionnées par possession ou abonnement (cf /mes/acces).

L'accès est restreint aux partenaires de Mir@bel.

URL
GET /mes/acces/changes
Paramètres
Nom Description Lieu Requis ? Type, format
partenaire

Clé privée du partenaire

queryOuistring
abonnement

Restreint la liste aux titres auxquels le partenaire est abonné, via une collection ou une ressource.

Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
depuis

Timestamp (en secondes) à partir duquel lister les changements.

Une date textuelle ("2019-01-20 12:30:00" ou "-1 week") est aussi possible, mais plus ambiguë.

queryOuistring
possession

Si possession=1, seuls les titres possédés par le partenaire seront concernés.

Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
Réponses
Code HTTP Description Schema
200

Objet décrivant les ajouts, modifications, suppressions

AccesChanges

/mes/titres

GET /mes/titres

Titre
Pour un partenaire de Mir@bel, liste des titres, par possession ou abonnement
Description

Liste des titres de revues possédées par un partenaire de Mir@bel, et décrites par leur dernier titre.

L'accès est restreint aux partenaires de Mir@bel.

URL
GET /mes/titres
Paramètres
Nom Description Lieu Requis ? Type, format
partenaire

Clé privée du partenaire

queryOuistring
abonnement

Restreint la liste aux titres auxquels le partenaire est abonné, via une collection ou une ressource.

Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
possession

Si possession=1, seuls les titres possédés par le partenaire seront concernés.

Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
ressourceid

Identifiant numérique d'une ressource de Mir@bel (par ex. 3 pour Cairn.info).

Filtre supplémentaire

queryNoninteger
Réponses
Code HTTP Description Schema
200

liste de titres

[ → Titre ]
default

Erreur

Erreur

Modèles de données

Acces

idinteger
Identifiant unique attribué par Mir@bel à cet accès en ligne.
contenustring
Parmi "Intégral", "Résumé", "Sommaire", "Indexation".
collections[ string ]
Nom des éventuelles collections concernées, dans la ressource de cet accès.
datedebutstring
Date (YYYY ou YYYY-mm ou YYYY-mm-dd) de début d'accès.
datefinstring
Éventuelle date (YYYY ou YYYY-mm ou YYYY-mm-dd) de fin d'accès.
dateinfostring
Description textuelle de la date barrière. Si cette donnée n'est pas fournie par la source de l'accès, elle est déduite du champ 'embargoinfo'. Exemple de valeur : "Accès avant une date barrière mobile de 3 années calendaires".
dernumurlstring
URL pointant sur le dernier numéro de la revue.
diffusionstring
Valeur parmi "libre", "restreint", "abonné". Cette dernière valeur n'est possible que si le paramètre "partenaire" est présent.
embargoinfostring
Le contenu du champ `embargo_info`, si l'accès a été créé par un import KBART.
identifiantpartenairestring
Si interrogation sur les possessions d'un partenaire, donne l'identifiant de possession.
issn[ string ]
La liste des ISSN des titres de cet accès en ligne. Champ présent seulement si la recherche se fait par ISSN.
lacunaireboolean
Si vrai, des numéros sont manquants sur la période, donc la couverture n'est pas exhaustive.
mailurlstring
URL de la revue par alerte courriel.
nodebutinteger
Null ou numérotation initiale, par exemple 6.
nofininteger
Null ou numérotation finale, par exemple 12.
numerodebutstring
Intitulé du numéro initial, par exemple "Vol. I, no 6".
numerofinstring
Intitulé du numéro final, par exemple "Vol. XXV, no 12 (HS)".
ressourcestring
Nom de la ressource fournissant cet accès.
ressourceidinteger
Identifiant unique attribué par Mir@bel à la ressource de cet accès.
ressourcesiglestring
Nom bref (sigle ou acronyme) de la ressource.
rssurlstring
URL du flux RSS de la revue.
selectionboolean
Si vrai, un numéro est représenté par une sélection d'articles, donc la couverture n'est pas exhaustive.
titreidinteger
référence à Titre.id
urlstring
URL de la revue.
urlproxystring
Si le partenaire est déclaré et que ses proxys sont actifs pour cet accès, alors ce champ contient l'URL avec application des proxys. Sinon, ce champ n'est pas présent.
voldebutinteger
Null, ou volume initial, par exemple 1.
volfininteger
Null, ou volume final, par exemple 25.

AccesChanges

Trois champs. creations et modifications sont des listes d'accès. Et suppressions est une liste des ID d'accès supprimés (non-limitée aux revues possédées).

creations[ → Acces ]
Liste des accès ajoutés.
modifications[ → Acces ]
suppressions[ integer ]
Identifiants (cf Acces.id) des accès supprimés.

Editeur

idinteger
Identifiant unique attribué par Mir@bel à cet éditeur.
identifiants[ string ]
Liste d'identifiants sous forme de couples [clé, valeur], par exemple `[["idref", "029524989"]]`.
liens[ string ]
Liste d'URL extérieures (Facebook, Twitter, etc) pour cet éditeur.
nomstring
Nom (sans son éventuel préfixe comme "L'").
paysstring
Codes ISO à 3 lettres du pays de l'éditeur.
prefixestring
Préfixe du nom de l'éditeur (par exemple "L'").
rolestring
Rôle général de l'éditeur pour ses titres.
urlstring
Site web de l'éditeur. URL publique, hors Mir@bel.
url_mirabelstring
Page web de cet éditeur sur le site de Mir@bel.

EditeurTitre

Les champs editeur* sont absents si la relation se rapporte à un éditeur connu. De même pour titre*.

editeurstring
Nom de l'éditeur (sans son éventuel préfixe comme "L'").
editeur_idinteger
Identifiant unique attribué par Mir@bel à cet éditeur.
precedentboolean
Il s'agit d'un éditeur précédent, qui n'intervient plus sur ce titre.
rolestring
Rôle de l'éditeur spécifiquement pour ce titre. Champ absent s'il n'y a pas de rôle spécifique.
titrestring
Titre (sans son éventuel préfixe comme "L'").
titre_idinteger
Identifiant unique attribué par Mir@bel à ce titre.

Issn

Attributs identifiant un titre ou une revue.

Cette structure contient généralement un ISSN, mais peut aussi ne donner que d'autres identifiants.

bnfarkstring
Identifiant Ark de la BNF.
issnstring
Ce champ sera absent si l'ISSN n'existe pas ou n'est pas connu, mais qu'un PPN (SUDOC) ou qu'un OCN (Worldcat) existe.
issnlstring
Éventuellemnt absent.
statutstring
Valeur parmi "en cours", "sans", "valide"
sudocnoholdingboolean
Si true, la notice du Sudoc n'est pas localisée.
sudocppnstring
Identifiant PPN du Sudoc.
supportstring
Valeur parmi "inconnu", "papier", "electronique"
worldcatocninteger
Identifiant OCN de Worldcat.

Revue

Une revue est un historique de titres.

idinteger
Identifiant unique attribué par Mir@bel à cette revue.
dermodifinteger
Timestamp (secondes) de la dernière modification de la revue (incluant titres et accès).
derverifinteger
Timestamp (secondes) de la dernière vérification des données de la revue (incluant titres et accès) dans Mir@bel.
titres[ → Titre ]
Historique des titres de la revue, triés du plus récent au plus ancient. Le premier est donc le titre actif.

Theme

Un thème est un élément de la thématique utilisée par Mir@bel.

idinteger
Identifiant unique attribué par Mir@bel. La racine a l'identifiant 1.
parentidinteger
Identifiant du thème parent. 0 pour la racine, strictement positif sinon.
nomstring
Nom du thème.

Titre

idinteger
Identifiant unique attribué par Mir@bel à ce titre.
bouquetpartenairestring
Ce champ est présent si le titre a été produit par une recherche sur les possessions, par exemple dans la requête /mes/titres. Il contient le bouquet déclaré par le partenaire pour ce titre dans ses possessions.
datedebutstring, date
Date de début de ce titre.
datefinstring, date
Éventellement, date de fin de ce titre.
editeurs[ string ]
Liste des noms d'éditeurs actuels. Voir `relations_editeurs` pour une liste plus détaillée.
identifiantpartenairestring
Ce champ est présent si le titre a été produit par une recherche sur les possessions, par exemple dans la requête /mes/titres. Il contient l'identification local au partenaire pour ce titre, telle que déclaré dans ses possessions.
issns[ → Issn ]
Liste des identifiants, notamment ISSN, attachés au titre.
labellisation[ string ]
Liste de textes parmi "DOAJ seal", "Catálogo 2.0 Latindex".
langues[ string ]
Liste des langues de ce titre, par leurs codes ISO à 3 lettres.
liens[ string ]
Liste d'URL extérieures (Facebook, Twitter, etc) pour ce titre.
obsoleteparinteger
Éventuel identifiant numérique du titre qui a remplacé celui-ci dans la revue.
periodicitestring
Périodicité.
prefixestring
Préfixe du titre (par exemple "L'").
relations_editeurs[ → EditeurTitre ]
Ce champ n'est présent que dans les requêtes cherchant un titre unique, autrement dit /titres/{id}.
revueidinteger
Identifiant unique attribué par Mir@bel à cette revue (historique de titres).
siglestring
Nom bref (sigle ou acronyme).
titrestring
Titre (sans son éventuel préfixe comme "L'").
urlstring
Site web de la revue. URL publique, hors Mir@bel.
url_revue_mirabelstring
Page web de la revue sur le site de Mir@bel.

Erreur

codeinteger, int32
Code HTTP de l'erreur
messagestring
Description détaillée du problème
fieldsstring
Éventuels champs créant un trouble dans la requête
details?
Éventuels détails sur l'erreur.

Redirection

codeinteger, int32
Code HTTP de la redirection (300 à 399)
nouvelidinteger, int32
identifiant de l'objet après redirection
urlstring
url de l'objet après redirection