Skip to content
Perl module for communicating with News API (
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Build Status


This Perl 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.


use Web::NewsAPI;
use v5.10;

# To use this module, you need to get a free API key from
# (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;


This module's most recent release is on CPAN! Your best bet is to install it via the CPAN installation tool of your choice.

For example, if you have cpanminus installed on your system:

cpanm Web::NewsAPI

(And if you don't have cpanminus, maybe install cpanminus? It's likely available through your favorite package manager.)

To instead install it from source, run these commands:

perl Build.PL
perl Build build
perl Build install # run under sudo to install at system-level


For full programmer documentation, see Web::NewsAPI.


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!


Jason McIntosh (

Copyright and licence

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

This is free software, licensed under:

The MIT (X11) License

A personal request

My ability to share and maintain free, open-source software like this depends upon my living in a society that allows me the free time and personal liberty to create work benefiting people other than just myself or my immediate family. I recognize that I got a head start on this due to an accident of birth, and I strive to convert some of my unclaimed time and attention into work that, I hope, gives back to society in some small way.

Worryingly, I find myself today living in a country experiencing a profound and unwelcome political upheaval, with its already flawed democracy under grave threat from powerful authoritarian elements. These powers wish to undermine this society, remolding it according to their deeply cynical and strictly zero-sum philosophies, where nobody can gain without someone else losing.

Free and open-source software has no place in such a world. As such, these autocrats' further ascension would have a deleterious effect on my ability to continue working for the public good.

Therefore, if you would like to financially support my work, I would ask you to consider a donation to one of the following causes. It would mean a lot to me if you did. (You can tell me about it if you'd like to, but you don't have to.)

You can’t perform that action at this time.