Vous êtes ici : Accueil › API

Présentation

Les API d'Isidore sont disponibles à l'URL api.rechercheisidore.fr 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 ressources contenant le terme « cnrs »

En xml : api.rechercheisidore.fr/resource/search?q=cnrs&replies=5
En json : api.rechercheisidore.fr/resource/search?q=cnrs&output=json&replies=5

Services

Nous proposons les 7 services suivants :

  1. api.rechercheisidore.fr/resource/search : pour effectuer des recherches sur les ressources

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

    Paramètres disponibles : q, output, page, replies, sort, language, facet, cluster
    Liste des filtres possibles : uri, url, author, date, lang, novelty, type, discipline, rameau, lcsh, bne, pactols, gemet, geoethno, geonames, country, after, before, source_tree, scope
    Liste des facettes disponibles : author, date, lang, novelty, type, discipline, rameau, lcsh, bne, pactols, gemet, geoethno, geonames, country, source_tree, scope

  2. api.rechercheisidore.fr/resource/suggest : pour obtenir des suggestions de recherche sur les ressources

    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. api.rechercheisidore.fr/resource/content : pour accéder au contenu détaillé d'une ressource

    Paramètre disponible : uri

  4. api.rechercheisidore.fr/source/search : pour effectuer des recherches sur les sources

    ex : les sources de type "Publication" en lien avec la musique

    Paramètres disponibles : q, output, page, replies, language, facet, cluster
    Liste des filtres possibles : scope, source_tree
    Liste des facettes disponibles : scope, source_tree

  5. api.rechercheisidore.fr/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, language, facet, cluster
    Liste des filtres possibles : referentiel
    Liste des facettes disponibles : referentiel

  6. api.rechercheisidore.fr/vocabulary/suggest : pour obtenir des suggestions de termes d'anotations sur les référentiels utilisés par Isidore

    ex : autocomplétion sur dix concepts commençant par "vedet"

    Paramètres disponibles : q, output, replies

  7. api.rechercheisidore.fr/sparql : pour interroger l'entrepôt RDF des ressources 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 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 : relevance (par pertinence), title (en fonction du titre), author (en fonction du nom des auteurs) ou date (en fonction de la date) le tri s'effectue par ordre croissant (ASC) ou décroissant (DESC) : author,ASC ou date,DESC;relevance,DESC ou etc.
language 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=lang,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 une ressource en fonction de son URI uri=10670/1.zkmwro
url retourne une ressource en fonction de son URL url=https://medihal.archives-ouvertes.fr/medihal-01329752
author filtre des ressources en fonction de l'id d'un auteur author=http://orcid.org/0000-0002-5780-7732 ORCID, IdHAL, ISNI, IdRef, VIAF ou nom_prenom (si pas d'identifiant auteur aligné)
date filtre des ressources en fonction de leur date de parution date=1900/1990 (les ressources de la décennie 1990) les valeurs des dates disponibles sont présentes dans l'attribut key de la facette date
lang filtre des ressources en fonction de leur langue lang=http://lexvo.org/id/iso639-3/ita (les ressources en italien) les valeurs des langues disponibles sont présentes dans l'attribut key de la facette lang
novelty filtre des ressources en fonction de leur nouveauté dans Isidore novelty=["2016-10-10"%20..%20"2017-01-10"[ (les ressources intégrées dans Isidore il y a moins de 3 mois) les valeurs des nouveautés disponibles sont présentes dans l'attribut key de la facette novelty
type filtre des ressources en fonction de leur typologie documentaire (articles, page web, photos et images...) type=http://www.rechercheisidore.fr/ontology#article (les ressources de type "articles") les valeurs des types disponibles sont présentes dans l'attribut key de la facette type
discipline filtre les ressources en fonction d'une discipline discipline=http://aurehal.archives-ouvertes.fr/subject/shs|http://aurehal.archives-ouvertes.fr/subject/shs.droit (les ressources en droit) les valeurs des disciplines disponibles sont présentes dans l'attribut key de la facette discipline
rameau filtre les ressources en fonction d'un concept issu du référentiel Rameau rameau=http://data.bnf.fr/ark:/12148/cb12009547n (les ressources enrichies par le concept "société" de Rameau)
lcsh filtre les ressources en fonction d'un concept issu du référentiel de LCSH lcsh=http://id.loc.gov/authorities/subjects/sh99001535 (les ressources enrichies par le concept "Constitution" de LCSH)
bne filtre les ressources en fonction d'un concept issu du référentiel de la BNE bne=http://datos.bne.es/resource/XX536152 (les ressources enrichies par le concept "Absentismo escolar" du référentiel BNE)
pactols filtre les ressources en fonction d'un concept issu du référentiel des Pactols pactols=http://ark.frantiq.fr/ark:/26678/pcrtQMIHuzxSAB (les ressources enrichies par le concept "accouchement" du référentiel Pactols)
gemet filtre les ressources en fonction d'un concept issu du référentiel Gemet gemet=http://www.eionet.europa.eu/gemet/concept/5708 (les ressources enrichies par le concept "accident nucléaire" du référentiel Gemet)
geoethno filtre les ressources en fonction d'un concept issu du référentiel Geoethno geoethno=http://GeoEthno#BETSIBOKA (les ressources enrichies par le concept "Betsiboka" du référentiel Geoethno)
geonames filtre les ressources en fonction d'un concept issu du référentiel Geonames geonames=http://sws.geonames.org/2507480/ (les ressources enrichies par la ville "Alger" du référentiel Geonames)
country filtre les ressources en fonction d'un pays country=http://sws.geonames.org/6255149/|http://sws.geonames.org/6251999/ (les ressources enrichies par le pays "Canada" du référentiel Geonames) les valeurs des pays disponibles sont présentes dans l'attribut key de la facette country
after filtre les ressources datées après une certaine date after=2009-05-12 (toutes les ressources datées après le 12 mai 2009)
before filtre les ressources datées avant une certaine date before=1870-04-01 (toutes les ressources datées avant le 1 avril 1870)
source_tree filtre les ressources en fonction d'une source ou d'une collection source_tree=10670/3.m1wx3t (les sources de la collection "Actualités des Écoles françaises et Instituts français à l'étranger")
source_tree=10670/3.m1wx3t|10670/2.1n5lcu (les ressources de la source "Portail des instituts français de recherche à l'étranger")
les valeurs des collections et sources disponibles sont présentes dans l'attribut key de la facette source_tree
scope filtre les ressources 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>