Requests

The base URL of the API is:

https://api.dp.la/v2

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.

Resource Types

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.

items

A DPLA 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:

https://api.dp.la/v2/items

collections

A 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 items.

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 collection object.

The RESTful URL to request data from the collections resource begins:

https://api.dp.la/v2/collections

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.

Feature Outline

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
• Wildcards
• Searching within specific fields
• Temporal searching
• Spatial searching
• Searching within collections
• Fetching specific items

How do you want it?

• Fetching only certain fields
• Sorting results
• Faceting results
• Pagination
• JSONP

Putting it all together

• Complex queries
• Sortable fields
• Facetable fields

Features

Simple search

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 q parameter.

Example:

https://api.dp.la/v2/items?q=kittens&api_key=

(items with kittens anywhere in any field)

Boolean operators

You can combine multiple terms using AND and OR operators. The default behavior when searching for multiple terms is boolean AND.

Examples:
AND:

https://api.dp.la/v2/items?q=fruit+AND+banana&api_key=

(items with both fruit and banana in any field)

OR:

https://api.dp.la/v2/items?q=yodeling+OR+costumes&api_key=

(items with either yodeling or costumes in any field)

Wildcards

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.

Examples:

https://api.dp.la/v2/items?q=*deling&api_key=

(items with words ending in deling in any field: yodeling, modeling, etc.)

https://api.dp.la/v2/items?q=yodel*&api_key=

(items with words beginning with yodel in any field: yodel, yodeled, yodeling, etc.)

https://api.dp.la/v2/items?q=*odel*&api_key=

(items with words containing the characters odel anywhere in any field: modeled, Winona Odel, etc.)

Searching within specific fields

Searching for phrases

sourceResource.title="old+victorian"

sourceResource.title=%22old+victorian%22

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="lithograph+on+paper"will return no records, but one for sourceResource.format="Lithograph+on+paper" will. Here is a list of the most significant fields that are case-sensitive:

• id
• sourceResource.format
• sourceResource.type
• sourceResource.contributor
• sourceResource.date.displayDate
• sourceResource.extent
• sourceResource.language.iso639
• sourceResource.spatial.iso3166-2
• sourceResource.specType
• sourceResource.stateLocatedIn.name

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:

dataProvider=University+of+Pennsylvania&exact_field_match=true

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.

The 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 exact_field_match).

Searchable fields

You can search for terms within any textual field except

• fields within the @context field
• fields within the originalRecord field
• values for the ingestType and ingestDate fields

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.

Examples:

https://api.dp.la/v2/items?sourceResource.description=obituaries&api_key=

(items with obituaries anywhere in the description field)

https://api.dp.la/v2/items?sourceResource.title=yodellers&api_key=

(items with yodellers anywhere in the title field)

Multiple:

https://api.dp.la/v2/items?sourceResource.language=Russian&sourceResource.description=1982&api_key=

(items with Russian in the list of languages and 1982 in the description)

Field & simple:

https://api.dp.la/v2/items?sourceResource.title=zoo&q=zebra&api_key=

(items with zoo in the title and zebra in any field.)

Boolean:

https://api.dp.la/v2/items?sourceResource.title=cat+OR+dog&api_key=

(items with cat or dog in the title.)

Wildcard:

https://api.dp.la/v2/items?sourceResource.title=yodel*&api_key=

(items with words beginning with yodel in the title.)

Temporal searching

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.

This field can be a range of dates, e.g., a book pertaining to the decade of the 1930s can have an after year of 1930 and a before year of 1939.

Examples:

https://api.dp.la/v2/items?sourceResource.date.after=1910-01-01&api_key=

(items that were created on or after 1910)

https://api.dp.la/v2/items?sourceResource.date.before=1869-01-01&api_key=

(items that were created on or before 1869)

https://api.dp.la/v2/items?sourceResource.date.after=1910&sourceResource.date.before=1920&api_key=

(items that were created between 1910 & 1920)

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 after and before.

Note that the keywords after and before are used to scope the time span of your search. As you will see in the examples below, if you want to sort or facet a search on sourceResource.date or sourceResource.temporal, you will use the keywords begin and end.

Spatial searching

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]).

The spatial field has many searchable sub-fields. A few important ones are: name, state, and 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.

Examples:

