We serve the API over SSL, in other words, with “https”, but it’s also still available with plain HTTP (as “http”) if you like. Many of the examples in this Codex still say “http” but you may always use “https” instead.
When you formulate a REST query, you have to decide which resource type you want. The resource type is the first word in your query and determines the format of the response data. The two resource types currently offered are described below.
item is a reference to the digital representation of a single piece of content indexed by the DPLA. The piece of content can be, for example, a book, a photograph, a video, etc. The content is digitized from its original, physical source and uploaded to an online repository. The DPLA allows users to search for content across a multitude of online repositories, including University of Virginia Library, Kentucky Digital Library, Harvard University Library, etc. After retrieving DPLA
items, developers can display or follow links to their original online digital records.
The RESTful URL to request data from the items resource begins:
collection is a little more abstract than an item. Where an
item is a reference to the digital representation of a physical object, a
collection is a representation of the grouping of a set of
For example, a university could have a collection of Emily Dickinson poems. If so, the DPLA would have a digital
collection object that represents the library’s conceptual collection. All DPLA items that represent online digital records that are part of a conceptual collection are identified as belonging to a
The RESTful URL to request data from the collections resource begins:
Remember: You must enter your 32-character API key after the
&api_key= parameter in every request you make, including the examples below. Learn how to request one.
Query features can be broken into two sections: What do you want? and How do you want it?
What do you want?
- Simple search
- Boolean operators
- Searching within specific fields
- Temporal searching
- Spatial searching
- Searching within collections
- Fetching specific items
How do you want it?
Putting it all together
This is just a keyword search against all the text fields. If don’t know anything about the fields, but you know you want
kittens, use the
kittens anywhere in any field)
You can combine multiple terms using AND and OR operators. The default behavior when searching for multiple terms is boolean AND.
(items with both
banana in any field)
(items with either
costumes in any field)
Throw in an asterisk (
*) when you want to match any collection of characters within a word. For example, you may want all possible variants of
yodeling, regardless of prefixes, infixes, and suffixes.
(items with words ending in
deling in any field: yodeling, modeling, etc.)
(items with words beginning with
yodel in any field: yodel, yodeled, yodeling, etc.)
(items with words containing the characters
odel anywhere in any field: modeled, Winona Odel, etc.)
Searching within specific fields
Searching for phrases
%22, such as:
For example, the quoted phrase
"old+victorian" will return records with titles containing that exact sequence of letters. Without the quotes, you might get a record with a title like “Belter Victorian settee with old rose upholstery.”
Some fields are case-sensitive. For example, take
sourceResource.format. A search for
sourceResource.format="will return no records, but one for
sourceResource.format=" will. Here is a list of the most significant fields that are case-sensitive:
Searching for an exact match on a phrase
Going back to the example above of quoting a phrase to search for a specific sequence of words, you will find eventually that our search on
"old+victorian" is capable of returning results that contain that sequence, such as “old Victorian settee.” Suppose you want records from University of Pennsylvania, but not Lock Haven University of Pennsylvania. What then?
For that purpose, we have a parameter,
exact_field_match, which says to match exactly the phrases given in field parameters — and nothing more.
An exact match could be specified as follows:
The parameter is case-sensitive and must read “true” to be recognized.
This parameter is especially useful if you are building an application that displays facets to the user, and gives the user the opportunity to click through to narrow down a search on those values. In that case, you want this kind of exact match.
exact_field_match behavior is applied to all specific-field parameters. It does not affect the behavior of the “simple search”
q parameter (which can be combined with fields, and with
You can search for terms within any textual field except
- fields within the
- fields within the
- values for the
You do not need the
q parameter when searching within a specific field. Use the field’s name as a URL query string parameter instead.
You can combine specific field searches with simple search. You can also combine multiple field-specific searches. When combining field
q parameters, separate them with an ampersand (
&). (You already are doing this when you append
&api_key to your requests.) These combinations are exclusive, meaning that result items fulfill all simple and field-specific criteria.
You may also use the boolean operators and wildcards when searching specific fields.
obituaries anywhere in the
yodellers anywhere in the
Field & simple:
zoo in the
zebra in any field.)
dog in the
(items with words beginning with
yodel in the
The DPLA API understands dates. Combine that with the fielded search above, and you’ve got a pretty spiffy way of finding records that have fields that fall before, after, and between dates.
The following examples search the
sourceResource.date field, which is the time frame of the original physical object, such as when a book was written or when a photo was taken.
(items that were created on or after
(items that were created on or before
(items that were created between
A related field,
sourceResource.temporal, describes the temporal characteristic, or “about-ness” of the the resource, such as the time period about which a book is written. As with
sourceResource.date, you can search
sourceResource.temporal using the keywords
Note that the keywords
before are used to scope the time span of your search. As you will see in the examples below, if you want to
facet a search on
sourceResource.temporal, you will use the keywords
You can find records around a location of interest to you by simply searching within
spatial fields. DPLA also understands
coordinates of the form
latitude:longitude so you can find things more specifically.
The following examples search the
sourceResource.spatial field (the location of the original physical object’s creation, or other location associated with a record, e.g., its setting [for a book]).
spatial field has many searchable sub-fields. A few important ones are:
coordinates. If you do not specify a sub-field, all are searched. The
state sub-field is normalized to the full spelling of the (US) state’s name.
(items that are in or about Boston)
(items that are in or about the State of Hawaii)
(items that are in or about the States of either Massachusetts or Hawaii)
Searching within collections
If you have a collection in mind, use the
Say you already have the
id for the
item you want, and you’re just looking to get the rest of the metadata for that item. Simply add the
id to the end of the
items request. Bonus: You can search for multiple IDs by separating them with a comma (,), with a maximum of 50
ids per request.
(item with the given
Fetching only certain fields
You’re a busy person. You don’t need to stare at pages and pages of JSON. You know what you want, and after you read this, you’ll know how to get it.
You can get only the fields you want by using the “fields” parameter, and comma (,) separating the field names. This works for any field except:
yodellers in the
title but only return the
Sort stuff using the
sort_by parameter. We’ll sort stuff in ascending order by default, but if you’d like to flip things, set the
sort_order parameter to
To see which fields are sortable, see the Sortable Fields section.
You can also sort by distance from a geographic point (which is pretty sweet). Use the
sort_by_pin parameter with a latitude and longitude pair, and make sure to specify the coordinates field to use in the
yodeling in any field, sorted by the
yodeling in any field, sorted by starting time span; most recent items listed first)
atlanta in any field, sorted by the name of their subject)
(all items sorted by distance to Boston)
Facets tell you the most common values for certain fields in a collection of items. We return a couple different types of facets depending upon the field you’re looking for. For date fields, we’ll send back facets of type
date_histogram (which is what it sounds like). For complex text fields, we’ll break it down for you into a
terms type. For simple text fields, we’ll also send back a
terms type but with unadulterated values. And for geographic types, we’ll give you a
geo_distance type. See what that looks like in the Field Reference.
To see which fascinating fields are facetable, see the Facetable Fields list.
Facet Limit (maximum 2000):
By default, we’ll give you 10 items. If that’s not enough, you can get the next ten items incrementing the
page parameter (it’s one-indexed). If that’s still not enough, you can pull more items per page by using the
page_size parameter (we’ll limit you to 500 items per page because greediness is a vice).
You’re probably not on our domain, so you probably want to wrap everything up nicely with a callback. Use the
Let’s get this APIarty started.
(items with both words beginning with
atl in any field and
africa in the
(the first 25 items with either words beginning with
atl or the full word
africa in the description)
- sourceResource.spatial.coordinates (with additional sort_by_pin query parameter, like “sort_by_pin=42,-70”)
- sourceResource.spatial.coordinates (with facet modifier, like “sourceResource.spatial.coordinates:42:-70”
- admin.contributingInstitution (combines dataProvider and intermediateProvider)