Open Collections

The Open Collections API

UBC Library Open Collections provides direct programmatic access to all of the metadata and much of the media available on the website through our APIs.

Three different Open Collections API Endpoints are available to meet a variety of use cases:

• The Open Collections REST API provides access to all collection and item-level metadata and full text transcripts, as well as the ElasticSearch search index for complex queries.
• The Open Collections OAI-PMH API provides access to item-level metadata programmatically or for harvesting by compatible software.
• The Open Collections IIIF API provides access to images and associated metadata programmatically or for use with IIIF-compatible image viewers.

To use the Open Collections APIs, you should first register for an API Key: Unregistered users will be limited in the number of requests that can be made.

Before using the APIs, please review and comply with our terms of use.

More information on using each of the API Endpoints can be found below. If you have feedback, questions, or want to share work that you've done using the API, please get in touch!

API Keys

To control abuse, users are encouraged to register their email address to receive an Open Collections API Key. The API Key is a string of characters that is appended to your API Request to show that it originates from a verified source. Unregistered users will be limited in the number of requests that can be made.

The Open Collections REST API

Metadata Endpoints

Collection and item metadata is requested from the Open Collections API by querying specifically structured endpoints. All metadata endpoints begin with the API base url, https://oc-index.library.ubc.ca, followed by a specific path for the collection and item being requested.

Collections

A collection is a reference to a set of items indexed in Open Collections. Collections have two RESTful endpoints associated with them, a /collections/ endpoint that returns information about the collection, and and a /collections/.../items/ endpoint that lists the contents of the collection.

Collection Metadata

The collection metadata endpoints return data describing the contents of a collection.

https://oc-index.library.ubc.ca/collections/[:name]

https://oc-index.library.ubc.ca/collections/berkpost

Mappings for all collection nicknames are available here .

Collection Items

The collections items endpoints return a list all items in a collections. There are two types of collection items endpoints, one returns a simple list of all items in a collection (ids only), and the other returns a paginated list of all items in the collection with a richer subset of metadata.

https://oc-index.library.ubc.ca/collections/[:name]/items

https://oc-index.library.ubc.ca/collections/arkley/items

https://oc-index.library.ubc.ca/collections/[:name]/items?limit=[:limit]&offset[:offset]

https://oc-index.library.ubc.ca/collections/arkley/items?limit=10&offset=0

Item Metadata

An "item" in open collection is typically a single piece of content indexed in Open Collections. The content can be, for example, a book, an image, a video, and in some cases can have multiple components (ie. a PDF and an audio file). The /item/ endpoint returns data

https://oc-index.library.ubc.ca/collections/[:name]/items/[:itemId]

https://oc-index.library.ubc.ca/collections/arkley/items/1.0013125

Tip: You can grab the requisite [:name] and [:itemId] values from the collection/.../items endpoint.

Search Endpoint

The Open Collections /search/[:api_version]/ endpoint returns search results and metadata from the system's ElasticSearch index, where [:api_version] is the version of ElasticSearch syntax to use (currently we are supporting 8.5). The endpoint supports GET requests with a limited subset of parameters, and more complete access to the full ElasticSearch feature set via POST request (see Advanced Usage).

Basic Searching (GET Requests)

https://oc-index.library.ubc.ca/search/8.5?q=[:query]

https://oc-index.library.ubc.ca/search/8.5?q=cat

https://oc-index.library.ubc.ca/search/8.5?q=[:query]&index=[:index]

https://oc-index.library.ubc.ca/search/8.5?q=cat&index=arkley

https://oc-index.library.ubc.ca/search/8.5?q=[:query]&term=[:field],[:term];[:field],[:term]

https://oc-index.library.ubc.ca/search/8.5?q=cat&term=creator.raw,Kull%2C%20Bob;type.raw,Still%20Image

See the full list of supported parameters in the API Reference or at https://oc-index.library.ubc.ca/search/help . Note that parameter values should be URI-encoded to avoid errors.

Advanced Usage

For more advanced use cases, the Open Collections Search API provides access to the full power of its underlying ElasticSearch index, including aggregations (useful for data visualization and analysis), advanced searching and filtering, geolocation, and much more (everything except custom script fields).

ElasticSearch version 8.5 Query DSL objects can be submitted to the /search/8.5/ endpoint via POST request and can be combined with the Open Collections search URI parameters. Query DSL object values will take precedence over URI parameter values.

Learn more about the ElasticSearch API:

