The content on this wiki is being preserved for historical purposes, but is not being maintained and is probably no longer accurate.
For current information about DPLA Development, see the Development Portal
For latest API documentation, see the API documentation
Version 0.02 API Documentation
Contents |
Base URI for the Item type
http://api.dp.la/dev/item/
Basic Query
Basic queries to DPLA include the field you want to search against and your query term:
| Parameter name | Parameter description |
|---|---|
| search_type | The field you want to search against |
| query | The query term you're interested in |
A basic query might look something like this:
http://api.dp.la/dev/item/?search_type=keyword&query=internet
Base Fields
| Field name | Field description |
|---|---|
| keyword | Almost all of a record's fields get copied to this field |
| title | The title and/or subtitle of the item. Exact matching. |
| title_keyword | The title and/or subtitle of the item. Keyword matching. |
| creator | The creator(s), contributor(s), editor(s), etc. of the item. Exact matching |
| creator_keyword | The creator(s), contributor(s), editor(s), etc. of the item. Keyword matching |
| date | The item's date of publication. |
| description | The item's description. This often includes the item's Table of Contents. Exact matching. |
| description_keyword | The item's description. This often includes the item's Table of Contents. Keyword matching. |
| subject | A catchall for subject information. LCSH, Dewey, and other tag related fields are copied to this field. Exact matching. |
| subject_keyword | A catchall for subject information. LCSH, Dewey, and other tag related fields are copied to this field. Keyword matching. |
| publisher | The name of the publisher. Exact matching. |
| language | The primary language of the item. Exact matching. |
| id_isbn | The item's ISBN. Exact matching. |
| id_oclc | The item's OCLC identifier. Exact matching. |
| id_lccn | The item's LCCN. Exact matching. |
| id_inst | The identifier supplied by the partner. This is usually the partner's internal unique identifier for the item. Exact matching. |
| call_num | The item's call number. Exact matching. |
| height | The item's physical height. Exact matching. |
| page_count | The number of pages contained in the item. Exact matching. |
| relation | A link to a related resource. Exact matching. |
| content_link | A link to the item's content. Exact matching. |
| rights | Copyright/usage description. Exact matching. |
| data_source | The contributing partner. Exact matching. |
| resource_type | The resource's type. Common values include item and collection. Exact matching. |
A search for subjects containing the term computer networks might look something like this:
http://api.dp.la/dev/item/?search_type=subject_keyword&query=computer networks
Fields common to all DPLA records
A number of handy DPLA system related fields exist in every record in DPLA:
| Parameter name | Parameter description |
|---|---|
| id | Each item in DPLA is given a unique identifier. |
| data_source | The unique name of the partner that supplied the record. These field values usually take the form of the partner's domain name. e.g. example_edu, library_example_org |
| dataset_tag | Each record loaded into DPLA is loaded in a batch. This field is a unique identifier common to all records loaded in the batch. |
A search for all items contributed by example.edu might look like this:
http://api.dp.la/dev/item/?search_type=data_source&query=example_edu
Faceting and Filtering
The API allows filtering and faceting on almost all fields:
| Parameter name | Parameter description |
|---|---|
| facet | The field you want to facet on |
| facet_limit_fieldname | The default facet return set size is 100. You can limit that on a per field basis by using this parameter. (Substitute fieldname for the name of your field) |
| filter | You can narrow queries by using filters. Syntax looks like this: fieldname:filter (example: language:English) |
A search for items containing the term internet, faceting on subject might look like this:
http://api.dp.la/dev/item/?search_type=keyword&query=internet&facet=subject
Let's give filtering a go:
A search for items containing the term internet, faceting on search subject, limiting ourselves to the records supplied by Example.edu, might look like this:
http://api.dp.la/dev/item/?search_type=keyword&query=internet&facet=subject&filter=data_source:example_edu
Controls
Common API controls are available:
| Parameter name | Parameter description |
|---|---|
| limit | Number of records to return |
| start | The starting point in the result set |
A search for items containing the term internet, limiting the return number 10, starting at record 30:
http://api.dp.la/dev/item/?search_type=keyword&query=internet&limit=10&start=30
