The Perl Advent Calendar needs more articles for 2022. Submit your idea today!


WebService::HackerNews - interface to the official HackerNews API


 use WebService::HackerNews;
 my $hn     = WebService::HackerNews->new;
 my @top100 = $hn->top_story_ids;
 my $item   = $hn->item( $top100[0] );
 my $user   = $hn->user($item->by);

 printf qq{"%s" by %s (karma: %d)\n},
        $item->title, $item->by, $user->karma;


This module provides an interface to the official Hacker News API. This is very much a lash-up at the moment, and liable to change. Feel free to hack on it and send me pull requests.

It provides a semi object-oriented interface to the API. You start off by creating an instance of WebService::HackerNews:

 $hn = WebService::HackerNews->new;

You can then call one of the methods to either get information about items or users.

An item is either a story, a job, a comment, a poll, or a pollopt. All items live in a single space, and are identified by a unique integer identifier, or id. Given an id, you can get all information for the associated item using the item() method.

A user is like an item, but represents a registered user of HackerNews. The id for a user isn't an integer, but is a username. Given a username, you can get all information for the associated user with the user() method.

Items and User are represented with classes, but where the attributes of items and users relate to further items and classes, they are represented as references to arrays of ids, rather than returning references to arrays of other objects.


As of version 0.02, this implements all of the functions listed in the official documentation for the API.


Returns a list of ids for the current top 100 stories.

 my @ids = $hn->top_story_ids;

You can then call item() to get the details for specific items.


Takes an item id and returns an instance of WebService::HackerNews::Item, which has attributes named exactly the same as the properties listed in the official doc.

 $item = $hn->item($id);
 printf "item %d has type %s\n", $item->id, $item->type;


Takes a user id and returns an instance of WebService::HackerNews::User, which has attributes named exactly the same as the user properties listed in the official doc.

 $user = $hn->user($username);
 printf "user %s has %d karma\n", $user->id, $user->karma;


Returns the max item id.


Returns two array references, which contain IDs for changed items and usernames for changed users:

 use WebService::HackerNews 0.02;

 my $hn              = WebService::HackerNews->new;
 my ($items, $users) = $hn->changed_items_and_users;


This method returns "recently changed items and users", without defining 'changed since when?'. If you want to track changes, you'd just have to poll on a regular basis.

This method is really aimed at people using Firebase streaming API.

This method was added in version 0.02, so you should specify that as the minimum version of the module, as above.


Blog post about the API.

API Documentation.



Neil Bowers <>


This software is copyright (c) 2014 by Neil Bowers <>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.