How to use the UMedia API

UMedia provides open access to digitized materials from across the University of Minnesota. There are several methods you can use to programmatically access metadata and digital objects from the UMedia collections:

  1. The JSON API section below describes how you can construct URLs to download metadata and text data from UMedia. 
  2. The IIIF Documentation section below describes how to programmatically download digital objects from UMedia.
  3. This Python notebook (GitHub) includes example code you can use to build more sophisticated API queries. 

JSON API: For UMedia metadata and text

The search interface for UMedia includes an API that you can access by modifying the URLs to point to JSON representations of both UMedia search results as well as individual records for UMedia objects.

Creating JSON URLs 

To create a URL in UMedia to call the JSON API, you can simply append ".json" before the question mark in any UMedia URL. This search, for example, displays the UMedia Historical Maps collection:

https://umedia.lib.umn.edu/search?facets%5Bcollection_name_s%5D%5B%5D=Historical+Maps 

To view the API results for the search above, you can add ".json" after "search" and before "?":

https://umedia.lib.umn.edu/search.json?facets%5Bcollection_name_s%5D%5B%5D=Historical+Maps

Note that you can also manually request more results, by adding "&rows=" at the end of your URL, along with the number of the search results you would like to see. If you want to use the API to download the metadata for the entire Historical Maps collections, you can add "&rows=8763" to the end of the URL (caution: this might take a long time to load):

https://umedia.lib.umn.edu/search.json?facets%5Bcollection_name_s%5D%5B%5D=Historical+Maps&rows=8763 
Single items in UMedia

Adding ".json" also works for URLs of specific item records in UMedia. Here's the record for a 15th century map of Afghanistan and Pakistan:

https://umedia.lib.umn.edu/item/p16022coll251:3420

And here's the API call to view the same record represented in JSON:

https://umedia.lib.umn.edu/item/p16022coll251:3420.json

If you want more detailed information from the UMedia API, you can construct an API call to iterate through the search results, and pull the JSON record for each item in the results to get full information. See the Python notebook for examples of how to build that kind of API request.

Limitations
  • The UMedia API will not download digital objects (e.g., images) from UMedia. Please see the IIIF Documentation below for instructions of how to access digial objects programmatically.
  • Some metadata fields are not accessible via the JSON for search results. They can be accessed by viewing the full JSON for an individual record.
Formatting URLs

The general form of the URL to construct a JSON API call of UMedia is:

https://umedia.lib.umn.edu/search.json?facets%5Bfilter_1%5D%5B%5D=key_1&facets%5Bfilter_2%5D%5B%5D=key_2&sort=&q=k

The structure of the URL for UMedia's JSON is formed by three parts:

  1. Base URL
  2. Filters
  3. Search by Keyword

Let us go through them one by one.

Base URL

The base URL is the same for every UMedia page. You can simply copy this:

https://umedia.lib.umn.edu/search.json?
Filters

Use filters to narrow the scope of your search. You can see the full list of available filters in the Appendix below.

This is the basic format for adding filters to your URL:

facets%5Bfilter_1%5D%5B%5D=key_1&facets%5Bfilter_2%5D%5B%5D=key_2

You can just replace "filter_1" with the filter you want. It is the same for "filter_2", "key_1", and "key_2". For example, if you want the creator of all the search results for "Detroit Publishing Co.", the URL would be:

facets%5Bcreator_ss%5D%5B%5D=Detroit Publishing Co.

If you want to add more filters, just append them at the end of your URL string. Remember to use "&" to connect them. For example, here we set the types filter to "Still Image":

facets%5Bcreator_ss%5D%5B%5D=Detroit+Publishing+Co.&facets%5Btypes%5D%5B%5D=Still Image

Don't forget to include the base URL at the beginning! The full URL for the example above would be:

https://umedia.lib.umn.edu/search.json?facets%5Bcreator_ss%5D%5B%5D=Detroit+Publishing+Co.&facets%5Btypes%5D%5B%5D=Still Image

Another helpful filter is collection name. To display all of the items from the "Digitizing Immigrant Letters" collection, for example:

https://umedia.lib.umn.edu/search.json?facets%5Bcollection_name_s%5D%5B%5D=Digitizing+Immigrant+Letters
Keyword Search

To add search terms to your URL, the format is:

&q=k

To form your own search URL, replace the "k" above by any keyword(s) that you want to query. For example, if you want to search "Kovač" the search format would be:

&q=Kovač

So to search "Kovač", the full URL would be:

https://umedia.lib.umn.edu/search.json?&q=Kovač

