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:
- The JSON API section below describes how you can construct URLs to download metadata and text data from UMedia.
- The IIIF Documentation section below describes how to programmatically download digital objects from UMedia.
- This Python notebook (GitHub) includes example code you can use to build more sophisticated API queries.
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:
To view the API results for the search above, you can add ".json" after "search" and before "?":
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):
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:
And here's the API call to view the same record represented in 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.
- 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.
The general form of the URL to construct a JSON API call of UMedia is:
The structure of the URL for UMedia's JSON is formed by three parts:
- Base URL
- Search by Keyword
Let us go through them one by one.
The base URL is the same for every UMedia page. You can simply copy this:
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:
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":
Don't forget to include the base URL at the beginning! The full URL for the example above would be:
Another helpful filter is collection name. To display all of the items from the "Digitizing Immigrant Letters" collection, for example:
To add search terms to your URL, the format is:
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:
So to search "Kovač", the full URL would be:
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.
The filter for creator is:
facets%5Bcreator_creator_ss%5D%5B%5D=Scurlock, Addison N.
The filter for the type of "Still Image" is:
And the URL for searching the keywords "African Americans" is:
Putting it all together:
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:
The Base URL, which should precede all IIIF calls for UMedia images via API is:
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:
Let's first copy the link address for the title:
The link address that we just copied is:
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:
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.
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:
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:
Or for the example above, view:
To find more information about the IIIF syntax check out the full API.
Documentation by Yupei Liu and Cody Hennesy