NAME

Net::Twitter - Perl interface to twitter.com

VERSION

This document describes Net::Twitter version 1.17

SYNOPSIS

   #!/usr/bin/perl

   use Net::Twitter;

   my $twit = Net::Twitter->new(username=>"myuser", password=>"mypass" );

   $result = $twit->update("My current Status");

   $twit->credentials("otheruser", "otherpass");

   $result = $twit->update("Status for otheruser");

DESCRIPTION

http://www.twitter.com provides a web 2.0 type of ubiquitous presence. This module allows you to set your status, as well as review the statuses of your friends.

You can view the latest status of Net::Twitter on it's own twitter timeline at http://twitter.com/net_twitter

new(...)

You must supply a hash containing the configuration for the connection.

Valid configuration items are:

username

Username of your account at twitter.com. This is usually your email address. "user" is an alias for "username". REQUIRED.

password

Password of your account at twitter.com. "pass" is an alias for "password" REQUIRED.

useragent

OPTIONAL: Sets the User Agent header in the HTTP request. If omitted, this will default to "Net::Twitter/$Net::Twitter::Version (Perl)"

source

OPTIONAL: Sets the source name, so messages will appear as "from <source>" instead of "from web". Defaults to displaying "Perl Net::Twitter". Note: see Twitter FAQ, your client source needs to be included at twitter manually.

This value will be a code which is assigned to you by Twitter. For example, the default value is "twitterpm", which causes Twitter to display the "from Perl Net::Twitter" in your timeline.

Twitter claims that specifying a nonexistant code will cause the system to default to "from web". Some testing with invalid source codes has caused certain requests to fail, returning undef. If you don't have a code from twitter, don't set one.

clientname

OPTIONAL: Sets the X-Twitter-Client-Name: HTTP Header. If omitted, this defaults to "Perl Net::Twitter"

clientver

OPTIONAL: Sets the X-Twitter-Client-Version: HTTP Header. If omitted, this defaults to the current Net::Twitter version, $Net::Twitter::VERSION.

clienturl

OPTIONAL: Sets the X-Twitter-Client-URL: HTTP Header. If omitted, this defaults to http://x4.net/Net-Twitter/meta.xml. By standard, this file should be in XML format, as at the default location.

apiurl

OPTIONAL. The URL of the API for twitter.com. This defaults to http://twitter.com/ if not set.

apihost

apirealm

OPTIONAL: If you do point to a different URL, you will also need to set apihost and apirealm so that the internal LWP can authenticate.

apihost defaults to www.twitter.com:80.

apirealm defaults to Twitter API.

twittervision

OPTIONAL: If the twittervision argument is passed with a true value, the module will enable use of the http://www.twittervision.com API. If enabled, the show_user method will include relevant location data in its response hashref. Also, the update_twittervision method will allow setting of the current location.

credentials($username, $password, $apihost, $apiurl)

Change the credentials for logging into twitter. This is helpful when managing multiple accounts.

apirealm and apihost are optional and will default to the standard twitter versions if omitted.

http_code

Returns the HTTP response code of the most recent request.

http_message

Returns the HTTP response message of the most recent request.

STATUS METHODS

update($status)

Set your current status. This returns a hashref containing your most recent status. Returns undef if an error occurs.

update_twittervision($location)

If the twittervision argument is passed to new when the object is created, this method will update your location setting at twittervision.com.

If the twittervision arg is not set at object creation, this method will return an empty hashref, otherwise it will return a hashref containing the location data.

show_status($id)

Returns status of a single tweet. The status' author will be returned inline.

The argument is the ID or email address of the twitter user to pull, and is REQUIRED.

destroy_status($id)

Destroys the status specified by the required ID parameter. The authenticating user must be the author of the specified status.

user_timeline(...)

Returns the 20 most recent statuses posted in the last 24 hours from the authenticating user. It's also possible to request another user's timeline via the id parameter below.

Accepts an optional argument of a hashref:

id: ID or email address of a user other than the authenticated user, in order to retrieve that user's user_timeline.
since: Narrows the returned results to just those statuses created after the specified HTTP-formatted date.
since_id: Narrows the returned results to just those statuses created after the specified ID.
count: Narrows the returned results to a certain number of statuses. This is limited to 200.
page: Gets the 20 next most recent statuses from the authenticating user and that user's friends, eg "page=3".

public_timeline([12345])

This returns a hashref containing the public timeline of all twitter users. Returns undef if an error occurs.

Accepts an optional argument containing a status ID, and limits responses to only statuses greater than this ID

following_timeline(...) DEPRECATED

friends_timeline(...)

Returns the 20 most recent statuses posted in the last 24 hours from the authenticating user and that user's friends. It's also possible to request another user's friends_timeline via the id parameter below.

