API CODEX

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:

http://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:

http://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?

Searching within specific fields

Searching for phrases

Quote characters may also be represented as URL-encoded entities, with %22, such as:

sourceResource.title=%22old+victorian%22

Spaces must be represented by plus (+) characters. (This is a standard aspect of URL-encoding, independent of our API.)

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:

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

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.

Searching within collections

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.

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.

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.

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

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

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

http://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”.