Présentation de l'API

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 »

En xml : https://api.isidore.science/resource/search?q=cnrs&replies=5
En json : https://api.isidore.science/resource/search?q=cnrs&output=json&replies=5

Services

Nous proposons les 8 services suivants :

  1. https://api.isidore.science/resource/search : pour effectuer des recherches sur les documents

    ex : les thèses en linguistique concernant la cartographie :

    https://api.isidore.science/resource/search?q=cartographie&type=http://www.rechercheisidore.fr/ontology%23thesis&discipline=http://aurehal.archives-ouvertes.fr/subject/shs.langue

    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

  2. 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"

    Paramètres disponibles : q, output, replies, feed

  3. https://api.isidore.science/resource/content : pour accéder au contenu détaillé d'un document

    Paramètre disponible : uri

  4. 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

  5. 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"

    Paramètres disponibles : q, output, replies

  6. 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

  7. 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"

    Paramètres disponibles : q, output, replies

  8. https://api.isidore.science/sparql : pour interroger l'entrepôt RDF des documents ISIDORE

Requêtes

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

Schéma de réponse XML

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>