NAME

WWW::Kickstarter - Retrieve information from Kickstarter

VERSION

Version 1.14.0

SYNOPSIS

   use WWW::Kickstarter;

   my $email    = '...';  # Your Kickstarter login credentials
   my $password = '...';

   my $ks = WWW::Kickstarter->new();
   my $myself = $ks->login($email, $password);

   my $iter = $ks->projects_ending_soon();
   while (my ($project) = $iter->get()) {
      print($project->name, "\n");
   }

DESCRIPTION

This distribution provides access to Kickstarter's private API to obtain information about your account, other users and projects.

CONSTRUCTOR

new

   my $ks = WWW::Kickstarter->new(%opts);

This is the starting point to using the API, after which you much login using the $ks->login method documented immediately below.

Options:

  • agent => "application_name/version "

    The string to pass to Kickstarter in the User-Agent HTTP header. If the string ends with a space, the name and version of this library will be appended, as will the name of version of the underling HTTP client.

  • impolite => 1

    This module throttles the rate at which it sends requests to Kickstarter. It won't place another request until $X seconds has passed since the last request, where $X is the amount of time taken to fulfill the last request, but at most 4 seconds.

    impolite => 1 disables the throttling.

  • http_client_class => $class_name

    The class to use instead of WWW::Kickstarter::HttpClient::Lwp as the HTTP client. For example, this would allow you to easily substitute Net::Curl for LWP::UserAgent. See WWW::Kickstarter::HttpClient for documentation on the interface the replacement class needs to provide.

  • json_parser_class => $class_name

    The class to use instead of WWW::Kickstarter::JsonParser::JsonXs as the JSON parser. For example, this would allow you to easily substitute JSON::PP for JSON::XS. See WWW::Kickstarter::JsonParser for documentation on the interface the replacement class needs to provide.

ACCESSORS

my_id

   my $user_id = $ks->my_id;

Returns the id of the logged-in user.

API CALLS

login

   my $myself = $ks->login($email, $password);

You must login using your standard Kickstarter credentials before you can query the API.

Returns a WWW::Kickstarter::Data::User::Myself object for the user that logged in.

myself

   my $myself = $ks->myself();

Fetches and returns the logged-in user as a WWW::Kickstarter::Data::User::Myself object.

my_notification_prefs

   my @notification_prefs = $ks->my_notification_prefs();

Fetches and returns the the logged-in user's notification preferences of backed projects as WWW::Kickstarter::Data::NotificationPref objects. The notification preferences for the project created last is returned first.

my_projects_created

   my @projects = $ks->my_projects_created();

Fetches and returns the projects created by the logged-in user as WWW::Kickstarter::Data::Project objects. The project created last is returned first.

my_projects_backed

   my $projects_iter = $ks->my_projects_backed(%opts);

Returns an iterator that fetches and returns the projects backed by the logged-in user as WWW::Kickstarter::Data::Project objects. The most recently backed project is returned first.

Note that some projects may be returned twice. This happens when the data being queried changes while the results are being traversed.

Options:

  • page => $page_num

    If provided, the pages of results before the specified page number are skipped.

my_projects_starred

   my $projects_iter = $ks->my_projects_starred(%opts);

Returns an iterator that fetches and returns the projects starred by the logged-in user as WWW::Kickstarter::Data::Project objects. The most recently starred project is returned first.

Note that some projects may be returned twice. This happens when the data being queried changes while the results are being traversed.

Options:

  • page => $page_num

    If provided, the pages of results before the specified page number are skipped.

user

   my $user = $ks->user($user_id);

Fetches and returns the specified user as a WWW::Kickstarter::Data::User object.

Note that the argument must be the user's numerical id (as returned by $user->id).

user_projects_created

   my @projects = $ks->user_projects_created($user_id);

Fetches and returns the projects created by the specified user as WWW::Kickstarter::Data::Project objects. The project created last is returned first.

Note that the argument must be the user's numerical id (as returned by $user->id).

