Presentation of the API

ISIDORE APIs are available at https://api.isidore.science through the GET method on HTTP or HTTPS. They provide a fast, accurate and reliable service for querying ISIDORE data with extensive search functionalities (autocompletion, spelling correction, multi-criteria, boolean and faceted searches, sorting, aggregation of responses, etc.).

Each request to the engine is submitted through a URI pointing to a specific web service. The response is a stream in XML (default format) or JSON format.

For example: full-text search on a maximum of 5 resources containing the term "cnrs".

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

Services

We provide the following 8 services:

  1. https://api.isidore.science/resource/search : to carry out research on resources

    For example: theses in Linguistics about cartography:

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

    Available parameters: q, output, page, replies, sort, lang, facet, cluster
    List of possible filters: uri, url, author, date, language, type, discipline, subject, collection, scope
    List of available facets: author, date, language, type, discipline, subject, collection, scope

  2. https://api.isidore.science/resource/suggest : to get research suggestions on resources

    For example: autocompletion on concepts and authors starting with "mar"

    For example: autocompletion on the first 15 authors starting with "wal"

    Available parameters: q, output, replies, feed

  3. https://api.isidore.science/resource/content : to access the detailed content of a resource

    Available parameter: uri

  4. https://api.isidore.science/collection/search : to carry out research on collections

    ex : For example: "Publication" type collections related to music

    Available parameters: q, output, page, replies, lang, facet, cluster
    List of possible filters: scope
    List of available facets: scope

  5. https://api.isidore.science/collection/suggest : to get research suggestions on collections

    ex : autocompletion on collections containing the term "revue francaise"

    Available parameters : q, output, replies

  6. https://api.isidore.science/vocabulary/search : to carry out research on the vocabularies used by ISIDORE for metadata enrichment

    For example: all concepts related to the web

    For example: concepts related to politics in Rameau or Pactols

    Available parameters: q, output, page, replies, lang, facet, cluster
    List of possible filters: referentiel
    List of available facets: referentiel

  7. https://api.isidore.science/vocabulary/suggest : to get suggestions of notation terms on the vocabularies used by ISIDORE

    For example: autocompletion on ten concepts starting with "vedet"

    Available parameters: q, output, replies

  8. https://api.isidore.science/sparql : to query the RDF triple store of ISIDORE resources

Queries

Queries to the ISIDORE API are built using the following parameters:

Name Description Values/Examples Notes
q query to be executed q=radicalisation
q=internet+SAUF+droit
possible to use operators AND | OR | NOT and quotation marks
output Output format possible values: xml (default) or json XML schemas are given at the page bottom
page pagination/shift page=3, to display results 21 to 30 if 10 documents per page
replies maximum number of results per page replies=25, to return 25 documents per page by default, the system returns 10 documents; 1000 documents at most per request
sort sorting results possible values: random, relevance (by relevance), novelty (by novelty), title_az|title_za (by title), author_az|author_za (by author name) or date_asc|date_desc (by date) sorting is done in ascending (_asc, _az) or descending (_desc, _za) order
lang Labels language in the response flow possible values: fr (French by default), en (English) or es (Spanish)
facet facet(s) to be returned facet=discipline (returns the discipline facet)
facet=author,replies=100,sort=items,order=DESC&facet=language,sort=alpha,order=ASC (returns the author facet [first 100 sorted from the author with the most occurrences] AND the language facet [sorted alphabetically]))
the list of available facets depends on the services (see above); the number of replies, sorting and order of a facet are managed by replies, sort and order
cluster filter on which you want to aggregate the results cluster=scope,5 (cluster of 5 replies on the perimeter of the sources) the results can only be aggregated by using one facet
feed selects an autocompletion base Possible values : feed-creator or feed-subject
uri returns a resource according to its URI uri=10670/1.zkmwro
url returns a resource according to its URL url=https://medihal.archives-ouvertes.fr/medihal-01329752
author filters resources according to an author id author=minel_jean_luc surname_first_name (the alignment with ORCID, IdRef, ... bases is in progress)
date filters resources according to their release date date=1990 (resources of the 1990s) the values of the available dates are present in the key attribute of the date facet
language filters resources according to their language language=http://lexvo.org/id/iso639-3/ita (resources in Italian) the values of the available languages are present in the key attribute of the language facet
type filters resources according to their documentary typology (articles, web page, photos and images...) type=http://isidore.science/ontology#article (resources of type "article") the values of the available types are present in the key attribute of the type facet
discipline filters resources by discipline discipline=http://aurehal.archives-ouvertes.fr/subject/shs.droit (resources in Law) the values of the available disciplines are present in the key attribute of the discipline facet
subject filters resources by subject subject=http://data.bnf.fr/ark:/12148/cb12009547n (resources enriched by "society" concept of Rameau)
collection filters resources according to a collection collection=10670/2.1n5lcu (the resources of the collection "Portail des instituts français de recherche à l'étranger") the values of the available collections are present in the key attribute of the collection facet
scope filters resources according to their documentary scope (source, event, publications, etc.) scope=http://isidore.science/subject/primaires the values of the available scopes are present in the key attribute of the scope facet
referentiel filters concepts according to the uri of a vocabulary used in ISIDORE: Rameau, LCSH, BNE, Gemet, Pactols, Geoethno and Geonames for example referentiel=http://pactols.frantiq.fr/ the list of vocabularies URIs can be found via this URL: facet=referentiel

XML Response Schema

The XML responses of the ISIDORE API are based on the following schemas:

search, complete schema

<response>
  <header>
    <query text="" userId="" sessionId="" date=""> <!-- query keyword -->
      <param name="" value=""/> <!-- list of query parameters -->
    </query>
    <performance durationMs=""/> <!-- response time in milliseconds -->
  </header>
  <replies>
    <meta items="" pageItems=""/> <!-- number of results and number returned per page -->
    <facets> <!-- list of facets -->
      <facet id="" type="" layout="">...</facet>
    </facets>
    <content> <!-- list of results -->
      <reply uri="">
        <isidore>...</isidore> <!-- result -->
      </reply>
      ...
    </content>
    <page previous="" current="" next=""/> <!-- pagination -->
  </replies>
</response>

suggest, complete schema

<response>
  <header>
    <query text=""/> <!-- keyword for suggestion -->
  </header>
  <replies name="" items=""> <!-- response feed and number returned -->
    <reply label=""/> <!-- result -->
    ...
  </replies>
  ...
</response>