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".
We provide the following 8 services:
https://api.isidore.science/resource/search : to carry out research on resources
For example: theses in Linguistics about cartography:
Available parameters: q, output, page, replies, sort, lang, facet, cluster
List of possible filters: uri, url, author, authorId, date, language, type, discipline, subject, collection, scope
List of available facets: author, date, language, type, discipline, subject, collection, scope
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"
https://api.isidore.science/resource/content : to access the detailed content of a resource
Available parameter: uri
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
https://api.isidore.science/collection/suggest : to get research suggestions on collections
ex : autocompletion on collections containing the term "revue francaise"
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
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"
https://api.isidore.science/sparql : to query the RDF triple store of ISIDORE resources
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 : on resource : feed-creator or feed-subject and on vocabulary : bne, gemet, geoethno, lcsh, pactols or rameau | |
| 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 ISIDORE author id | author=minel_jean_luc | surname_firstname |
| authorId | filters resources according to an author id | authorId=orcid:0000-0001-6253-6722 | alignment with ORCID (orcid:), IdRef (idref:), ISNI (isni:) and IdHAL (idhal:) |
| 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 |
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>