project

   my $project = $ks->project($project_id);
   my $project = $ks->project($project_slug);

Fetches and returns the specified project as a WWW::Kickstarter::Data::Project object.

The argument may be the project's numerical id (as returned by $project->id) or its "slug" (as returned by $project->slug).

project_rewards

   my @rewards = $ks->project_rewards($project_id);
   my @rewards = $ks->project_rewards($project_slug);

Fetches and returns the rewards of the specified project as WWW::Kickstarter::Data::Reward objects.

The argument may be the project's numerical id (as returned by $project->id) or its "slug" (as returned by $project->slug).

projects

   my $projects_iter = $ks->projects(%opts);

Returns an iterator that fetches and returns all Kickstarter projects as WWW::Kickstarter::Data::Project objects.

Note that some projects may be returned twice, and some might be skipped. This happens when the data being queried changes while the results are being traversed.

Options:

  • q => $search_terms

    Limits the projects returned to those matching the string of search terms.

  • category => $category_id

  • category => $category_slug

  • category => $category_name

    Limits the projects returned to those of the specified category (or one of its subcategories).

  • tag => $tag_id

  • tag => $tag_slug

    Limits the projects returned to those with the specified tag.

    The list of tags available changes often. I don't know of an API endpoint that returns a list of available tags, but you can find some of them on Kickstarter's Advanced Discover page. See WWW::Kickstarter::Data::Tags for the list of tags known to exist at the time of this writing.

  • location => $woe_id

    Limits the projects returned to those associated with the specified location.

  • backed_by_self => 1

    Limits the projects returned to those backed by the logged-in user.

  • starred_by_self => 1

    Limits the projects returned to those starred by the logged-in user.

  • backed_by_friends => 1

    Limits the projects returned to those backed by friends of the logged-in user.

  • picked_by_staff => 1

    Limits the projects returned to those recommended by Kickstarter.

  • state => 'live'

  • state => 'successful'

    Limits the projects returned to those with the specified state.

    The empty string and the string all are accepted as equivalent to not providing the option at all.

  • goal => $goal_range_id

    Limits the projects returned to those which have a goal that falls within the specified range. The ranges are defined as follows:

    • 0: ≤$1k

    • 1: >$1k and ≤$10k

    • 2: >$10k and ≤$100k

    • 3: >$100k and ≤$1M

    • 4: >$1M

    The empty string and the string all are accepted as equivalent to not providing the option at all.

  • pledged => $pledged_range_id

    Limits the projects returned to those to which the amount pledged falls within the specified range. The ranges are defined as follows:

    • 0: ≤$1k

    • 1: >$1k and ≤$10k

    • 2: >$10k and ≤$100k

    • 3: >$100k and ≤$1M

    • 4: >$1M

    The empty string and the string all are accepted as equivalent to not providing the option at all.

  • raised => $raised_range_id

    Limits the projects returned to those to which the amount pledged falls within the specified range. The ranges are defined as follows:

    • 0: <75%

    • 1: 75% to 100%

    • 2: >100%

    The empty string and the string all are accepted as equivalent to not providing the option at all.

  • sort => 'magic' (default)

  • sort => 'end_date'

  • sort => 'newest'

  • sort => 'launch_date'

  • sort => 'popularity'

  • sort => 'most_funded'

    Controls the order in which the projects are returned.

  • page => $page_num

    If provided, the pages of results before the specified page number are skipped.

   my $projects_iter = $ks->projects_recommended(%opts);

Returns an iterator that fetches and returns recommended projects as WWW::Kickstarter::Data::Project objects.

It accepts the same options as projects.

projects_ending_soon

   my $projects_iter = $ks->projects_ending_soon(%opts);

Returns an iterator that fetches and returns projects ending soon as WWW::Kickstarter::Data::Project objects. The project closest to its deadline is returned first.

It accepts the same options as projects.

