Search the OAPEN Library using a REST API
Search syntax
You can search the OAPEN Library using a REST API, using the following syntax:
https://library.oapen.org/rest/search?query=[search query]
Examples:
- Full text query: “water AND fire” -
https://library.oapen.org/rest/search?query=%22water+AND+fire%22
- Query using dc.title: “The deliverance of open access books” -
https://library.oapen.org/rest/search?query=dc.title:%22the+deliverance+of+open+access+books%22
- Query using HANDLE: “20.500.12657/25287” -
https://library.oapen.org/rest/search?query=handle:%2220.500.12657/25287%22
List all available metadata
To list all available metadata, use:
https://library.oapen.org/rest/search?query=[search query]&expand=metadata
Examples:
- Full text query: “water AND fire” -
https://library.oapen.org/rest/search?query=%22water+AND+fire%22&expand=metadata
- Query using dc.title: “The deliverance of open access books” -
https://library.oapen.org/rest/search?query=dc.title:%22the+deliverance+of+open+access+books%22&expand=metadata
- Query using HANDLE: “20.500.12657/25287” -
https://library.oapen.org/rest/search?query=handle:%2220.500.12657/25287%22&expand=metadata
List all available bitstream objects
To list all available bitstream objects, use:
https://library.oapen.org/rest/search?query=[search query]&expand=bitstreams
Examples:
- Full text query: “water AND fire” -
https://library.oapen.org/rest/search?query=%22water+AND+fire%22&expand=bitstreams
- Query using dc.title: “The deliverance of open access books” -
https://library.oapen.org/rest/search?query=dc.title:%22the+deliverance+of+open+access+books%22&expand=bitstreams
- Query using HANDLE: “20.500.12657/25287” -
https://library.oapen.org/rest/search?query=handle:%2220.500.12657/25287%22&expand=bitstreams
List all available metadata and bitstream objects
To list both metadata and bitstream objects at once, use:
https://library.oapen.org/rest/search?query=[search query]&expand=metadata,bitstreams
Examples:
- Full text query: “water AND fire” -
https://library.oapen.org/rest/search?query=%22water+AND+fire%22&expand=metadata,bitstreams
- Query using dc.title: “The deliverance of open access books” -
https://library.oapen.org/rest/search?query=dc.title:%22the+deliverance+of+open+access+books%22&expand=metadata,bitstreams
- Query using HANDLE: “20.500.12657/25287” -
https://library.oapen.org/rest/search?query=handle:%2220.500.12657/25287%22&expand=metadata,bitstreams
Selecting fields for your query
To find out which metadata field to use:
- Select in the web UI an item that corresponds to a possible result of your query
- Open its full view, using one of these options: Click the “Show full item record” link under the thumbnail or append
?show=full
to the item’s URL - Select the metadata fields and their corresponding value.
For date fields, best to append the suffix “_dt” after the field’s name, e.g. dc.date.issued_dt
if you want the filter to behave as a date and not as text.
Examples:
- All titles, added in the last week. Query using dc.date.accessioned_dt -
https://library.oapen.org/rest/search?query=dc.date.accessioned_dt:[NOW-7DAY/DAY+TO+NOW]
- All titles, classified as “Politics & Government”, added in the last week. Query using dc.subject.classification, dc.date.accessioned_dt -
https://library.oapen.org/rest/search?query=dc.subject.classification:%22Politics+%26+Government%22+AND+dc.date.accessioned_dt:[NOW-7DAY/DAY+TO+NOW]
- All titles, added between 1 May 2020 and 10 May 2020. Query using dc.date.accessioned_dt -
https://library.oapen.org/rest/search?query=dc.date.accessioned_dt:[2020-05-01T00:00:00Z+TO+2020-05-10T23:59:59Z]
- Find the most recently added title, classified as “Politics & Government”. Query using dc.subject.classification, dc.date.accessioned_dt -
https://library.oapen.org/rest/search?query=dc.subject.classification:%22Politics+%26+Government%22&sort=dc.date.accessioned_dt&limit=1
If needed, you can expand metadata, bitstreams or both.
Collections
If you want to expose collections, query the oapen.collection field (using the collection label, not an ID). The same expand options are available.
Example:
- Find the collection “European Research Council” -
https://library.oapen.org/rest/search?query=oapen.collection:%22European+Research+Council%22
Funders
Retrieving all publications by a funder can be achieved via the relationship metadata fields. To find the actual ID for a funder, search by funder name, using the grantor.name field.
Example:
- Find the funder “Austrian Science Fund (FWF)“ -
https://library.oapen.org/rest/search?query=grantor.name:Austrian+Science+Fund+%28FWF%29&expand=metadata
- The ID can be found with the <UUID> tag:
<UUID>6c9e728b-5e84-472c-a792-21775da55aa0</UUID>
Expose the publications, by querying the oapen.relation.isFundedBy field
Example:
- The ID of funder Austrian Science Fund is 6c9e728b-5e84-472c-a792-21775da55aa0 -
https://library.oapen.org/rest/search?query=oapen.relation.isFundedBy:%226c9e728b-5e84-472c-a792-21775da55aa0%22
If needed, you can expand metadata, bitstreams or both.
Note that querying grantor.name also lists all publications funded by that funder - under the repeated “oapen.relation.funds” field – without the details. Therefore, use the above query to get all details at once instead of using one query per item to get their detailed metadata / files.
Publishers
Retrieving all publications by a publisher can be achieved via the relationship metadata fields. To find the actual ID for a publisher, search by publisher name, using the publisher.name field.
Example:
- Find the publisher “Oxford University Press“ -
https://library.oapen.org/rest/search?query=publisher.name:Oxford+University+Press&expand=metadata
- The ID can be found with the <UUID> tag:
<UUID>b9501915-cdee-4f2a-8030-9c0b187854b2</UUID>
Expose the publications, by querying the oapen.relation.isPublishedBy field
Example:
- The ID of publisher Oxford University Press is b9501915-cdee-4f2a-8030-9c0b187854b2 -
https://library.oapen.org/rest/search?query=oapen.relation.isPublishedBy:%22b9501915-cdee-4f2a-8030-9c0b187854b2%22
If needed, you can expand metadata, bitstreams or both.
Note that querying publisher.name also lists all publications from that publisher - under the repeated “oapen.relation.isPublisherOf” field – without the details. Therefore, use the above query to get all details at once instead of using one query per item to get their detailed metadata / files.
Communities and collections
The contents of the OAPEN Library are divided into “communities”, and the communities are subdivided into “collections”.
- List all communities -
https://library.oapen.org/rest/communities/
- List all collections -
https://library.oapen.org/rest/collections/
XML or JSON format
You must set your request header’s “Accept” property to either JSON (application/json) or XML (application/xml) depending on the format you prefer to work with.
Example:
- JSON format -
curl -s -H "Accept: application/json" "https://library.oapen.org/rest/search?query=handle:%2220.500.12657/25287%22&expand=metadata,bitstreams"
- XML format -
curl -s -H "Accept: application/xml" "https://library.oapen.org/rest/search?query=handle:%2220.500.12657/25287%22&expand=metadata,bitstreams"
More information
You can find more information on the REST API in this file.