• Search API documentation
• Query DSL documentation
• Aggregations
• Dealing with Human Language
• Geolocation

REST API Reference

API Endpoints

The following endpoints are available for use:

Collections

Fields

To view more about our metadata terms please view this page.

Search Parameters

The open collections https://oc-index.library.ubc.ca/search/8.5 endpoint accepts the following paremeters in GET requests:

Output Formats

Responses from the API are returned in JSON by default however there are a number of different formats available which we will show you how to request for below.

GET Requests

For GET requests you should replace :outputFormat in the URL below with the format you want returned:
https://oc-index.library.ubc.ca/collections/ [:name] /items/ [:itemId] /output-format/ [:outputFormat]

POST Requests

For POST requests you should set the HTTP Accept header to the format you want returned.

Available Formats

Example Scripts

Example scripts for working with the API in a variety of languages can be found on the UBC Library GitHub.

Get all items from a collection

To get all items from a collection you need to request the collection first and retrieve all its item ids and then loop through each item using the API.

Harvest full text of all items in a collection

Note: not all collections have full text, we've specifically chosen one of the smaller collections with full text to show you how to programmatically loop through items and export the full text.

Download Collection Data

This script should be run from a terminal window, it allows you to download items metadata into a format of your choosing using the API.

The Open Collections OAI-PMH API

What is OAI-PMH?

The Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH) provides an application-independent interoperability framework based on metadata harvesting. Open Collections’ OAI-PMH repository is a network accessible server that can process the 6 OAI-PMH requests to expose metadata to harvesters.

Note: To access Open Collections’ OAI-PMH you need to use a registered api_key in your request header. You can Register an API key if you don’t have one already. The following command shows how to add the api_key into request header using curl command:

Repository Info and Identifier Format

https://oce-index.library.ubc.ca/oai?verb=Identify 

<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
    <responseDate>2021-02-03T11:08:34Z</responseDate>
    <request verb="Identify">https://oc2-index-dev-ah.library.ubc.ca/oai</request>
    <Identify>
        <repositoryName>Open Collections</repositoryName>
        <baseURL>https://oce.library.ubc.ca/oai</baseURL>
        <protocolVersion>2.0</protocolVersion>
        <adminEmail>library.opencollections@ubc.ca</adminEmail>
        <earliestDatestamp>2020-01-01T00:00:00Z</earliestDatestamp>
        <deletedRecord>transient</deletedRecord>
        <granularity>YYYY-MM-DDThh:mm:ssZ</granularity>
        <description>
            <oai-identifier xmlns="http://www.openarchives.org/OAI/2.0/oai-identifier"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai-identifier http://www.openarchives.org/OAI/2.0/oai-identifier.xsd">
                <scheme>oai</scheme>
                <repository>oc</repository>
                <delimiter>:</delimiter>
                <sampleIdentifier>oai:oc:1.0088719</sampleIdentifier>
            </oai-identifier>
        </description>
    </Identify>
</OAI-PMH>
  

OAI-PMH Commands

To learn more about the OAI-PMH and request/verb details please see http://www.openarchives.org/OAI/openarchivesprotocol.html

The Open Collections IIIF API

UBC Open Collections uses the International Image Interoperability Framework ("IIIF") standard to display image content in the site, and provides access to this API through the OC IIIF API endpoint. This endpoint can return images resized and modified to specific specifications as well as metadata ("manifests") associated with the images, and can be used to view content in a number of different IIIF-compatible viewers. Requests can be made to the Open Collections IIIF Endpoint using IIIF 2.0 syntax at:

https://iiif.library.ubc.ca

IIIF API References

Some basic examples are included below, but for full details on using the IIIF standard, including the specific syntax and parameters available please consult the official documentation here:

• IIIF Image API 2.0 Documentation for accessing media
• IIIF Presentation API 2.0 Documentation for accessing manifests and metadata

Note: When working with results from the Open Collections Metadata API the item identifiers need to have the dot replaced with a dash to work with the IIIF API. For instance '1.0001258' would become '1-0001258'

Example: Requesting a Specific Image Size

Once you've found an image you like, you can modify the URL to get the correct sized desktop background:

http://iiif.library.ubc.ca/image/cdm.tokugawa.1-0213163/full/1600,900/0/default.png

If we wanted to remove the excess borders we could replace 'full' in the [:region] part of the IIIF url with the crop coordinates:

 http://iiif.library.ubc.ca/image/cdm.tokugawa.1-0213163/1145,374,9234,4645/1600,900/0/default.png