= Gnip Client


This library provides a Ruby API for accessing
{Gnip}[http://gnipcentral.com] web services.  There are two basic
roles for using Gnip: subscribers and publishers.  This library
provides a single API for both roles.

== Consumer

=== Example 1: Retrieve all recent activities for a publisher

As a consumer one thing you might be interested in immediately is to
grab recent activity at a particular publisher.  To do this you must
create a connection to Gnip using your user name and password.  Once
that connection is established you can get the publisher and request
it's activities stream.  

    require 'rubygems'
    require 'gnip' 

    gnip = Gnip::Connection.new(Gnip::Config.new("me@mydomain.com", "my-password"))

    _,digg = gnip.get_publisher('digg')
    activities = gnip.publisher_activities_stream(digg)


=== Example 2: Retrieve all activities for a publisher around a specific time

Some times you will want to get activity information from before now.
Doing this look much like getting the recent activity, except that you
past a time when getting the activity stream.  This will return the
activity stream as it existed around that time.  The results will be
include some activities before and after the time you specify.

    require 'rubygems'
    require 'gnip' 

    gnip = Gnip::Connection.new(Gnip::Config.new("me@mydomain.com", "my-password"))

    _,digg = gnip.get_publisher('digg')
    activities = gnip.publisher_activities_stream(digg, Time.now - 3600)  # 1 hour ago


=== Example 3: Create an activity stream that includes only activities
    done by users you care about.

If you would like to filter a set of publishers by the user that
performed the activity you may create a filter to do so.  Once
created a filter's activity stream is retrieved much like a
publishers.  Activity that has already occured will not be included in
a filter.  Therefore any new filter will be empty until some
new matching activity has occured.


    require 'rubygems'
    require 'gnip' 

    gnip = Gnip::Connection.new(Gnip::Config.new("me@mydomain.com", "my-password"))

    digg = Gnip::Publisher.new('digg')
    my_filter = Gnip::Filter.new('my-filter')
    my_filter.addRule(Gnip::Rule.new('actor', 'Burento')

    gnip.create(digg,my_filter)
    
    _,publisher,activities = gnip.activities_stream(my_filter)

=== Example 4: Delete a filter

If you decide you no longer need a filter you have created in the
past you can remove it.

    require 'rubygems'
    require 'gnip' 

    gnip = Gnip::Connection.new(Gnip::Config.new("me@mydomain.com", "my-password"))
    digg = Gnip::Publisher.new('digg')
    _,my_filter = gnip.get_filter(digg,"my-filter")

    gnip.remove_filter(my_filter)

== Publisher

=== Example 1: Create a publisher and publish some activities

If you are interested in publishing activity you will need to create a
publisher.  Once the publisher resource is created, activities can be
published in it's activity stream.

    require 'rubygems'
    require 'gnip' 

    gnip = Gnip::Connection.new(Gnip::Config.new("me@mydomain.com", "my-password"))

    my_publisher = Gnip::Publisher.new('myservice')

    gnip.create(my_publisher)
    
    gnip.publish(my_publisher, 
                 [Gnip::Activity.new('joe', 'post', Time.now, 'http://mydomain.com/joe/my-new-blog-post')])


== Contributing

Contributions to this library are welcome.

Source         :: git://github.com/gnip/gnip-ruby.git
Community Site :: {gnip-community}[http://groups.google.com/group/gnip-community]
Mailing List   :: gnip-community@googlegroups.com

To get started create a clone of the main repository,
<git://github.com/gnip/gnip-ruby.git>, and start improving it.  Feel
discuss any changes you are making on the mailing list to get feed
back 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.