This guide is intended for people who want to find information on repositories and organisations, and who wish to determine if the UK RepositoryNet+ ORI "micro service" can help them to do so.
The guide explains the information available from the ORI, suggests how this might be used, and provides some simple examples of querying the ORI database. Full documentation on the APIs is available in the Technical Manual. The Frequently Asked Questions (FAQs) are provided to clarify the service and the terms under which it may be used.
ORI supports the development, for example, of deposit tools, which take account of organisational services. By providing a rich source of data based on organisation identification, the opportunities for developing products supporting inter-repository services are greatly enhanced.
An important characteristic of the ORI service is that it is a database of organisations which may have a list of repositories as an attribute, as opposed to a database of repositories which have organisations as one of their attributes.
ORI provides access for third parties to the functionality currently used for the identification of organisation and repository information by, for example, the OpenDepot.org client application.
Requests to calls supported by the main API presently provide access to information on circa 24,000 academic organisations and the 3,000 repositories located within those organisations.
The ORI is an edited union of several authoritative and extant data sources, stored in a PostgresSQL database. The sources currently gathered by ORI are:
The addition of further datasources is being considered for future releases of ORI.
Querying the ORI data can return the following data:
- Names and URLs for organisations (and repositories), including the date when URLs held in the database were last checked, and whether they were “alive”.
- Geolocations for organisations (and repositories).
- Network ranges for organisations.
- Descriptive details for repositories (descriptions, OAI base URLs, SWORD service documents etc.)
The results for repositories can be restricted by repository type(s) and/or accepted content type(s). Results are returned in a number of formats: JSON, XML and simple text.
For example the query: http://ori.edina.ac.uk/api?org=2464&format=text returns all the ORI data for the EDINA provided OpenDepot service in text format.
The ORI service is queried by an application using calls to three APIs:
primary contact point for calls to the ORI is
A SPARQL query interface to the data will be provided in a later release of the ORI, however a full dataset can be downloaded as RDF/XML or Turtle Linked Data.
In addition to the sample URL based calls illustrated in this section, there are a suite of simple demonstration clients for the ORI APIs (the main api, the get calls, and the list calls), a graphic visualisation, and a very simple client that displays ROAR usage charts for your organisation.
The main API is located at:
ori.edina.ac.uk/api. To make sample calls you add
various parameters to the end of the url.
?ip=aa.bb.cc.ddwill return what the system knows about based around that IP number
?org=1234will return what the system knows about the organisation with an org_id of 1234
?geo=lat,longwill return what the system knows about around that geo-location
?type=3will only include repositories that are of type 3
- See http://ori.edina.ac.uk/cgi-bin/list/type?format=xml for the available codes.
?content=11will only include repositories that accept contents of type 11
- See http://ori.edina.ac.uk/cgi-bin/list/content?format=xml for the available codes.
You can specify multiple items in each of the parameters:
- If you specify multiple items for ip, org or geo it will return a union of the items found e.g. all the orgs that are associated with any of the IP numbers given
- If you specify ips and/or orgs and/or geo, it will return the intersection of the items found (ie, all the items that are around the geo-location x,y and belong to something that owns that network range content & type are there to restrict the repositories returned.
The following simple calls provide a demonstration of calling this API.
Note that these sample calls return data in a new browser window.
- This call passes in values for the
formatparameters and returns a data object for the IP range 126.96.36.199/16 in XML format. In this case the call returns data on every organisation within this Class B network at the University of Edinburgh.
- This call uses the the org_id of 739 that was in the data returned from the previous query, to list all the information that ORI holds on this organisation.
- This call returns what data ORI holds within the geolocation bounded by Latitude 55.9 and Longitude -3.1
- Returns all data for organisations within the 188.8.131.52/16 Network having a repository of type 11, "Learning (Learning and Teaching Objects)".
- This call will return details of organisations within the 184.108.40.206/16 network that have a repository that accepts content of type 11, "Multimedia and audio-visual materials".
- This call returns the organisations in the networks 220.127.116.11/16 and 18.104.22.168/16 that have repositories which accept content of type 7, "Institutional (Institutional or departmental repositories)".
This is a suite of three APIs that are provided to support AJAX auto-completer requests.
All three calls take the same three parameters:
- q: a required field. The query term.
- field: The data field to search in. Defaults to name
What the options are for this field varies according to the get_xxx script:
- name - the name for the thing being searched. The search is case insensitive (eg
- id - the ORI id number for the thing (eg
- url - the url associated with thing being searched (eg
- ip - only available for get_nets, and is an IP number (eg
Names and urls may be partial ("edin" for example) and may be anchored: ^ to the start of the string, and $ for the end.
ips can be partial, and can be ranges For example
22.214.171.124 to 126.96.36.199
- name - the name for the thing being searched. The search is case insensitive (eg
- format: the format the data should be returned in. Defaults to json; but may be any of the following:
- prototype - a format specifically for the Prototype AJAX engine used in EPrints.
Note, if an additional callback parameter is included, the json return will be cross-platform complient.
These calls return data on organisations (get_orgs), repositories (get_repos) and networks (get_nets). The following examples provide a demonstration of calling each of these APIs.
Note that these sample calls return data in text format in a new browser window.
- Returns a data object in text format for all organisations that have the string "bangladesh" in their name field.
- Queries ORI for organisations whose URL contains the string "www.bau." The data object is returned in text format.
- Queries ORI for organisations that have the string "City of Glasgow" in their name filed and returns the IP ranges for these. Note that URL is encoded to prevent the spaces in the query string being misunderstood.
Returns the networks that start with "129.215". The
field=ipparameter must be passed in otherwise no matches are found.
The same query as in the previous example except that the use of the prototype returns
the data as an XHTML unordered list (as per the scriptalicious/prototype requirements),
for:attribute for each list item set to match EPrints field names.
- This query returns details of repositories that have the string "deposit" in their URL field.
nameis the default search field this query returns details of those repositories that have the string "archive server" in their name.
These calls return lists of the codes that can be used when making calls to the main API.
Note that these sample calls return data in XML format in a new browser window
- Returns the list of repository type numeric codes that can be used when making queries via the main API type method .
- This lists the numeric codes and type of content that repositories accept. Use the numeric content code when calling via the main API content method .
- Lists all the countries the dataset knows about: the ISO 3166-1 codes .
Lists all the languages the dataset knows about: the ISO 639 codes .
- The following calls all take several minutes to run & write the information to the browser window.
- Lists all the organisations within the database.
- Lists all the organisations within the database.
- Lists all the repositories within the database.
The ORI is a versatile resource as there are no proscribed limits on the use of the data returned, the only limitation being the developer resources that are available to organisations to create applications and services that make use of the data it can provide.
For this reason, ORI is particularly attractive to projects and organisations that are looking to enhance or to extend the functionality of the applications and services they provide or are developing.
Since ORI data provides a relationship between an organisation and its IP range(s) it can be used to implement or to improve access and authentication for services. For example:
- Authentication and authorisation services often require the user to select their identity provider from a list of several hundred institutions . Using calls to the ORI API this identity could be determined without the user having to make a selection.
Services in UK academic institutions providing staff and students with "Direct Access" to national services
often rely upon manual queries on local "lookup" files by staff, to match IP ranges to organisation IDs and
then grant "authenticated" access to the requested service.
This authentication could be made easier if the User Support staff were able to use a look-up service employing type-in forms to determine if the IP range provided matches the organisation reguesting it: the experience of service providers is that ~2% of requests are "invalid".
Although services such as the Registry of Open Access Repositories (ROAR) and the Directory of Open Access Repositories (OpenDOAR) provide a means of finding repositories they do have some limitations:
- It is difficult to list all the repositories at, for example, "The University of Edinburgh"
- Organisations without repositories do not exist, so one cannot say "There is no repository"
- Similarly it is not possible to ask "List all institutions without repositories".
Staff in organisations such as universities and research institutes produce and consume significant amounts of scholarly and research material. Locating specific types of content and where material can be deposited can be time consuming.
The ORI APIs support the creation of local HTML forms based applications with type-in completion fields to allow the easy selection of a suitable repository within a given locale.
ORI provides added value as it returns:
- Data on whether an organisation or repository is alive: the data is checked each week.
- Multiple names for objects: Kanagawa University Repository is actually called 神奈川大学学術機関リポジトリ by its local users.
Use of a mapping API together with ORI organisation data to produce online maps containing the location and details of organisations (like this) and repositories for a geographic domain. A mobile mapping version of the application could also be developed.
- What is ORI?
Organisation and Repository Idenitification (ORI) is an managed "micro service" providing access to an
edited union of several authoritative sources of data on organisations and repositories:
UKAMF, ROAR, OpenDOAR, Webometrics and WHOIS.
- How many organisation records does ORI contain?
- At present (Q3, 2012) ORI holds records on 24,000 organisations and over 3,000 repositories located within them.
- Who provides the ORI service?
- The service is provided as a "micro service" by the UKRepositoryNet+, a JISC initiative being developed by EDINA as a socio-technical infrastructure supporting deposit, curation and exposure of Open Access research literature.
- What can ORI be used for?
- See the Example Use Cases section earlier in this guide for some possible uses.
- How do I use ORI
- Although simple manual queries can be made using parameterised URLs from a web browser, access will usually be machine to machine via an application that is developed in-house or as added functionality for an existing application. Typically, the calling application will use an Ajax framework such as jQuery to request data from ORI and present the results to the user.
- Are there live examples of using the ORI service that I can study?
- The ORI technical manual provides some simple URL based calls to the main API and documents the syntax for these. Experienced application programmers will be able to develop applications on the basis of this information. In-house demonstration clients with code samples to call ORI and format the returned data are available for inspiration.
- What restrictions are there on the use of the ORI?
- There are no restrictions on access to the main API calls, so anyone may access the service over HTTP.
- What licences apply to the ORI data?
- All data in the ORI has been harvested from public sources, therefore use of the ORI data is unrestricted.
- Who do I contact if I need help or support?
- If you require support or further questions about the service that are not answered by this guide or the technical manual please use the UK RepositoryNet+ Helpdesk contact form or send email direct to: email@example.com. Doing so will raise a "ticket" in the helpdesk to ensure that the request is dealt with in a consistent manner.
- How does ORI gather information on organisations?
- Information is harvested from external sources using a set of scripts running on an automated schedule.
- What information does ORI hold on an organisation?
- Please see the section Data Returns of the technical manual for complete details of the data that ORI returns on organisations, repositories, networks and identities.
- Can I trust the organisation data held by ORI?
- The database is built from multiple online sources, so there may be inconsistencies. These errors would be present in any call to services such as ROAR or OpenDOAR. Extensive curation procedures both scripted and manual are undertaken on the data to ensure that errors in the data held are kept to an absolute minimum.
- How do I report any errors I find in the data?
- Please report any errors that you find using the use the UK RepositoryNet+ Helpdesk contact form or send email direct to: firstname.lastname@example.org. It would assist in correcting the data if you could include a copy of the returned data in the format that it was requested in e.g. JSON or XML.
- Who should I report bugs to?
- Bugs or other issues that you encounter when querying the ORI should be reported to the UK RepositoryNet+ Helpdesk who will forward the issue(s) on to the ORI development team for their attention.