Net::Amazon::MechanicalTurk - Amazon Mechanical Turk SDK for Perl


Version 1.02


Configuring your access keys and web service urls.

MechanicalTurk needs access keys for authentication. If you do not specify all of the relevant attributes, The file is read from your home directory for this information.

Run the command:

    perl -MNet::Amazon::MechanicalTurk::Configurer -e configure

to help you create this file.


Module for MechanicalTurk API.

    use Net::Amazon::MechanicalTurk;

    # Create a new MechTurk client
    my $mturk = Net::Amazon::MechanicalTurk->new();

    # Create a new MechTurk client without using
    my $mturk = Net::Amazon::MechanicalTurk->new(
        serviceUrl     => '',
        serviceVersion => '2007-06-21',
        accessKey      => '1AAAAA1A1AAAAA11AA11',
        secretKey      => '1aAaAAAAAAAA+aAaAaaaaaaAAA/AAAAAA1a1aAaa'

    # Get your balance
    my $balance = $mturk->GetAccountBalance->{AvailableBalance}[0]{Amount}[0];
    print "Your balance is $balance\n";

    # CreateHIT
    my $question = "Tell me something interesting.";

    my $questionXml = <<END_XML;
    <?xml version="1.0" encoding="UTF-8"?>
    <QuestionForm xmlns="">

    my $result = $mturk->CreateHIT(
        Title       => 'Answer a question',
        Description => 'Test HIT from Perl',
        Keywords    => 'hello, world',
        Reward => {
            CurrencyCode => 'USD',
            Amount       => 0.01
        RequesterAnnotation         => 'Test Hit',
        AssignmentDurationInSeconds => 60 * 60,
        AutoApprovalDelayInSeconds  => 60 * 60 * 10,
        MaxAssignments              => 1,
        LifetimeInSeconds           => 60 * 60,
        Question                    => $questionXml

    printf "Created HIT:\n";
    printf "HITId:     %s\n", $result->{HITId}[0];
    printf "HITTypeId: %s\n", $result->{HITTypeId}[0];

    # Approve all submitted assignments
    my $hits = $mturk->GetReviewableHITsAll;
    while (my $hit = $hits->next) {
        my $hitId = $hit->{HITId}[0];
        my $assignments = $mturk->GetAssignmentsForHITAll(
            HITId => $hitId,
            AssignmentStatus => 'Submitted'
        while (my $assignment = $assignments->next) {
            my $assignmentId = $assignment->{AssignmentId}[0];
            $mturk->ApproveAssignment( AssignmentId => $assignmentId );


Most methods indicate an error condition through die or Carp::croak. This is similar to throwing an exception in other languages. To catch an error, use eval:

    eval {
    if ($@) { # catch an error
       warn "The following error occurred: ", $@, "\n";

       # You can access the error code through the last response object.
       print "Error Code: ", $mturk->response->errorCode, "\n";

       # You can also access the last request made.
       print "Error while calling operation, ",
             $mturk->request->{Operation}, "\n";


All of the operations listed in the MechanicalTurk API may be called on a MechanicalTurk instance. To see a list of those operations and what parameters they take see the following URL:


The MechanicalTurk web service returns XML for a request. This module will parse the XML into a generic perl data structure consisting of hashes and arrays. This data structure is then looked through to find a result. A result is the first child element under the root element whose element name is not OperationRequest. The XML returned by the webservice contains information rarely used. (If you ever need this extra information it is available through the response attribute on the MechanicalTurk instance.)

Although the results are normal data structures, they also have methods added to them through the package


This package provides a few methods, however the most useful one during development is toString. The toString method will help you figure out how to access the information you need from the result. Here is an example of the result as returned by GetAccountBalance.

    my $result = $mturk->GetAccountBalance;
    print $result->toString, "\n";
    printf "Available Balance: %s\n", $result->{AvailableBalance}[0]{Amount}[0];

          [0] 10000.00
          [0] USD
          [0] $10,000.00
          [0] 0.00
          [0] USD
          [0] $0.00
          [0] True

    Available Balance: 10000.00

Implementation Note: Hash values always contain arrays, even when the WSDL/XSD specifies that child element of another element only occurs once. This perl module does not use the WSDL or XSD for reading or generating XML and does not know if a child element should occur once or many times. It treats the XML as if the element could always occur more than once. It could have been written to condense a single occurence in an array to 1 scalar item, however this would require API users to test if a value is a SCALAR or an ARRAY.


Some of the MechanicalTurk operations, such as GetAssignmentsForHIT are limited in the number of results returned. These methods have the parameters PageSize and PageNumber, which can be used to go through an entire list of results.

Instead of writing the code to iterate through all of the results using pages, you can make a call to that method with the word 'All' appended to the method name. An object will be returned, which has a method called next, which will return the next item in the results or undef when there are no more results.

Example using an iterator for the GetAssignmentsForHIT operation:

    my $assignments = $mturk->GetAssignmentsForHITAll(
        HITId => $hitId,
        AssignmentStatus => 'Submitted'
    while (my $assignment = $assignments->next) {
        my $assignmentId = $assignment->{AssignmentId}[0];
        $mturk->ApproveAssignment( AssignmentId => $assignmentId );


Methods which provide additional functionaliy on top of Mechanical Turk

Extra methods are available through a dynamic extension mechanism. Modules under Net::Amazon::MechanicalTurk::Command add extra functionality to the MechanicalTurk client.


If you were to call the method listOperations, the module Net::Amazon::MechanicalTurk::Command::ListOperations would be loaded and the method listOperations would be added to the MechanicalTurk client.

See the perldocs for those commands:


accessKey or access_key

Get or set the access key used for authentication.

secretKey or secret_key

Get or set the secret key used for signing web service requests.

serviceUrl or service_url

Get or set the endpoint for the webservice. If this url contains the query parameters, Version and/or Service. Then the values for serviceVersion and serviceName will also be set.

serviceName or service_name

Get or set the service name of the web service.

serviceVersion or service_version

Get or set the version of the web service.

requesterUrl or requester_url

Get or set the URL for the requester website. This is only used for display purposes.

workerUrl or worker_url

Get or set the URL for the worker website. This is only used for display purposes.


Get the last response from a web service call. This will be of type Net::Amazon::MechanicalTurk::Response.


Get the last request used for a web service call. This will be a hash of all the parameters sent to the transport.


Get the filterChain used for intercepting web service calls. This is for advanced use cases and internal use. This attribute will be of type Net::Amazon::MechanicalTurk::FilterChain.


Get or set the transport used for sending web service requests.

The default transport is of type Net::Amazon::MechanicalTurk::Transport::RESTTransport.

Hint: You can get to the underlying LWP::UserAgent through the RESTTransport to set connection timeouts.




Initialize a new MechanicalTurk client

Utility Methods


Tests whether or not the current serviceUrl is for production.


Tests whether or not the current serviceUrl is for the MechanicalTurk sandbox environment.



serviceUrl determines which host the client communicates with. Can be given a full Url, or can be set to one of the named urls: * Sanbox * Production


transport is the object that handles actual comunications with the service. Pass in an initialized transport or parameters to be passed to Net::Amazon::MechanicalTurk::Transport->create.

Mechanical Turk API calls


iterator retrieves a Net::Amazon:MechanicalTurk::PagedResultsIterator for the requested operation and parameters


call simply invokes the requested operation with the provided parameters and returns the result


Please report any bugs or feature requests through the Amazon Web Services Developer Connection.


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

    perldoc Net::Amazon::MechanicalTurk

You can also look for information at:


Copyright (c) 2007 Amazon Technologies, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.