Application Programmers' Interface (API)Introduction | Technical Manual | Code Lists | Sample Output | XML DTD | Version Changes
The API is a machine-to-machine interface that lets third party applications run a wide variety of queries against the OpenDOAR Database and get back XML data. You can choose to receive just repository titles & URLs (suitable for OAI-PMH harvesting), or all the available OpenDOAR data, or intermediate levels of detail. You can then incorporate the output into your own applications and 'mash-ups'.
There are many uses to which the API can be put - either to re-purpose the data, or to use it to control operations such as OAI-PMH harvesting. The three experimental applications listed below give a flavour of the sort of things that can be done. They were initially created by external collaborators when the API was at the prototype stage, and are listed with their permission.
Stuart Lewis's Repository66 Mash-up
Other possibilities that come to mind include: displaying a list of repositories for a given country (perhaps in association with an OpenDOAR Chart); gathering a collection of OAI Base URLs for repositories containing material in a given language, which can then be harvested for a specialist search service; and compiling data for statistical purposes.
OpenDOAR API output data is licenced for re-use under a Creative Commons Attribution-Non-Commercial-Share Alike licence. See http://creativecommons.org/licenses/by-nc-sa/2.0/uk/ for further details.
The API works by client programs making HTTP get requests to the API at http://opendoar.org/api.php, with the URL's arguments indicating the required query criteria and output format. The results are returned as an XML stream.
Queries can search all the fields that the interactive OpenDOAR Find facility can search - Keywords, Country/Continent, Language, Subject Area, and Content Type. Keywords can search all the text fields, or specific families of fields such as URLs, Software Names & Versions, etc. There are additional fields that currently only the API can search - OpenDOAR Record ID, Policy Grade, OpenDOAR Record Update Date, and presence/absence of an OAI Base URL. Furthermore, the API has extra functionality that Find does not have. You can search for lists of countries, languages, subjects, etc., and there is some Boolean logic.
Output options are flexible, ranging from a minimal list of titles and URLs to all the available OpenDOAR data. In between, the OpenDOAR fields can be specified in groups - Basic information, Index terms, Contact details, and Policy data. The default Basic format is a collection of the most popular fields.
Find repositories in France, Canada, Belgium or Switzerland in the French language. Returns repository names & URLs sorted by country & repository name.
Find repositories containing the strings 'geo' or 'earth' or with the subject code for 'earth and planetary sciences'. By default, returns summary records sorted by repository name.
Show all available OpenDOAR data for the CCLRC ePublication Archive.
Full instructions on how to use the API are available in two formats:
- A Web-based version (http://www.opendoar.org/tools/api13.html)
- A printable PDF version (http://www.opendoar.org/tools/OpenDOARapi13.pdf)
Both versions include lists of the codes required for certain fields, annotated sample output, and the XML Document Type Definition (DTD).
The API is now an officially supported OpenDOAR service. As the interactive version of OpenDOAR continues to develop, any changes will also be reflected in the API. However, we believe that the XML field tags are stable and will not be re-named. On the other hand, we may add new fields to the schema (e.g latitude & longitude). We will also continue to improve the API, for instance with enhanced error trapping.
API version numbers have major and minor components rendered in a decimal format - e.g. Version 1.3. The major component indicates significant functional changes in the way the API works that possibly may not be backwardly compatible. The minor component mainly reflects additions to the XML output schema that are unlikely to affect existing applications adversely. Old versions will continue to be supported for a period after any upgrade. If you need to use an older version, it will be possible to do so by including the version number in the URL - e.g. http://www.opendoar.org/api11.php for version 1.1.
Feedback & Support
Please send feedback and requests for support to Peter Millington (firstname.lastname@example.org).