The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Web-NewsAPI-0.002
River stage one • 2 direct dependents • 2 total dependents
2 ++
/ Web::NewsAPI

NAME

Web::NewsAPI - Fetch and search news headlines and sources from News API

SYNOPSIS

 use Web::NewsAPI;
 use v5.10;

 # To use this module, you need to get a free API key from
 # https://newsapi.org. (The following is a bogus example key that will
 # not actually work. Try it with your own key instead!)
 my $api_key = 'deadbeef1234567890f001f001deadbeef';

 my $newsapi = Web::NewsAPI->new(
    api_key => $api_key,
 );

 say "Here are the top ten headlines from American news sources...";
 # This will be a Web::NewsAPI::Results object.
 my $result = $newsapi->top_headlines( country => 'us', pageSize => 10 );
 for my $article ( $result->articles ) {
    # Each is a Web::NewsAPI::Article object.
    say $article->title;
 }

 say "Here are the top ten headlines worldwide containing 'chicken'...";
 my $chicken_heds = $newsapi->everything( q => 'chicken', pageSize => 10 );
 for my $article ( $chicken_heds->articles ) {
    # Each is a Web::NewsAPI::Article object.
    say $article->title;
 }
 say "The total number of chicken-flavor articles returned: "
     . $chicken_heds->total_results;


 say "Here are some sources for English-language technology news...";
 my @sources = $newsapi->sources(
    category => 'technology',
    language => 'en'
 );
 for my $source ( @sources ) {
    # Each is a Web::NewsAPI::Source object.
    say $source->name;
 }

DESCRIPTION

This module provides a simple, object-oriented interface to the News API, version 2. It supports that API's three public endpoints, allowing your code to fetch and search current news headlines and sources.

METHODS

Class Methods

new

 my $newsapi = Web::NewsAPI->new( api_key => $your_api_key );

Object constructor. Takes a hash as an argument, whose only recognized key is api_key. This must be set to a valid News API key. You can fetch a key for yourself by registering a free account with News API at its website.

Note that the validity of the API key you provide isn't checked until this object (or one of its derivative objects) tries to send a query to News API.

Object Methods

Each of these methods will attempt to call News API using the API key you provided during construction. If the call fails, then this module will throw an exception, sharing the error code and message passed back from News API.

everything

 # Call in scalar context to get a result object.
 my $chicken_result-> = $newsapi->everything( q => 'chickens' );

 # Or call in array context to just get one page of articles.
 my @chicken_stories = $newsapi->everything( q => 'chickens' );

In scalar context, returns a Web::NewsAPI::Result object representing news articles matching the query parameters you provide. In array context, it returns one page-worth of Web::NewsAPI::Article objects (equivalent to calling "articles" in Web::NewsAPI::Result on the result object, and then discarding it).

In either case, the argument hash must contain at least one of the following keys:

q

Keywords or phrases to search for.

See the News API docs for a complete description of what's allowed here.

sources

Either a comma-separated string or an array reference of News API news source ID strings to limit results from.

See the News API sources index for a list of valid source IDs.

domains

Either a comma-separated string or an array reference of domains (e.g. "bbc.co.uk, techcrunch.com, engadget.com") to limit results from.

You may also provide any of these optional keys:

excludeDomains

Either a comma-separated string or an array reference of domains (e.g. "bbc.co.uk, techcrunch.com, engadget.com") to remove from the results.

from

Either an ISO 8601-formatted date-time string or a DateTime object representing the timestamp of the oldest article allowed.

to

Either an ISO 8601-formatted date-time string or a DateTime object representing the timestamp of the most recent article allowed.

language

The 2-letter ISO-639-1 code of the language you want to get headlines for. Possible options include ar, de, en, es, fr, he, it, nl, no, pt, ru, se, ud, and zh.

sortBy

The order to sort the articles in. Possible options: relevancy, popularity, publishedAt. (Default: publishedAt)

pageSize

The number of results to return per page. 20 is the default, 100 is the maximum.

page

Which page of results to return. The default is 1.

top_headlines

 # Call in scalar context to get a result object.
 my $top_us_headlines = $newsapi->top_headlines( country => 'us' );

 # Or call in array context to just get one page of articles.
 my @top_us_headlines = $newsapi->top_headlines( country => 'us' );

Like "everything", but limits results only to the latest articles, sorted by recency. (Note that this arguments are a little different, as well.)

In scalar context, returns a Web::NewsAPI::Result object representing news articles matching the query parameters you provide. In array context, it returns one page-worth of Web::NewsAPI::Article objects (equivalent to calling "articles" in Web::NewsAPI::Result on the result object, and then discarding it).

In either case, the argument hash must contain at least one of the following keys:

country

Limit returned headlines to a single country, expressed as a 2-letter ISO 3166-1 code. (See the News API documentation for a full list of country codes it supports.)

News API will return an error if you mix this with sources.

category

Limit returned headlines to a single category. Possible options include business, entertainment, general, health, science, sports, and technology.

News API will return an error if you mix this with sources.

sources

Either a comma-separated string or an array reference of News API news source ID strings to limit results from.

See the News API sources index for a list of valid source IDs.

News API will return an error if you mix this with country or category.

q

Keywords or a phrase to search for.

You may also provide either of these optional keys:

pageSize

The number of results to return per page (request). 20 is the default, 100 is the maximum.

page

Use this to page through the results if the total results found is greater than the page size.

sources

 my @sources = $newsapi->sources( language => 'en' );

Returns a number of Web::NewsAPI::Source objects reprsenting News API's news sources.

You may provide any of these optional parameters:

category

Limit sources to a single category. Possible options include business, entertainment, general, health, science, sports, and technology.

country

Limit sources to a single country, expressed as a 2-letter ISO 3166-1 code. (See the News API documentation for a full list of country codes it supports.)

language

Limit sources to a single language. Possible options include ar, de, en, es, fr, he, it, nl, no, pt, ru, se, ud, and zh.

NOTES AND BUGS

This is this module's first release (or nearly so). It works for the author's own use-cases, but it's probably buggy beyond that. Please report issues at the module's GitHub site. Code and documentation pull requests are very welcome!

AUTHOR

Jason McIntosh (jmac@jmac.org)

COPYRIGHT AND LICENSE

This software is Copyright (c) 2019 by Jason McIntosh.

This is free software, licensed under:

  The MIT (X11) License