/ 
WebService-Antigate-0.02
River stage zero No dependents
/ WebService::Antigate

NAME

WebService::Antigate - Recognition of captches using antigate.com service (former anti-captcha.com)

SYNOPSIS

Simplest variant
use WebService::Antigate;

my $recognizer = WebService::Antigate->new(key => 'd41d8cd98f00b204e9800998ecf8427e');

my $captcha = $recognizer->upload_and_recognize(file => "/tmp/Captcha.jpeg")
      or die $recognizer->errstr;

print "Recognized captcha is: ", $captcha, "\n";
More control
use WebService::Antigate;

my $recognizer = WebService::Antigate->new(key => 'd41d8cd98f00b204e9800998ecf8427e', attempts => 25);

my $id = $recognizer->upload(file => '/tmp/Captcha.jpeg');
unless($id)
{
      die "Error while uploading captcha: ", $recognizer->errno, " (", $recognizer->errstr, ")";
}

my $captcha = $recognizer->recognize($id);
unless($captcha)
{
      die "Error while recognizing captcha: ", $recognizer->errno, " (", $recognizer->errstr, ")";
}

print "Recognized captcha is: ", $captcha, "\n";
Control all operations yourself
use WebService::Antigate;

my $recognizer = WebService::Antigate->new(key => 'd41d8cd98f00b204e9800998ecf8427e');

# will use captcha from variable, not from file for this example
my $captcha_img = $recognizer->ua->get('http://some-site.com/captcha.php?id=4')->content;

my $id;
until($id = $recognizer->try_upload(content => $captcha_img))
{
      warn "not uploaded yet: ", $recognizer->errno;
      sleep 5;
}

my $captcha;
until($captcha = $recognizer->try_recognize($id))
{
      warn "not recognized yet: ", $recognizer->errno;
      sleep 5;
}

print "Recognized captcha is: ", $captcha, "\n";

DESCRIPTION

The WebService::Antigate is a class for captcha text recognition. It uses the API of antigate.com service. You have to register with antigate.com to obtain you private key. Thereafter you can upload captcha image to this service using this class and receive captcha text already recognized. Be aware not to use this service for any illegal activities.

METHODS

WebService::Antigate->new( %options )

This method constructs new object WebService::Antigate. Key / value pairs can be passed as an argument to specify the initial state. The following options correspond to attribute methods described below:

KEY                  DEFAULT                                           OPTIONAL
-----------          --------------------                              ---------------
key                   undef                                            NO
ua                    LWP::UserAgent->new                              yes
domain                $WebService::Antigate::DOMAIN = 'antigate.com'   yes
wait                  $WebService::Antigate::WAIT = 220                yes
attempts              undef                                            yes
delay                 $WebService::Antigate::DELAY = 5                 yes

Options description:

key      - your service private key, which can be found here: http://antigate.com/panel.php?action=api
ua       - LWP::UserAgent object used to upload captcha and receive the result (captcha recognition)
domain   - current domain of the service, can be changed in the future
wait     - maximum waiting time until captcha will be accepted  ( upload() ) or recognized ( recognize() ) by the service
delay    - delay time before next attempt of captcha uploading or recognition after previous failure
attempts - maximum number of attempts that we can try_upload() or try_recognize()

If you specify `wait' and `attempts' options at the same time, than class will try to upload/recognize until time or attempts will over (which first). If you do not specify neither `wait', nor `attempts', than default value of `wait' will be used.

$recognizer->key
$recognizer->key($key)

This method gets or sets your service private key.

$recognizer->ua
$recognizer->ua($ua)

This method gets or sets an LWP::UserAgent object associated with class. Thus we can configure this object: set proxy, etc. See LWP::UserAgent for details.

Example:

$recognizer->ua->proxy(http => 'http://localhost:8080');
$recognizer->domain
$recognizer->domain($domain)

This method gets or sets the domain of the service.

$recognizer->wait
$recognizer->wait($time)

This method gets or sets maximum waiting time. See above.

$recognizer->delay
$recognizer->delay($time)

This method gets or sets delay time before next attempt. See above.

$recognizer->attempts
$recognizer->attempts($attempts)

This method gets or sets maximum number of attempts. See above.

$recognizer->errno

This method gets an error from previous unsuccessful operation. The Error is returned as a string constant associated with this error type.

$recognizer->errstr

This method gets an error from previous unsuccessful operation. The Error is returned as a string which describs the problem.

$recognizer->try_upload(%options)

This method tries to upload captcha image to the service. Here you can use the following settings:

KEY            DEFAULT       DESCRIPTION
----------     ----------    ------------
file            undef        path to the file with captcha
content         undef        captcha content
name            undef        represented name of the file with captcha
phrase          0            1 if captcha text have 2-4 words
regsense        0            1 if that captcha text is case sensitive
numeric         0            1 if that captcha text contains only digits, 2 if captcha text have no digits
calc            0            1 if that digits on the captcha should be summed up
min_len         0            minimum length of the captcha text (0..20)
max_len         0            maximum length of the captcha text (0..20), 0 - no limits

You must specify either `file' option or `content'. Other options are facultative. If you want to upload captcha from variable (`content' option) instead from file you must specify the name of the file with `name' option. Otherwise $WebService::Antigate::FNAME will be used as captcha name. You also can change file name with `name' option if you uploading captcha from file. On success captcha id is returned. On failure returns undef and sets errno and errstr.

$recognizer->upload(%options)

This method attempts to upload a captcha image to the service until exceeds allotted time limit or attempts or a captcha will not be uploaded. The parameter %options is identical with the one in method try_upload(). On success will return captcha id. On failure returns undef and sets errno and errstr.

$recognizer->try_recognize($captcha_id)

This method tries to recognize captcha with id $captcha_id - value returned by method upload() or try_upload(). On success will return recognized captcha text. On failure returns undef and sets errno and errstr.

$recognizer->recognize($captcha_id)

This method tries to recognize captcha as it does method try_recognize() but will make attempts until time limit or attempts exceeds or captcha will be recognized. On success will return recognized captcha text. On failure returns undef and sets errno and errstr.

$recognizer->upload_and_recognize(%options)

This method uploads and recognizes captcha in one step. It is easier but less flexible. Parameter %options is identical with the one in method try_upload(). On success will return recognized captcha text. On failure returns undef and sets errno and errstr.

$recognizer->abuse($captcha_id)

This method sends a message to the service that captcha with $captcha_id was recognized incorrectly. On success will return a true value. On failure returns undef and sets errno and errstr.

$recognizer->balance()

This method gets user balance. On success will return user balance as a float number. On failure returns undef and sets errno and errstr.

PACKAGE VARIABLES

$WebService::Antigate::DOMAIN = 'antigate.com'; # service domain often changes because of the abuse

$WebService::Antigate::WAIT = 220; # default time that recognize() or upload() can work

$WebService::Antigate::DELAY = 5; # sleep time before retry while uploading or recognizing captcha

$WebService::Antigate::FNAME = 'captcha.jpg'; # default name of the uploaded captcha if uploading from the variable used

SEE ALSO

LWP::UserAgent

COPYRIGHT

Copyright 2010 Oleg G <oleg@cpan.org>.

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