https://api.dp.la/v2/items?sourceResource.spatial=Boston&api_key=

(items that are in or about Boston)

https://api.dp.la/v2/items?sourceResource.spatial.state=Hawaii&api_key=

(items that are in or about the State of Hawaii)

https://api.dp.la/v2/items?sourceResource.spatial.state=Massachusetts+OR+Hawaii&api_key=

(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 sourceResource.collection.title field.

Example:

https://api.dp.la/v2/items?sourceResource.collection.title=Smith&api_key=

Fetching specific items

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.

Example:

https://api.dp.la/v2/items/fffffed915b46b7d71bcc8d888900c4b?api_key=

(item with the given id)

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:

• @context
• originalRecord

Examples:

https://api.dp.la/v2/items?sourceResource.title=yodellers&fields=sourceResource.title&api_key=

(items with yodellers in the title but only return the titles)

https://api.dp.la/v2/items?q=atlanta&fields=sourceResource.description,sourceResource.date&api_key=

(items with atlanta in any field but only return the description and date range)

Sorting results

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 desc.

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 sort_by parameter.

Examples:

https://api.dp.la/v2/items?q=yodeling&sort_by=sourceResource.title&api_key=

(items with yodeling in any field, sorted by the title)

https://api.dp.la/v2/items?q=yodeling&sort_by=sourceResource.date.begin&sort_order=desc&api_key=

(items with yodeling in any field, sorted by starting time span; most recent items listed first)

https://api.dp.la/v2/items?q=atlanta&sort_by=sourceResource.subject.name&api_key=

(items with atlanta in any field, sorted by the name of their subject)

https://api.dp.la/v2/items?sort_by_pin=42.3,-71&sort_by=sourceResource.spatial.coordinates&api_key=

(all items sorted by distance to Boston)

Faceting results

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.

Examples:

Basic:

https://api.dp.la/v2/items?facets=isPartOf&api_key=

Multiple:

https://api.dp.la/v2/items?facets=sourceResource.publisher,sourceResource.creator&api_key=

No Docs:

https://api.dp.la/dev/items?facets=sourceResource.date.begin&page_size=0

Auto-Expanded:

https://api.dp.la/v2/items?facets=sourceResource.subject.@id,sourceResource.subject.name&api_key=

Dates:

https://api.dp.la/v2/items?facets=sourceResource.date.begin&api_key=

Geo-Distance:

https://api.dp.la/v2/items?facets=sourceResource.spatial.coordinates:42.3:-71&api_key=

Facet Limit (maximum 2000):

https://api.dp.la/v2/items?facets=sourceResource.date.begin&facet_size=3&api_key=

 

Pagination

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). The maximum page number is 100. 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).

Examples:

https://api.dp.la/v2/items?q=yodeling&page_size=2&api_key=

https://api.dp.la/v2/items?q=atlanta&page_size=25&api_key=

https://api.dp.la/v2/items?q=atlanta&page_size=25&page=3&api_key=

JSONP

You’re probably not on our domain, so you probably want to wrap everything up nicely with a callback. Use the callback parameter and specify your callback name. The response will be JavaScript (rather than pure JSON) that, when evaluated, will call your callback function.

If you are using a JavaScript library for AJAX, such as jQuery or Zepto, the library will handle using the callback parameter for you if you set dataType to “jsonp”.

Examples:

https://api.dp.la/v2/items?sourceResource.subject=yodeling&callback=myFunc&api_key=

Complex Queries

Let’s get this APIarty started.

Examples:

https://api.dp.la/v2/items?q=atl*&sourceResource.title=africa&api_key=

(items with both words beginning with atl in any field and africa in the title)

https://api.dp.la/v2/items?sourceResource.description=atl*+OR+africa&page_size=25&api_key=

(the first 25 items with either words beginning with atl or the full word africa in the description)

https://api.dp.la/v2/items?sourceResource.title=africa&sourceResource.date.after=1960&sourceResource.date.before=1995&page_size=25&api_key=

(the first 25 items with africa in the title that were published between 1960 and 1995)

https://api.dp.la/v2/items?sourceResource.title=africa&sourceResource.date.after=1960&sourceResource.date.before=1995&sort_by=sourceResource.title&page_size=25&api_key=

(the first 25 items with africa in the title that were published between 1960 and 1995 sorted by the title)