gnip / gnip-perl

Welcome to the Gnip Perl convenience library!

== VERSION ==
This library complies with API version 2.1
https://api-v21.gnip.com

== Overview ==

This library provides a Perl API for accessing Gnip web services.  This library 
supports activities related to publishing and subscribing to data. Using this 
library assumes that you have an account on the server.

== Dependencies == 
Dependencies can be installed via command line or by running the install script.

= Required Dependencies =
  - perl (this lib tested with version 5.8.8)
  - DateTime
  - DateTime::Format::Strptime
  - LWP::Debug
  - LWP::UserAgent
  - libwww-perl-5.x
  - IO::Socket::SSL
  - NET::SSLeay
  

Resource links for the above dependencies can be found here:
  http://search.cpan.org/
  http://www.perl.org/
  http://cpansearch.perl.org/src/GAAS/libwww-perl-5.823/README.SSL


Note, the data that goes into / comes out of a Gnip instance
are XML documents that you must parse.  To help with detecting
error conditions, all of the functions that connect to a Gnip 
server over the network return the HTTP response status code. 

If an HTTP request is successful, the return $content could 
contain a <filters>, <activities>, or other XML document
described in Gnip.xsd.  Otherwise, $content will contain
the error XML document.

== Quick Start ==

Gnip has a test publisher "gnip-sample":
https://api-v21.gnip.com/gnip/publishers/gnip-sample/notification/

The following example retrieves notification data from the current bucket for 
gnip-sample. Please note that both the current and 0-1 minute old buckets are not 
static and therefore will contain a variable amount of data, but you'll get 
quick feedback to know if you can connect and access the public notification data.

