allolex / Net-NPR-Query

NAME
    NPR::Query - Query National Public Radio's NPR API service for text and
    multimedia content.

SYNOPSIS
        use NPR::Query;

        my $term = shift;

        my $apikey = "API_KEY_STRING_PROVIDED_BY_NPR";

        my $npr = NPR::Query->new(apikey => $apikey);

        my $results = $npr->search("$term");

        $npr->print_stories($results);

DESCRIPTION
        National Public Radio is the US equivalent of the BBC. In 2008, they
        opened up their site content using a web API that allows access to nearly
        all of their content going back to 1995. People who want to use the API
        are required to obtain their own API key, which can be applied for here:
        L<<a href="http://www.npr.org/api/index">http://www.npr.org/api/index</a>>.

METHODS
    new
                    Returns an NPR::Query object. Requires the API KEY passed in a hash
                    argument.

                    my $npr -> NPR::Query->new(apikey => $apikey)

    uri
                        Returns the NPR API URI.

    search
                        Requires a search term passed as a scalar argument, returns an array reference.

    list
                        Requires an NPR list ID, returns an array reference.

    query
                        Requires a query URI, returns an array reference. Use the method L<build_query()> to build your 
                        query.

    build_query
                    Returns an NPR API string to give to the browser object.

                        $npr->build_query(value => "Perl");
                        $npr->build_query(type => "list", value => "2");

                        It requires at a minimum a "value" argument in the form value => "ID|SEARCH_TERM". 
                        The default query type is 'query', the dispatcher NPR uses for searches. If you require 
                        a list, then specify type => 'list'.

    validate_fields
                    Like the name says, this validates a field string against a list of valid
                    NPR API data fields.

    fields      Returns a list of valid NPR result fields.

    field_defaults
                        Returns a comma-separated string of default values for the NPR API to output.

    apikey
                        Returns your NPR API key.

    format      Returns the desired format for NPR API output.

    change_agent
                        Sets the browser user agent string.

    browser
                        Returns the C<<WWW::Mechanize>> browser object.

    print_stories
                        Provided the output from search(), query() or list(), this method prints out a basic summary of 
                        the stories.

TODO
        Pretty much everything really. Especially tests.

COPYRIGHT
        Copyright (C) 2009 Damon Allen Davison. All rights reserved.

AUTHOR
        Damon Allen Davison <allolex@gmail.com>

LICENCE
    This library is free software, you can redistribute it and/or modify it
    under the same terms as Perl itself.