Les API d'ISIDORE sont disponibles à l'URL https://api.isidore.science par la méthode GET sur HTTP ou HTTPS. Elles offrent un service de requêtage des données d'ISIDORE à la fois rapide, précis et fiable avec des fonctionnalités de recherche élaborées (autocomplétion, correction orthographique, recherches multicritères, booléenne et à facettes, tri, agrégation des réponses, ...)
Chaque requête au moteur est soumise au moyen d'une URI pointant vers un service web spécifique. La réponse est un flux au format XML (format par défaut) ou JSON.
ex : recherche plein texte sur au maximum 5 documents contenant le terme « cnrs »
Nous proposons les 8 services suivants :
https://api.isidore.science/resource/search : pour effectuer des recherches sur les documents
ex : les thèses en linguistique concernant la cartographie :
Paramètres disponibles : q, output, page, replies, sort, lang, facet, cluster
Liste des filtres possibles : uri, url, author, date, language, type, discipline, subject, collection, scope
Liste des facettes disponibles : author, date, language, type, discipline, subject, collection, scope
https://api.isidore.science/resource/suggest : pour obtenir des suggestions de recherche sur les documents
ex : autocomplétion sur les concepts et les auteurs commençant par "mar"
ex : autocomplétion sur les 15 premiers auteurs commençant par "wal"
https://api.isidore.science/resource/content : pour accéder au contenu détaillé d'un document
Paramètre disponible : uri
https://api.isidore.science/collection/search : pour effectuer des recherches sur les collections
ex : les collections de type "Publication" en lien avec la musique
Paramètres disponibles : q, output, page, replies, lang, facet, cluster
Liste des filtres possibles : scope
Liste des facettes disponibles : scope
https://api.isidore.science/collection/suggest : pour obtenir des suggestions de recherche sur les collections
ex : autocomplétion sur les collections contenant le terme "revue francaise"
https://api.isidore.science/vocabulary/search : pour rechercher sur les référentiels utilisés par ISIDORE pour l'enrichissement de métadonnées
ex : tous les concepts autour du web
ex : les concepts autour de la politique dans Rameau ou Pactols
Paramètres disponibles : q, output, page, replies, lang, facet, cluster
Liste des filtres possibles : referentiel
Liste des facettes disponibles : referentiel
https://api.isidore.science/vocabulary/suggest : pour obtenir des suggestions de termes d'anotations dans les référentiels utilisés par ISIDORE
ex : autocomplétion sur dix concepts commençant par "vedet"
https://api.isidore.science/sparql : pour interroger l'entrepôt RDF des documents ISIDORE
Les requêtes à l'API ISIDORE se construisent à l'aide des paramètres suivants :
| Nom | Description | Valeurs/Exemples | Notes |
|---|---|---|---|
| q | requête à effectuer | q=radicalisation q=internet+SAUF+droit |
possibilité d'utiliser les opérateurs ET | OU | SAUF | PROCHE et les guillemets |
| output | format de réponse | valeurs possibles : xml (par défaut) ou json | Les schémas XML sont donnés en fin de page |
| page | pagination/décalage | page=3, pour afficher les résultats 21 à 30 si 10 documents par page | |
| replies | nombre de résultats maximum par page | replies=25, pour remonter 25 documents par page | par défaut, le système remonte 10 documents ; 1000 documents au plus par requête |
| sort | tri des résultats | valeurs possibles : random (aléatoire), relevance (par pertinence), novelty (nouveauté), title_az|title_za (en fonction du titre), author_az|author_za (en fonction du nom des auteurs) ou date_asc|date_desc (en fonction de la date) | le tri s'effectue par ordre croissant (_asc, _az) ou décroissant (_desc, _za) |
| lang | langue des libellés dans le flux de réponse | valeurs possibles : fr (français par défaut), en (anglais) ou es (espagnol) | |
| facet | facette(s) à retourner | facet=discipline (retourne la facette discipline) facet=author,replies=100,sort=items,order=DESC&facet=language,sort=alpha,order=ASC (retourne le facette auteur [100 premiers triés en partant de l'auteur avec le plus d'occurrences] ET la facette langue [triée par ordre alphabétique]) |
la liste des facettes disponibles dépend des services (cf. supra) ; le nombre de retour, le tri et l'ordre d'une facette sont gérés par replies, sort et order |
| cluster | filtre sur lequel on souhaite agréger les résultats | cluster=scope,5 (cluster de 5 réponses sur le périmètre des sources) | on ne peut agréger les résultats que suivant une facette |
| feed | sélectionne une base d'autocomplétion | valeurs possibles : feed-creator ou feed-subject | |
| uri | retourne un document en fonction de son URI | uri=10670/1.zkmwro | |
| url | retourne un document en fonction de son URL | url=https://medihal.archives-ouvertes.fr/medihal-01329752 | |
| author | filtre des documents en fonction de l'id d'un auteur | author=minel_jean_luc | nom_prenom (l'alignement avec les bases ORCID, IdRef, ... est en cours) |
| date | filtre des documents en fonction de leur date de parution/publication | date=1990 (les documents de 1990) | les valeurs des dates disponibles sont présentes dans l'attribut key de la facette date |
| language | filtre des documents en fonction de leur langue | language=http://lexvo.org/id/iso639-3/ita (les documents en italien) | les valeurs des langues disponibles sont présentes dans l'attribut key de la facette language |
| type | filtre des documents en fonction de leur typologie documentaire (articles, page web, photos et images...) | type=http://www.rechercheisidore.fr/ontology#article (les documents de type "articles") | les valeurs des types disponibles sont présentes dans l'attribut key de la facette type |
| discipline | filtre les documents en fonction d'une discipline | discipline=http://aurehal.archives-ouvertes.fr/subject/shs.droit (les documents en droit) | les valeurs des disciplines disponibles sont présentes dans l'attribut key de la facette discipline |
| subject | filtre les documents en fonction d'un subject/concept d'un référentiel | subject=http://data.bnf.fr/ark:/12148/cb12009547n (les documents enrichies par le concept "société" de Rameau) | |
| collection | filtre les documents en fonction d'une collection | collection=10670/2.1n5lcu (les documents de la collection "Portail des instituts français de recherche à l'étranger") | les valeurs des collections disponibles sont présentes dans l'attribut key de la facette collection |
| scope | filtre les documents en fonction de leur périmètre documentaire (source de la recherche, données événementielles, publications, etc.) | scope=http://www.rechercheisidore.fr/subject/primaires | les valeurs des périmètres disponibles sont présentes dans l'attribut key de la facette scope |
| referentiel | filtre les concepts en fonction de l'uri d'un référentiel utilisé dans ISIDORE : Rameau, Lcsh, Bne, Gemet, Pactols, Geoethno et Geonames par exemple | referentiel=http://pactols.frantiq.fr/ | la liste des URI des référentiels peut être obtenue via cette URL : facet=referentiel |
Les retours XML de l'API ISIDORE suivent les schémas suivants :
search, schéma complet
<response>
<header>
<query text="" userId="" sessionId="" date=""> <!-- mot-clé de la requête -->
<param name="" value=""/> <!-- liste des paramètres de la requête -->
</query>
<performance durationMs=""/> <!-- temps de réponse en milliseconde -->
</header>
<replies>
<meta items="" pageItems=""/> <!-- nombre de résultats et nombre retourné par page -->
<facets> <!-- liste des facettes -->
<facet id="" type="" layout="">...</facet>
</facets>
<content> <!-- liste des résultats -->
<reply uri="">
<isidore>...</isidore> <!-- résultat -->
</reply>
...
</content>
<page previous="" current="" next=""/> <!-- pagination -->
</replies>
</response>suggest, schéma complet
<response>
<header>
<query text=""/> <!-- mot-clé pour suggestion -->
</header>
<replies name="" items=""> <!-- feed de réponse et nombre retourné -->
<reply label=""/> <!-- réponse -->
...
</replies>
...
</response>