projects_recently_launched

   my $projects_iter = $ks->projects_recently_launched(%opts);

Returns an iterator that fetches and returns recently launched projects as WWW::Kickstarter::Data::Project objects. The most recently launched project is returned first.

It accepts the same options as projects.

   my $projects_iter = $ks->popular_projects(%opts);

Returns an iterator that fetches and returns popular projects as WWW::Kickstarter::Data::Project objects.

It accepts the same options as projects.

location

   my $location = $ks->location($location_id);

Fetches and returns the specified location as a WWW::Kickstarter::Data::Location object.

Note that the argument must be the location's numerical id (as returned by $location->id).

projects_near_location

   my $projects_iter = $ks->projects_near_location($location_id, %opts);

Returns an iterator that fetches and returns the projects near the specified location as WWW::Kickstarter::Data::Project objects.

The argument must be the location's id (as returned by $location->id).

It accepts the same options as projects.

category

   my $category = $ks->category($category_id);
   my $category = $ks->category($category_slug);
   my $category = $ks->category($category_name);

Fetches and returns the specified category as a WWW::Kickstarter::Data::Category object.

The argument may be the category's numerical id (as returned by $category->id), its "slug" (as returned by $category->slug) or its name (as returned by $category->name).

categories

    my $categories = $ks->categories();

Fetches and returns all the categories as a WWW::Kickstarter::Data::Categories object.

category_projects

   my $projects_iter = $ks->category_projects($category_id,   %opts);
   my $projects_iter = $ks->category_projects($category_slug, %opts);
   my $projects_iter = $ks->category_projects($category_name, %opts);

Returns an iterator that fetches and returns projects in the specified category as WWW::Kickstarter::Data::Project objects.

The argument may be the category's numerical id (as returned by $category->id), its "slug" (as returned by $category->slug) or its name (as returned by $category->name).

It accepts the same options as projects.

   my $projects_iter = $ks->category_projects_recommended($category_id,   %opts);
   my $projects_iter = $ks->category_projects_recommended($category_slug, %opts);
   my $projects_iter = $ks->category_projects_recommended($category_name, %opts);

Returns an iterator that fetches and returns the recommended projects in the specified category as WWW::Kickstarter::Data::Project objects.

The argument may be the category's numerical id (as returned by $category->id), its "slug" (as returned by $category->slug) or its name (as returned by $category->name).

It accepts the same options as projects.

ERROR REPORTING

When an API call encounters an error, it throws a WWW::Kickstarter::Error object as an exception.

GUARANTEE

Kickstarter has not provided a public API. As such, this distribution uses a private API to obtain information. The API is subject to incompatible change without notice. This has already happened, and may happen again. I cannot guarantee the continuing operation of this distribution.

KNOWN ISSUES

The following issues are known:

  • A lot of the data returned by the API has not been made available through accessors (though the data is available by accessing the object hash directly).

  • Some API calls may not have been made available.

  • Non-existent test suite.

Feel free to bug the author to work on these, or to submit a patch to one of the bug trackers listed below.

DOCUMENTATION AND SUPPORT

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

   perldoc WWW::Kickstarter

You can also find it online at these locations:

If you need help, the following are great resources:

Bugs and improvements can be reported using any of the following systems:

Using CPAN's request tracker by emailing bug-WWW-Kickstarter at rt.cpan.org
Using CPAN's request tracker at http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Kickstarter
Using GitHub's issue tracker at https://github.com/ikegami/perl-WWW-Kickstarter/issues

REPOSITORY

AUTHOR

Eric Brine <ikegami@adaelis.com>

Initial release assisted by Mark Olson's "Kickscraper" project for Ruby.

COPYRIGHT AND LICENSE

No rights reserved.

The author has dedicated the work to the Commons by waiving all of his or her rights to the work worldwide under copyright law and all related or neighboring legal rights he or she had in the work, to the extent allowable by law.

Works under CC0 do not require attribution. When citing the work, you should not imply endorsement by the author.