Application Programmers' Interface (API)

Introduction  |  Technical Manual  |  Code Lists  |  Sample Output  |  XML DTD  |  Version Changes

Technical Manual

Basic Principles

The API works by client programs making HTTP get requests to http://opendoar.org/api.php or http://opendoar.org/api13.php, with the URL's arguments indicating the required query criteria and output format. The results are returned as an XML stream. The URL api13.php is specific to version 1.3 of the API. The URL api.php always uses the version that is current at runtime.

Licencing

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

Input Parameters

All URL parameter names are in lower case. Parameter values are case-insentitive.
Query Specification

1. all (optional) - Complete database. Only permitted value is 'all=y'.

2. rid (optional) - OpenDOAR Record Identifier. A comma-separated list of internal OpenDOAR ID numbers. (The rID argument in the <repository> XML tag).

3. co (optional) - Country/Continent. A list of ISO-3166 2-letter country codes or continent/Region names (see Appendix A) separated by commas. These will be searched using OR logic. See:
   http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html

4. la (optional) - Language. A list of ISO 2-letter language codes separated by commas. These will be searched using OR logic. See:
   http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

5. subject (optional) - Subject area codes. A list of OpenDOAR subject codes, separated by commas. Multiple codes are searched using OR logic. List in Appendix B.

6. rt (optional) - Repository type codes. A list of OpenDOAR numeric repository type codes separated by commas. These will be searched using OR logic. List in Appendix C.

7. ct (optional) - Content type codes. A list of OpenDOAR numeric content type codes separated by commas. These will be searched using OR logic. List in Appendix D.

8. pograde (optional) - Policy grade codes. A list of OpenDOAR numeric policy grade codes separated by commas. These will be searched using OR logic. List in Appendix E.

9. since (optional) - Update date. Inclusive date since which the record was added, updated or otherwise processed. Format: e.g. '2006-09-21'

10. before (optional) - Update date. Exclusive date before which the record was added, updated or otherwise processed. Format: e.g. '2003-01-31'

11. oai (optional) - OAI Base URL Availability.
    • y - OAI Base URL available in OpenDOAR
    • n - OAI Base URL absent from OpenDOAR
12. kwd (optional) - Keywords. A list of space-separated strings for searching one or more of the text fields - e.g. repository name, organisation name, software name, etc. Case insensitive.
    • Spaces and HTML special characters should be URL-encoded - e.g. &kwd=texas%20a%26m (for Texas A&M).
    • Accented Latin characters are acceptable - e.g. &kwd=québec.
    • Non-latin scripts should be encoded using UTF-8 - e.g.:
      • &kwd=京都大学 or &kwd=%E4%BA%AC%E9%83%BD%E5%A4%A7%E5%AD%A6 (for 京都大学 , Kyoto)
      • &kwd=Ψηφίδα or &kwd=%CE%A8%CE%B7%CF%86%CE%AF%CE%B4%CE%B1 (for Ψηφίδα, Psepheda).
13. multi (optional) - Qualifier for multi-string kwd parameters. This may have one of the following values:
    • phrase [default] - treats everything as a single string or phrase, which may appear anywhere in the relevant fields. Any spaces are significant.
    • begins - String must appear at the start of the relevant fields. Spaces are significant.
    • ends - String must appear at the end of the relevant fields. Spaces are significant.
    • all - All the words must appear in the relevant field(s) - in any order
    • any - One or more of the words must appear in the relevant field(s)
14. fields (optional) - Field family code. This indicates which group of fields is to be searched by the kwd parameter:
    • rname - Repository name, acronym or URL.
    • oname - Organisation name, acronym or URL - and Unit/Dept name, acronym or URL.
    • names - Repository name, Organisation name, Unit/Dept name, or their acronyms. (N.b. not URLs)
    • sw - Software name
    • url - Repository, OAI Base, Organisation, and Unit/Dept URLs.
    • all [default] - All the above (except 'url'), plus Description and Remarks
15. bool (optional) - Boolean logical operator. This may be used if two or more different query options have been specified:
    • and [default] - Both or all query items must be found.
    • or - At least one of the query items must be found.
    • [not - not to be implemented (yet).]

Output Options

15. show (optional) - Collections of fields to be output:
    • min - Minimum data - Repository name, acronym, preference, URL, and OAI Base URL. This is the minimum required for a list of repository titles, or for OAI harvesting.
    • basic [default] - as for min, plus Academic unit name, acronym, preference and URL, Organisation name, acronym, preference and URL, Postal Address, Country, Latitude and Longitude, Phone and Fax, Description, Remarks, Number of records and Date harvested for record count. These are generally the most popular fields.
    • index - as for min, plus lists of index terms and categories - i.e. Year established, Repository type, Operational status, Software name & version, Subject classes, Languages, Content types, and Policy grades.
    • contact - as for min, plus list of contacts - i.e. Personal name, Job title, Email address and Phone number.
    • policy - as for min, plus list of Policy grades, and Standardised policy statements.
    • max - Maximum data for all available fields.

    Multiple options can be specified, separated by commas. Where options overlap, fields are not duplicated in the output. See example output in Appendix F.

16. sort (optional) - Sort order. A list of field codes in the order required, separated by commas: rname [default], co, oname, or sw - i.e. Repository name, Country, Organisation name, or Software name.
17. header (optional) - XML header. Controls whether or not to display an XML header section echoing the query and providing statistics and error reports on the outcome:
    • y - Display a header.
    • n [default] - Suppress the header

Constraints

• At least one query option must be specified (points 1 to 11).
• Parameters cannot have null (empty) values.
• If either the 'multi' or 'fields' parameters is specified, the 'kwd' parameter must also be specified.
• 'multi' and 'bool' expect multiple words and/or query items. No error is reported if there is only one.

Outcome and Error handling

• If 'header=y' is specified, an XML header section will: echo the query, report the number of hits retrieved (which could be zero), give textual error reports if anything untoward happens
• If 'header=n' and either nothing is found, or an error occurs, an empty XML file will be returned. The application may therefore need to repeat the query with 'header=y' if the cause needs identifying.

Examples

• http://opendoar.org/api13.php?co=fr,ca,be,ch&la=fr&show=min&sort=co,rname
  Finds repositories in France, Canada, Belgium or Switzerland in the French language. Returns repository names & URLs sorted by country & repository name.
• http://opendoar.org/api13.php?kwd=geo%20earth&multi=any&subject=cam&bool=or
  Finds 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.
• http://opendoar.org/api13.php?kwd=CCLRC%20ePublication%20Archive&show=max
  Shows all available OpenDOAR data for the CCLRC ePublication Archived.

© 2006-2007, University of Nottingham, UK. Last updated: 02-Feb-2020