Accepts an optional argument hashref:

id: User id or email address of a user other than the authenticated user, in order to retrieve that user's friends_timeline.
since: Narrows the returned results to just those statuses created after the specified HTTP-formatted date.
since_id: Narrows the returned results to just those statuses created after the specified ID.
count: Narrows the returned results to a certain number of statuses. This is limited to 200.
page: Gets the 20 next most recent statuses from the authenticating user and that user's friends, eg "page=3".

following_timeline() is DEPRECATED, see note below.

replies([$page])

Returns the 20 most recent replies (status updates prefixed with @username posted by users who are friends with the user being replied to) to the authenticating user.

Accepts an optional argument for page to retrieve, which will the 20 next most recent statuses from the authenticating user and that user's friends, eg "page=3"

USER METHODS

following() DEPRECATED

friends()

This returns a hashref containing the most recent status of those you have marked as friends in twitter. Returns undef if an error occurs.

id: OPTIONAL: User id or email address of a user other than the authenticated user, in order to retrieve that user's friends.
page: Gets the 100 next most recent friends, eg "page=3".

following() is DEPRECATED, see note below.

followers()

This returns a hashref containing the timeline of those who follow your status in twitter. Returns undef if an error occurs.

featured()

This returns a hashref containing a list of the users currently featured on the site with their current statuses inline. Returns undef if an error occurs.

show_user()

Returns extended information of a single user.

The argument is a hashref containing either the user's ID or email address:

id: The ID or screen name of the user.
email: The email address of the user. If email is specified, id is ignored.

If the twittervision argument is passed to new when the object is created, this method will include the location information for the user from twittervision.com, placing it inside the returned hashref under the key twittervision.

DIRECT MESSAGE METHODS

direct_messages()

Returns a list of the direct messages sent to the authenticating user.

Accepts an optional hashref for arguments:

page: Retrieves the 20 next most recent direct messages.
since: Narrows the returned results to just those statuses created after the specified HTTP-formatted date.
since_id: Narrows the returned results to just those statuses created after the specified ID.

sent_direct_messages()

Returns a list of the direct messages sent by the authenticating user.

Accepts an optional hashref for arguments:

page: Retrieves the 20 next most recent direct messages.
since: Narrows the returned results to just those statuses created after the specified HTTP-formatted date.
since_id: Narrows the returned results to just those statuses created after the specified ID.

new_direct_message($args)

Sends a new direct message to the specified user from the authenticating user.

REQUIRES an argument of a hashref:

user: ID or email address of user to send direct message to.
text: Text of direct message.

destroy_direct_message($id)

Destroys the direct message specified in the required ID parameter. The authenticating user must be the recipient of the specified direct message.

FRIENDSHIP METHODS

follow($id) DEPRECATED

create_friend($id)

Befriends the user specified in the ID parameter as the authenticating user. Returns the befriended user in the requested format when successful.

follow is DEPRECATED, see note below.

stop_following($id) DEPRECATED

destroy_friend($id)

Discontinues friendship with the user specified in the ID parameter as the authenticating user. Returns the un-friended user in the requested format when successful.

stop_following is DEPRECATED, see note below.

relationship_exists($user_a, $user_b)

Tests if friendship exists between the two users specified as arguments.

ACCOUNT METHODS

verify_credentials()

Returns an HTTP 200 OK response code and a format-specific response if authentication was successful. Use this method to test if supplied user credentials are valid with minimal overhead.

end_session()

Ends the session of the authenticating user, returning a null cookie. Use this method to sign users out of client-facing applications like widgets.

archive()

WARNING: As of August 11th, 2008 the archive() function is no longer listed in the twitter API documentation, despite being listed in the table of contents. This method has been retained in this module, but may not function properly.

Returns 80 statuses per page for the authenticating user, ordered by descending date of posting. Use this method to rapidly export your archive of statuses.

Accepts an optional hashref for arguments:

page: Retrieves the 20 next most recent direct messages.
since: Narrows the returned results to just those statuses created after the specified HTTP-formatted date.
since_id: Narrows the returned results to just those statuses created after the specified ID.

update_location($location)

Updates the location attribute of the authenticating user, as displayed on the side of their profile and returned in various API methods.

update_delivery_device($device)

Sets which device Twitter delivers updates to for the authenticating user. $device must be one of: "sms", "im", or "none". Sending none as the device parameter will disable IM or SMS updates.

rate_limit_status

Returns the remaining number of API requests available to the authenticating user before the API limit is reached for the current hour. Calls to rate_limit_status require authentication, but will not count against the rate limit.

FAVORITE METHODS

favorites()

Returns the 20 most recent favorite statuses for the authenticating user or user specified by the ID parameter.