Also note that your requests must be scoped, "gnip" for publicly accessible publishers 
and "my" for publishers you own.

    my $gnip = new Gnip(<your account email>, <your account pw>);
    ($response) = $gnip->get_notifications('gnip-sample, 'gnip');
    print $response;
    
You should see xml notification data from the current time bucket.

=Testing Tips=
Tests are provided in GnipTester.pl and in addition to 
testing also show basics of using the Gnip API. To execute the tests,
run:
  
% perl GnipTester.pl -user <your account email> -pass <your account pw> -publisher gnip-sample
  
Docstrings are also included for each method.

==== Subscriber Actions ====

=== Notification vs. Activity ===

As a subscriber you can retrieve notification data or activity data. The main 
difference between these two types of data buckets are:

*** Notifications contain a reduced meta-data subset of attributes for an activity
*** Activities contain full data, including the raw payload. There are some 
    restrictions on activity data. You can only request unfiltered activities 
    on publishers that you own (have authorization access to). You can create 
    filters on any publisher and request activity data. Some publishers do not
    authorize full data for their streams.

=== Example 1: Retrieve notifications from a publisher ===

As a consumer one thing you might be interested in immediately is
grabbing data from a publisher. To do this you must create a connection to Gnip 
using your username and password.  Once the connection is established you can 
get the publisher and request the stream. These examples uses the publisher 
"gnip-sample".

*** Notification data stream request ***

    my $gnip = new Gnip(<your account email>, <your account pw>);
    ($response) = $gnip->get_notifications('gnip-sample, 'gnip');
    print $response;

You can also view the current notifications bucket via web on the Gnip site:
    https://api-v21.gnip.com/gnip/publishers/gnip-sample/notification/current.xml
    
    
*** Notification data stream request with optional date param ***

    my $formatter = DateTime::Format::Strptime->new( pattern => '%Y-%m-%dT%H:%M:%S');
    my $twoMinutesAgo = DateTime->from_epoch( epoch => time(), formatter => $formatter )->subtract( minutes => 2);
    
    my $gnip = new Gnip(<your account email>, <your account pw>);
    ($response) = $gnip->get_notifications('gnip-sample, 'gnip', $twoMinutesAgo);
    print $response;

You can see the running list of notification buckets on the Gnip site:
    https://api-v21.gnip.com/gnip/publishers/gnip-sample/notification/
    
=== Example 2: Filter notifications or activities by a set of users ===

You can create a filter to stream activity data for the users you care about. 
Posts from the users that have already occurred will not be included in a 
filter. Therefore any new filter you create will be empty until the users you 
specify perform an action (make a tweet, digg a story, create a bookmark in 
delicious, etc.). 

You can only retrieve activity data (full data) from publishers that you don't own 
by creating a filter.

The test actor for "gnip-sample" is "jvaleski". To test your filter, be sure 
"jvaleski" appears in your rule set.

The following examples illustrate creating filters for both notification and activity 
data. Additionally, the two examples show how to use/not use the post URL parameter.

*** Notificiation Filter without POST URL ***

Note that the full data in your formatted XML for the filter must be set to 
false. This example does not include a POST Url, meaning you'll have to poll 
Gnip for the results when you need them. The following snippet creates (and 
retrieves) a notification filter called "myNotificationFilter" on the publisher 
gnip-sample.

    my $gnip = new Gnip(<your account email>, <your account pw>);

    $filter_xml = 
        '<filter name="myNotificationFilter" fullData="false">'.
            '<rule type="actor">jvaleski</rule>'.
            '<rule type="actor">mary</rule>'.
            '<rule type="actor">electromute</rule>'.
        '</filter>';
    ($response) = $gnip->create_filter('gnip-sample', 'gnip', $filter_xml);
    print $response;
    
The server will return :
<result>Success</result>
    
You can view your filters by running:
    print $gnip->get_filter('gnip-sample', 'gnip', 'myNotificationFilter');

Your actors list should be (not necessarily in this order): electromute, mary, jvaleski

You can also see your filters list for each publisher by going to the Gnip site:
    https://api-v21.gnip.com/gnip/publishers/gnip-sample/filters
    
You can view notification buckets on the Gnip site by going to:
    
    https://api-v21.gnip.com/gnip/publishers/gnip-sample/filters/myNotificationFilter/notification
    
*** Activity Filter with POST URL ***

Note that the full data attribute of the filter XML must be set to 
true to view activity data. This example includes the optional POST Url, 
meaning Gnip will POST via an HTTP HEAD request to this URL. The following 
snippet creates (and gets) an activity filter called "myActivityFilter" on 
the publisher gnip-sample. 

If you want activities to be sent to a script on your server for processing, 
you must ensure that the postURL parameter you set responds successfully to an 
HTTP HEAD request. (note that this example will throw an error because the POST 
url is invalid).

    my $gnip = new Gnip(<your account email>, <your account pw>);

    $filter_xml = 
        '<filter name="myNotificationFilter" fullData="true">'.
            '<rule type="actor">jvaleski</rule>'.
            '<rule type="actor">mary</rule>'.
            '<rule type="actor">electromute</rule>'.
        '</filter>';
    ($response) = $gnip->create_filter('gnip-sample', 'gnip', $filter_xml);
    print $response;
    
You can view your filters by running:
    print $gnip->get_filter('gnip-sample', 'gnip', 'myActivityFilter');

You can see your filters by going to the Gnip site:
    https://api-v21.gnip.com/gnip/publishers/gnip-sample/filters
Your actors list should be (not necessarily in this order): electromute, mary, jvaleski

Once data is available, you can see it here:
    https://api-v21.gnip.com/gnip/publishers/gnip-sample/activity
    
=== Example 3: Add rules to an existing filter ===

You can add rules later to an existing filter. The following code snippet adds 
two new rules to the notification filter we created above, myNotificationFilter. 
There are two ways to modify an existing filter, you can overwrite it or add rules using
the batch endpoint (better for large rulesets or large filters).


    my $gnip = new Gnip(<your account email>, <your account pw>);

    $filter_xml = 
        '<filter name="myNotificationFilter" fullData="true">'.
        '<rule type="actor">jvaleski</rule>'.
        '<rule type="actor">mary</rule>'.
        '<rule type="actor">electromute</rule>'.
        '<rule type="actor">sam</rule>'.
        '<rule type="actor">judy</rule>'.
    '</filter>';
    ($response) = $gnip->overwrite_filter('gnip-sample', 'gnip', 'myNotificationFilter', $filter_xml);
    print $response;

Your actors list should be (not necessarily in this order): mary, electromute, sam, jvaleski, judy


Adding rules in large batches is the fastest way to augment an existing Filter, and 
for Filters that already contain large rule sets, batch additions must be used to 
change the Filter.  Here's an example of a batch add:

    my $gnip = new Gnip(<your account email>, <your account pw>);
    $batch_rules =
        '<rules>'.
            '<rule type="actor">andrewhyde</rule>'.
            '<rule type="actor">bpm140</rule>'.
            '<rule type="actor">penguin</rule>'.
       '</rules>';
    ($response) = $gnip->add_batch_rules('gnip-sample, 'gnip', 'myNotificationFilter', $batch_rules);
    print $response;

If the server receives the message successfully, you should receive an HTTP response code 
of 200 and a message of "Success".  Note, Gnip processes rule addition asynchronously, so 
there may be a delay beteween completion of the request and Gnip's finishing adding rules
to the Filter.  
    
You can test if a rule already exists by calling:

    my $gnip = new Gnip(<your account email>, <your account pw>);
    ($response) = $gnip->get_rule('gnip-sample', 'gnip', 'myNotificationFilter', 'actor', 'jvaleski');
    print $response;
    
You should get <rule type="actor">jvaleski</rule>

If you like, you can delete the rule:
    
    my $gnip = new Gnip(<your account email>, <your account pw>);
    ($response) = $gnip->delete_rule('gnip-sample', 'gnip', 'myNotificationFilter', 'actor', 'penguin');
    print $response;

You should get a response message of "Success".  

=== Example 4: Delete a filter ===

Filters can be easily deleted. The following code sample deletes the filter 
that was created above:

    my $gnip = new Gnip(<your account email>, <your account pw>);
    ($response) = $gnip->get_filter('gnip-sample', 'gnip', 'myNotificationFilter');
    print $response;
    
You should get a response message of "Success".
    
=== Example 5: Retrieve activities from a publisher ===

*** Activity Data Stream Request ***

NOTE: You must create a filter (see Example 2 above) before you can view 
activities for a publisher that you do not own.

    my $gnip = new Gnip(<your account email>, <your account pw>);
    ($response) = $gnip->get_filter_activities('gnip-sample, 'gnip', 'myActivityFilter');
    print $response;

You can also view the current activity bucket via web on the Gnip site:
    https://api-v21.gnip.com/gnip/publishers/gnip-sample/filters/myActivityFilter/activity/current.xml

*** Activity Data Stream Request with Date Param ***

NOTE: You must create a filter (see Example 3 below) before you can view 
activities for a publisher that you do not own.

    my $formatter = DateTime::Format::Strptime->new( pattern => '%Y-%m-%dT%H:%M:%S');
    my $twoMinutesAgo = DateTime->from_epoch( epoch => time(), formatter => $formatter )->subtract( minutes => 2);
    
    my $gnip = new Gnip(<your account email>, <your account pw>);
    ($response) = $gnip->get_filter_activities('gnip-sample, 'gnip', 'myActivityFilter', $twoMinutesAgo);
    print $response;

You can see the running list of activity buckets on the Gnip site:
    https://api-v21.gnip.com/gnip/publishers/gnip-sample/filters/myActivityFilter/activity/


==== Publisher Actions ====

In order to utilize the publisher API, you must first create a publisher. The 
publisher name should be descriptive to you. Currently publishers you create
are private to your account only, and fall under the "my" scope.

Publishers must have one or more rule types specified so that filters can be 
created based on the rule types. The following rule types are supported by 
Gnip:
    Actor 
    To
    Regarding
    Source
    Tag
    
=== Example 1: Create a publisher
    
    my $publisher_xml =
        '<publisher name="myPublisher">'.
            '<supportedRuleTypes>'.
                '<type>actor</type>'.
                '<type>tag</type>'.
            '</supportedRuleTypes>'.
        '</publisher>';
        
    my $gnip = new Gnip(<your account email>, <your account pw>);
    ($response) = $gnip->create_publisher($publisher_xml);
    print $response;
    
You should see a response message of "Success".

=== Example 2: Updating a publisher

The following example takes an existing publisher and updates it with a new set 
of supported rule types.
    
    my $publisher_xml =
        '<publisher name="myPublisher">'.
            '<supportedRuleTypes>'.
                '<type>actor</type>'.
                '<type>to</type>'.
            '</supportedRuleTypes>'.
        '</publisher>';
        
    my $gnip = new Gnip(<your account email>, <your account pw>);
    ($response) = $gnip->overwrite_publisher("myPublisher", $publisher_xml);  
    
    You should see a response message of "Success".

=== Example 3: Publishing activities

Here is how you can publish activities to the activity stream. You'll want to review the
Gnip xsd for specifics on what is required/optional. This is a very stripped down version of
what can be published.

https://api-v21.gnip.com/schema/gnip.xsd


    my $formatter = DateTime::Format::Strptime->new( pattern => '%Y-%m-%dT%H:%M:%S.000Z' );
    my $currentTimeString =  DateTime->from_epoch( epoch => time(), formatter => $formatter );
    
    my $xml = 
    '<activities publisher="myPublisher">'.
        '<activity>'.
            '<at>'.$currentTimeString.'</at>'.
            '<action>ping</action>'.
            '<activityID>12345</activityID>'.
            '<URL>http://www.gnip.com</URL>'.
            '<source>web</source>'.
            '<place><featurename>Boulder, CO</featurename></place>'.
            '<actor uid="455969" metaURL="http://gnip.com/people/electromute">electromute</actor>'.
            '<payload><title>Testing Pearl</title><raw>base64encoded string</raw></payload>'.
        '</activity>'.
    '</activities>';
                                           
      
    my $gnip = new Gnip(<your account email>, <your account pw>);                                      
    ($response) = $gnip->publish("myPublisher", $xml);
    print $response;
    
You should see a response message of "Success".

=== Example 4: Deleting a publisher

You can delete a publisher that you own. This is most useful for testing purposes.

    my $gnip = new Gnip(<your account email>, <your account pw>);
    ($response) = $gnip->delete_publisher("myPublisher");
    print $response;
    
You should see a response message of "Success".

=== Contributing ===
 
Contributions to this library are welcome.
 
Source :: git://github.com/gnip/gnip-perl.git
Community Site :: http://groups.google.com/group/gnip-community
Mailing List :: gnip-community@googlegroups.com
Twitter Status :: @gnipsupport
 
To get started create a clone of the main repository,
<git://github.com/gnip/gnip-perl.git>, and start improving it. Feel
discuss any changes you are making on the mailing list to get feedback 
from the other users. Once you are ready to publish your changes
you can send them to the mailing list or, if you are using GitHub,
send a pull request to the owner of the main repositiory.