What if you want to search for a keyword with filters? For instance, if you want to search "African Americans" and then limit the results to the item type of "Still Image" and the creator "Scurlock, Addison N." you can simply use "&" to connect everything together.

Search screen for UMedia

The filter for creator is:

facets%5Bcreator_creator_ss%5D%5B%5D=Scurlock, Addison N.

The filter for the type of "Still Image" is:

facets%5Btypes%5D%5B%5D=Still+Image

And the URL for searching the keywords "African Americans" is:

q=African Americans

Putting it all together:

https://umedia.lib.umn.edu/search?facets%5Bcreator_ss%5D%5B%5D=Scurlock%2C+Addison+N.&facets%5Btypes%5D%5B%5D=Still+Image&q=african+americans

IIIF calls to download digital objects

To demonstrate how to programmatically download digital objects from UMedia, we will first explore how to download still images.

This section introduces an image delivery API defined by the International Image Interoperability Framework (IIIF) Consortium. By using the IIIF Image API, users can retrieve an image in response to a standard HTTP or HTTPS request. By editing the URL, users can specify the region, size, rotation, quality, and format of the requested image.

The general form of the URL for an image in UMedia is:

https://cdm16022.contentdm.oclc.org/digital/iiif/[collection-name]/[record-id]/[region]/[size]/[rotation]/[quality].[format]
Base URL

The Base URL, which should precede all IIIF calls for UMedia images via API is:

https://cdm16022.contentdm.oclc.org/digital/iiif/
Identifiers

As indicated in the general form above, there are two identifiers in the URL: collection name and record ID. Figuring out the identifiers of your target object is the most critical part to form the URL. I will use an example to illustrate how to find the identifiers for a target object.

Suppose this poster is the object we want to download:

Screenshot of poster on UMedia

Let's first copy the link address for the title:

Screenshot of copying the link from the title of the record

The link address that we just copied is:

https://umedia.lib.umn.edu/item/p16022coll208:4833?q=national+campaign+for+work

The information about the identifiers we need is included in this link address! Notice that after item/, there is a unique identifer, "p16022coll208:4833". This is the code we want. To break it down, it says that the collection name is p16022coll208 and the record ID is 4833.

For this image, then, the first part of our IIIF API call would be:

https://cdm16022.contentdm.oclc.org/digital/iiif/p16022coll208/4833/

Note that the IIIF response displays technical metadata about the image, but not the image itself. To download the image using the API, we have to add technical specifications in the URL as well.

Specifications

To download the original image without any modification, use the following specifications:

full    for [region]
full    for [size]
0       for [rotation]
default for [quality]
jpg     for [format]

For example, the full URL for the image above (p16022coll208:4833), using the default specifications would be:

https://cdm16022.contentdm.oclc.org/digital/iiif/p16022coll208/4833/full/full/0/default.jpg

You can open this URL in your browser to view and download the image. Of course, there are a lot of options for users to choose for region, size, rotation, quality, and format. To view more specification options for a specific record you can go to:

https://cdm16022.contentdm.oclc.org/digital/iiif/[collection-name]/[record-id]

Or for the example above, view:

https://cdm16022.contentdm.oclc.org/digital/iiif/p16022coll208/4833/

To find more information about the IIIF syntax check out the full API.

Appendix: URL Filters

Filters URL Example
Collection collection_name_s
collection_name_s%5D%5B%5D=Historical+Maps
Contributor contributor_ss
contributor_ss%5D%5B%5D=Blaeu%2C+Joan%2C+1596-1673
Contributing organization contribution_organization_name_s
contributing_organization_name_s%5D%5B%5D=Jaques+Art+Center
Creator creator_ss
creator_ss%5D%5B%5D=Hansen%2C+David+L.%2C+1952-
Date date_created_ss
date_created_ss%5D%5B%5D=1916
Format format_name
format_name%5D%5B%5D=Lantern+slides
Language language
language%5D%5B%5D=Japanese
Publisher publisher_s
publisher_s%5D%5B%5D=U.S.+Government+Printing+Office
Special Projects super_collection_name_ss
super_collection_name_ss%5D%5B%5D=Atlantic+World
Subject subject_ss
subject_ss%5D%5B%5D=Birds+Minnesota
Type types
types%5D%5B%5D=Still+Image

 

Documentation by Yupei Liu and Cody Hennesy

  • JSON API - Learn how to construct URLs to download metadata and text data from UMedia. 
  • IIIF Documentation - Learn how to programmatically download digital objects from UMedia.
  • Python notebook - Walk through example code you can use to build more sophisticated API queries.