API Codex

Requests

API CODEX


» Codex Home
» API Basics
⚐ Requests
» Responses
 »  Object Structure
 »  Field Reference
» Glossary
» Policies
» Philosophy
» Technologies
» Troubleshooting & FAQ
 »  Issue Tracker
» Contact

The base URL of the API is:

http://api.dp.la/v2

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?

What do you want?

How do you want it?

Putting it all together

 

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:

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

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

(items with both fruit and banana in any field)

OR:

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

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

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

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

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

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

You don’t know what you want, but you know it has to have yodellers [sic] in the title. It doesn’t just have to be the title, though. You can search for terms within any textual field except:

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:

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

(items with obituaries anywhere in the description field)

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

(items with yodellers anywhere in the title field)

Multiple:

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

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

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

Boolean:

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

(items with cat or dog in the title.)

Wildcard:

http://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.temporal field which is the time frame of the original physical object such as when a book was written, the period about which a book is 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 a begin year of 1930 and an end year of 1939.

Examples:

http://api.dp.la/v2/items?sourceResource.temporal.begin=1910-01-01&api_key=

(items that were created on or after 1910)

http://api.dp.la/v2/items?sourceResource.temporal.end=1869-01-01&api_key=

(items that were created on or before 1869)

http://api.dp.la/v2/items?sourceResource.temporal.begin=1910&sourceResource.temporal.end=1920&api_key=

(items that were created between 1910 & 1920)

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:

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

(items that are in or about Boston)

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

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

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

http://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 (,).

Example:

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

Examples:

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

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

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

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

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

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

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

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

Examples:

Basic:

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

Multiple:

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

No Docs:

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

Auto-Expanded:

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

Dates:

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

Geo-Distance:

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

Facet Limit (maximum 2000):

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

Examples:

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

Complex Queries

Let’s get this APIarty started.

Examples:

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

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

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

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

Sortable Fields

  • id
  • @id
  • sourceResource.id
  • sourceResource.contributor
  • sourceResource.date.begin
  • sourceResource.date.end
  • sourceResource.extent
  • sourceResource.language.name
  • sourceResource.language.iso639
  • sourceResource.format
  • sourceResource.stateLocatedIn.name
  • sourceResource.stateLocatedIn.iso3166-2
  • sourceResource.spatial.name
  • sourceResource.spatial.country
  • sourceResource.spatial.region
  • sourceResource.spatial.county
  • sourceResource.spatial.state
  • sourceResource.spatial.city
  • sourceResource.spatial.iso3166-2
  • sourceResource.spatial.coordinates
  • sourceResource.subject.@id
  • sourceResource.subject.type
  • sourceResource.subject.name
  • sourceResource.temporal.begin
  • sourceResource.temporal.end
  • sourceResource.title
  • sourceResource.type
  • hasView.@id
  • hasView.format
  • isPartOf.@id
  • isPartOf.name
  • isShownAt
  • object
  • provider.@id
  • provider.name

Facetable Fields

  • sourceResource.contributor
  • sourceResource.date.begin
  • sourceResource.date.end
  • sourceResource.language.name
  • sourceResource.language.iso639
  • sourceResource.format
  • sourceResource.stateLocatedIn.name
  • sourceResource.stateLocatedIn.iso3166-2
  • sourceResource.spatial.name
  • sourceResource.spatial.country
  • sourceResource.spatial.region
  • sourceResource.spatial.county
  • sourceResource.spatial.state
  • sourceResource.spatial.city
  • sourceResource.spatial.iso3166-2
  • sourceResource.spatial.coordinates
  • sourceResource.subject.@id
  • sourceResource.subject.name
  • sourceResource.temporal.begin
  • sourceResource.temporal.end
  • sourceResource.type
  • hasView.@id
  • hasView.format
  • isPartOf.@id
  • isPartOf.name
  • isShownAt
  • object
  • provider.@id
  • provider.name