Net::PMP::Client - Perl client for the Public Media Platform


 use Net::PMP::Client;
 my $host = '';
 my $client_id = 'i-am-a-client';
 my $client_secret = 'i-am-a-secret';

 # instantiate a client
 my $client = Net::PMP::Client->new(
     host   => $host,
     id     => $client_id,
     secret => $client_secret,

 # authenticate
 my $token = $client->get_token();
 if ($token->expires_in() < 10) {
     die "Access token expires too soon. Not enough time to make a request. Mayday, mayday!";
 printf("PMP token is: %s\n, $token->as_string());

 # search
 my $search_results = $client->search({ tag => 'samplecontent', profile => 'story' });  
 my $results = $search_results->get_items();
 printf( "total: %s\n", $results->total );
 while ( my $r = $results->next ) { 
     printf( '%s: %s [%s]', $results->count, $r->get_uri, $r->get_title, ) );


Net::PMP::Client is a Perl client for the Public Media Platform API (


new( args )

Instantiate a Client object. args may consist of:


Default is

id (required)

The client id. See

secret (required)

The client secret. See


Boolean. Default is off.


A LWP::UserAgent object.


Defaults to application/vnd.collection.doc+json. Change at your peril.


Internal method for object construction.


Returns the most recent HTTP::Response object. Useful for debugging client behaviour.


Returns the CollectionDoc for the API root. This object is cached for performance reasons.


Returns a Net::PMP::AuthToken object. The optional refresh boolean indicates that the Client should ignore any cached token and fetch a fresh one.

If get_home_doc() is undefined (i.e., no initial access has been attempted), then this method will return undef.

If the token will expire in less than warning_ttl seconds, the client will sleep() that long and then refresh itself. The default is 10 seconds.


Expires the currently active AuthToken.


Returns the URI for the Credentials API.

create_credentials( params )

Instantiates credentials at server. params should be a hash of key/value pairs.

username (required)
password (required)
scope (default: read)
expires (default: 86400)
label (default: null)

Returns a Net::PMP::Credentials object.

delete_credentials( params )

Deletes credentials at the server.

params should consist of:



Returns full URI for guid.


Returns full URI for profile.


Returns full URI for schema.


Issues a GET request on uri and decodes the JSON response into a Perl scalar.

If the GET request returns a 404 (Not Found) will return 0 (zero).

If the GET request returns anything other than 200, will croak.

If the GET request returns 200, will return the JSON response, decoded.

Retrieves the base doc edit link object for the API.


Write doc_object to the server. doc_object should be an instance of Net::PMP::CollectionDoc.

Returns the JSON response from the server on success, croaks on failure.

Normally you should use save() instead of put() directly, since save() optionally validates the doc_object before calling put() and makes sure there is a guid and href defined.


Remove doc_object from the server. Returns true on success, croaks on failure.

get_doc( [uri] [,tries] )

Returns a Net::PMP::CollectionDoc representing uri. Defaults to the API base endpoint if uri is omitted or false.

If uri is not found, returns 0 (zero) just like get().

The second, optional parameter tries indicates how many re-tries should be attempted when the response is a 404. This feature helps compenstate for occasional latency on the server between an initial save and subsequent read, since PUT and DELETE requests always return a 202 (accepted but not necessarily acted upon). The default is 1 try.


Like get_doc() but takes a guid as argument.

search( opts [,tries] )

Search in the 'urn:collectiondoc:query:docs' namespace.

Returns a Net::PMP::CollectionDoc object for opts. opts are passed directly to the query link URI template. See

The second, optional parameter tries is passed internally to get_doc(). See the description of get_doc().


Write doc_object to the server. doc_object may be a Net::PMP::Profile object, in which case the as_doc() method is called on it, or it may be a Net::PMP::CollectionDoc object.

Returns a Net::PMP::CollectionDoc object with its URI updated to reflect the server response.


Peter Karman, <karman at>


Please report any bugs or feature requests to bug-net-pmp at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc Net::PMP::Client

You can also look for information at:


American Public Media and the Public Media Platform sponsored the development of this module.


Copyright 2013 American Public Media Group

See the LICENSE file that accompanies this module.