3ft9/dpla

Provides access to the Digital Public Library of America's API.

PHP library for accessing the Digital Public Library of America API

This is a simple library for accessing the DPLA search API., _(*1)

Update on 2022-06-08: I've had an email notifying me that there have been breaking changes to the API and I can no longer state that it will work. Since I no longer use this code I won't be updating it but I'll be happy to accept pull requests., _(*2)

Basic usage

To get started you simply need to require the main DPLA class and create an instance of it, passing in your API key., _(*3)

require '/path/to/tfn/dpla.php';
$dpla = new \TFN\DPLA('your api key');

Using this object you can then create a search query. The query object supports chaining if you wish to use it. This example runs a simple search for anything mentioning pizza and gets the first page of ten results., _(*4)

$res = $dpla->createSearchQuery()->forText('pizza')->withPaging(1, 10)->execute();

As well as generic text you can also search within specific fields. This example will match anything with "pizza" in the title., _(*5)

$res = $dpla->createSearchQuery()->withTitle('pizza')->withPaging(1, 10)->execute();

See searchquery.php for full details of what's supported., _(*6)

The execute() method will return a results object which has a number of convenient methods for accessing parts of the search results., _(*7)

// Get the total number of documents that matched the search query.
$total_count = $res->getTotalCount();

// Get the page details that this results object represents.
$page = $res->getPageNumber();
$per_page = $res->getPerPage();

// Get an array of the documents in this results object.
$docs = $res->getDocuments();

It also provides convenience methods for getting the next and previous pages of results., _(*8)

$prev_page_res = $res->getPrevPage();
$next_page_res = $res->getNextPage();

You can also get the query objects for the current, previous and next pages., _(*9)

$current_query = $res->getSearchQuery();
$prev_page_query = $res->getPrevPageSearchQuery();
$next_page_query = $res->getNextPageSearchQuery();

License

This code is being put into the public domain so please use it in whatever way you need. Attribution is encouraged and welcomed but not required., _(*10)

Contributing

We welcome contributions in the form of pull requests., _(*11)

Who are we?

This code was developed and is maintained by Stuart Dallas at 3ft9 Ltd., _(*12)

The original version was heavily based on William Karavites' Java wrapper., _(*13)