![Amazon Mechanical Turk Getting Started Guide
Installing Command Line Tools
Installing Command Line Tools
You must install and configure the command line tools correctly before you can use the command line
to work through the examples in this guide.
If you use Unix, use the following procedure.
To install the Amazon Mechanical Turk command line tools for Unix users
1. Go to Amazon Mechanical Turk Command Line Tools.
2. Go to the [Command Line Tools Installation Directory] directory and open the file
Overview.html.
3. Follow the instructions in the section "Installing the command line tools" in the Overview.html file
to install and configure the command line tools.
You need your Access Key ID and Secret Access Key for this step.
If you use Windows, use the following procedure.
To install the Amazon Mechanical Turk command line tools for Windows Users
1. Go to Amazon Mechanical Turk Command Line Tools and download the command line tools.
2. Run mech-turk-setup.exe and follow the instructions.
This setup wizard installs and configures the command line tools. You need your Access Key ID and
Secret Access Key for this step.
Install C# Tools
To install and configure the Amazon Mechanical Turk SDK for .Net
1. Go to Amazon Mechanical Turk SDK for .NET and download the Amazon Mechanical Turk SDK for
.NET.
2. Open the file [SDK Installation Directory]Overview.html.
3. Verify that you meet the prerequisites listed in the "Prerequisites" section of the Overview.html
file.
4. Follow the instructions in the section "Installing the Amazon Mechanical Turk SDK for .NET" of the
Overview.html file to install and configure the SDK.
You need your Access Key ID and Secret Access Key for this step.
You must configure the SDK correctly before you can use the examples in this guide.
Install Java Tools
To install the Amazon Mechanical Turk SDK for Java
1. Go to Amazon Mechanical Turk SDK for Java and download the SDK for Java.
2. Open the file [SDK Installation Directory]Overview.html.
3. Verify that you meet the prerequisites listed in the "Prerequisites" section of the Overview.html
file.
4. Follow the instructions in the section "Installing the SDK" of the Overview.html file to install and
configure the SDK.
API Version 2008-08-02
8](https://image.slidesharecdn.com/amtgettingstarted-110825182926-phpapp02/85/AMT-Getting-Started-11-320.jpg)
![Amazon Mechanical Turk Getting Started Guide
Install Perl Tools
You need your Access Key ID and Secret Access Key for this step.
You must configure the SDK correctly before you can use the examples in this guide.
Install Perl Tools
To install the Amazon Mechanical Turk SDK for Perl
1. Go to Amazon Mechanical Turk SDK for Perl and download the SDK for Perl.
2. Open the file [SDK Installation Directory]README.
3. Verify that you meet the prerequisites listed in the "Prerequisites" section of the README file.
4. Follow the instructions in the "Installation" section of the README file to install and configure the SDK.
You need your Access Key ID and Secret Access Key for this step.
You must configure the SDK correctly before you can use the examples in this guide.
Install Ruby Tools
To install the Ruby Libraries for Amazon Web Services
1. Go to Ruby Libraries for Amazon Web Services and download the Ruby libraries.
2. Open the file [SDK Installation Directory]README.
3. Verify that you meet the prerequisites listed in the "Prerequisites" section of the README file.
4. Follow the instructions in the "Installation" section of the README file to install and configure the
libraries.
You need your Access Key ID and Secret Access Key for this step.
You must configure the SDK correctly before you can use the examples in this guide.
Creating an AWS Account
To develop with AWS web services, you must first create an AWS account. An AWS account is an
Amazon.com account that enables you to use AWS web services. You can use the login name and
password of your Amazon.com account to create your AWS account.
Important
If you have a personal Amazon.com account, you might want to have a separate Amazon.com
account reserved for your AWS activity. You could provide a new email address not already in
the Amazon.com system, or provide an email address for an existing Amazon.com account you
have but use a different password. You can have multiple Amazon.com accounts that use the
same email address, but different passwords.
From your AWS account, you can view your AWS account activity, view usage reports, and manage your
AWS account access identifiers.
Tip
If you already have an AWS account, you can skip to the next section. For more information, see
Viewing Your AWS Identifiers (p. 10). If you have already know how to view your AWS identifiers,
API Version 2008-08-02
9](https://image.slidesharecdn.com/amtgettingstarted-110825182926-phpapp02/85/AMT-Getting-Started-12-320.jpg)
![Amazon Mechanical Turk Getting Started Guide
Creating a HIT Using the API
# this HIT Lifetime value is 60*60*24*3 = 3 days
hitlifetime:259200
# this Auto Approval period is 60*60*24*15 = 15 days
autoapprovaldelay:1296000
4. Navigate to the [Command Line Tools Installation Directory]bin directory to run the
commands.
How to Test Your HIT
To test your HIT, publish it in the sandbox by including the -sandbox argument with the loadHITs
command.
To test your HIT
1. Open a command prompt, navigate to the [Command Line Tools Installation
Directory]bin directory, and run the following command:
loadHITs -input c:moviesurveymoviesurvey.input -question c:moviesur
veymoviesurvey.question -properties c:moviesurveymoviesurvey.properties
-sandbox
2. Go to the Amazon Mechanical Turk Developer Sandbox and view your HIT.
You can rewrite and rerun your HIT as often as you like.
How to Publish Your HIT
When you are satisfied with your HIT, publish it to the production system.
To publish your HIT to the production system
• Open a command prompt, navigate to the [Command Line Tools Installation
Directory]bin directory and run the following command:
loadHITs -input c:moviesurveymoviesurvey.input -question c:moviesur
veymoviesurvey.question -properties c:moviesurveymoviesurvey.properties
Your HIT is now on the production site.
Creating a HIT Using the API
Topics
• C# (p. 17)
• Java (p. 19)
API Version 2008-08-02
16](https://image.slidesharecdn.com/amtgettingstarted-110825182926-phpapp02/85/AMT-Getting-Started-19-320.jpg)
![Amazon Mechanical Turk Getting Started Guide
Creating a HIT Using the API
• Perl (p. 22)
• Ruby (p. 25)
The following sections explain how to create a HIT using the Amazon Mechanical Turk API.
C#
The following example uses the methods of the Amazon Mechanical Turk SDK for .Net to create the
movie survey. You must have the SDK installed and configured correctly to run this example.
How to Create a HIT
This section shows how to create a HIT.
To create the HIT
1. Add a project reference to [SDK Installation
Directory]libAmazon.WebServices.MechanicalTurk.dll.
2. Add the following using statements to your source code:
• using Amazon.WebServices.MechanicalTurk
• using Amazon.WebServices.MechanicalTurk.Domain
3. Copy the app.config file from the [SDK Installation Directory]src directory to your
project directory and add the file to your project. This file contains the configuration and the AWS
identifier information for your application.
4. Create a SimpleClient object. This class provides a client used to invoke single operations for
Mechanical Turk. Typically, you create this object once and use it throughout your application.
static SimpleClient client = new SimpleClient();
5. Use one of the CreateHIT() methods in the SimpleClient class to create a HIT. The following
example uses the CreateHIT() method that requires values for the title, description, reward,
question, and maxAssignments parameters of the method.
HIT hit = client.CreateHIT(
"Movie Survey",
"This is a survey to find out how many movies you have watched recently.",
new decimal(0.05), "How many movies have you seen this month?", 100);
The following example pulls together all the code described in the preceding procedure.
using System;
using System.Collections.Generic;
using System.Text;
using Amazon.WebServices.MechanicalTurk;
API Version 2008-08-02
17](https://image.slidesharecdn.com/amtgettingstarted-110825182926-phpapp02/85/AMT-Getting-Started-20-320.jpg)
![Amazon Mechanical Turk Getting Started Guide
Creating a HIT Using the API
using Amazon.WebServices.MechanicalTurk.Domain;
namespace CreateHITExample
{
class Program
{
// Create a client as a class member.
static SimpleClient client = new SimpleClient();
static void Main(string[] args)
{
CreateNewHIT();
}
static void CreateNewHIT()
{
// Create a HIT with the specified parameters.
HIT hit = client.CreateHIT(
"Movie Survey",
// title
"This is a survey to find out how many movies you have watched
recently.", // description
new decimal(0.05),
// reward
"How many movies have you seen this month?",
// question
100);
// number of assignments
// Write the new HIT Id to the console.
Console.WriteLine("Created HIT: {0}", hit.HITId);
Console.WriteLine("Hit Location: {0}", client.GetPreviewURL(hit.HIT
TypeId));
}
}
}
How to Test Your HIT
When you compile and run the code example, your HIT is published on the Amazon Mechanical Turk
Developer Sandbox by default. This is a simulated environment that enables you to view your HIT as it
would appear to Workers. The sandbox is a free test environment for all Requesters.
To test your HIT
1. Compile and run your project.
If no errors occur, you see output similar to the following:
Created HIT: 2X6T66XZQARRM98X5030
HIT Location: http://workersandbox.mturk.com/mturk/preview?groupId=2X6T66XZQAR
RM98X5030
API Version 2008-08-02
18](https://image.slidesharecdn.com/amtgettingstarted-110825182926-phpapp02/85/AMT-Getting-Started-21-320.jpg)
![Amazon Mechanical Turk Getting Started Guide
Creating a HIT Using the API
2. Go to the Amazon Mechanical Turk Developer Sandbox and view your HIT. You can rewrite and
recompile your HIT as often as necessary.
How to Publish Your HIT
When you are satisfied with your HIT, publish it on the Amazon Mechanical Turk production system. This
makes your HIT available for Workers to complete.
To publish your HIT
1. Open the App.config file for your project.
2. Under element <appSettings>, find the following entry:
<add key="MechanicalTurk.ServiceEndpoint" value="http://mechanicalturk.sand
box.amazonaws.com?Service=AWSMechanicalTurkRequester"/>
3. Replace the entry with the following string:
<add key="MechanicalTurk.ServiceEndpoint" value="http://mechanicalturk.amazon
aws.com/?Service=AWSMechanicalTurkRequester"/>
4. Save and close the file.
5. Run your application.
Your HIT is now on the production site.
Java
The following example uses the APIs of the Amazon Mechanical Turk SDK for Java to create the movie
survey. You must have the SDK installed and configured correctly before you run this example.
How to Create a HIT
This section shows how to create a HIT.
To create the HIT
1. Specify all the *.jar files in the [SDK Installation Directory]lib directory and in the [SDK
Installation Directory]libthird-party directory in your classpath.
2. Specify all the *.jar files in the [SDK Installation Directory]buildlib directory in your
classpath.
3. Copy the mturk.properties file to your project. This file contains the configuration information
needed for your project.
4. Import the following classes to your application.
• com.amazonaws.mturk.service.axis.RequesterService
• com.amazonaws.mturk.service.exception.ServiceException
• com.amazonaws.mturk.util.ClientConfig
• com.amazonaws.mturk.requester.HIT
API Version 2008-08-02
19](https://image.slidesharecdn.com/amtgettingstarted-110825182926-phpapp02/85/AMT-Getting-Started-22-320.jpg)
![Amazon Mechanical Turk Getting Started Guide
Creating a HIT Using the API
*
*/
public void createMovieSurvey()
{
try
{
// The createHIT method is called using a convenience static method
// RequesterService.getBasicFreeTextQuestion() that generates the question
format
// for the HIT.
HIT hit = service.createHIT
(
title,
description,
reward,
RequesterService.getBasicFreeTextQuestion(
"How many movies have you seen this month?"),
numAssignments);
// Print out the HITId and the URL to view the HIT.
System.out.println("Created HIT: " + hit.getHITId());
System.out.println("HIT location: ");
System.out.println(service.getWebsiteURL() + "/mturk/preview?groupId="
+ hit.getHITTypeId());
}
catch (ServiceException e)
{
System.err.println(e.getLocalizedMessage());
}
}
/**
* Main method
*
* @param args
*/
public static void main(String[] args)
{
// Create an instance of this class.
MovieSurvey app = new MovieSurvey();
// Create the new HIT.
app.createMovieSurvey();
}
}
How to Test Your HIT
This section shows how to test your HIT.
When you compile and run the code example, your HIT is published on the Amazon Mechanical Turk
Developer Sandbox. This is a simulated environment that enables you to view your HIT as it would appear
to Workers. The sandbox is a free test environment for all Requesters.
To test your HIT
1. Compile and run your project.
API Version 2008-08-02
21](https://image.slidesharecdn.com/amtgettingstarted-110825182926-phpapp02/85/AMT-Getting-Started-24-320.jpg)
![Amazon Mechanical Turk Getting Started Guide
Creating a HIT Using the API
# Create the question to ask in the HIT.
my $question = "How many movies have you seen this month?";
# Create the format for the question.
my $questionXml = <<END_XML;
<?xml version="1.0" encoding="UTF-8"?>
<QuestionForm xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkData
Schemas/2005-10-01/QuestionForm.xsd">
<Question>
<QuestionIdentifier>1</QuestionIdentifier>
<QuestionContent>
<Text>$question</Text>
</QuestionContent>
<AnswerSpecification>
<FreeTextAnswer/>
</AnswerSpecification>
</Question>
</QuestionForm>
END_XML
# Create a MechanicalTurk object.
my $mturk = Net::Amazon::MechanicalTurk->new;
# Create the HIT with the properties specified.
my $result = $mturk->CreateHIT(
Title => 'Movie Survey',
Description => 'This is a survey to find out how many movies you have watched
recently',
Keywords => 'movie, survey',
Reward => {
CurrencyCode => 'USD',
Amount => 0.05
},
RequesterAnnotation => 'Movie Survey',
AssignmentDurationInSeconds => 60 * 60 * 24,
AutoApprovalDelayInSeconds => 60 * 60 * 10,
MaxAssignments => 100,
LifetimeInSeconds => 60 * 60,
Question => $questionXml
);
# Print the HIT Id to the console.
printf "Created HIT:n";
printf "HITId: %sn", $result->{HITId}[0];
printf "nHIT Location: %sn", $mturk->getHITTypeURL($result->{HITTypeId}[0]);
How to Test Your HIT
When you run this code example, your HIT is published on the Amazon Mechanical Turk Developer
Sandbox by default. This is a simulated environment that enables you to view your HIT as it would appear
to Workers. The sandbox is a free test environment for all Requesters.
To test your HIT
1. Run the sample to publish the HIT on the Amazon Mechanical Turk Developer Sandbox.
If no errors occur, you see output similar to the following:
API Version 2008-08-02
24](https://image.slidesharecdn.com/amtgettingstarted-110825182926-phpapp02/85/AMT-Getting-Started-27-320.jpg)
![Amazon Mechanical Turk Getting Started Guide
Creating a HIT Using the API
# Load the question (QuestionForm) file
question = File.read( questionFile )
result = @mturk.createHIT( :Title => title,
:Description => desc,
:MaxAssignments => numAssignments,
:Reward => { :Amount => rewardAmount, :CurrencyCode => 'USD' },
:Question => question,
:Keywords => keywords )
puts "Created HIT: #{result[:HITId]}"
puts "HIT Location: #{getHITUrl( result[:HITTypeId] )}"
return result
end
def getHITUrl( hitTypeId )
if @mturk.host =~ /sandbox/
"http://workersandbox.mturk.com/mturk/preview?groupId=#{hitTypeId}" #
Sandbox Url
else
"http://mturk.com/mturk/preview?groupId=#{hitTypeId}" # Production Url
end
end
createNewHIT
How to Test Your HIT
When you run this code example, your HIT is published on the Amazon Mechanical Turk Developer
Sandbox by default. This is a simulated environment that enables you to view your HIT as it would appear
to Workers. The sandbox is a free test environment for all Requesters.
To test your HIT
1. Run the sample to publish the HIT on the Amazon Mechanical Turk Developer Sandbox.
If no errors occur, you see output similar to the following:
Created HIT: 2X6T66XZQARRM98X5030
HIT Location: http://workersandbox.mturk.com/mturk/preview?groupId=2X6T66XZQAR
RM98X5030
2. Go to the Amazon Mechanical Turk Developer Sandbox and view your HIT. You can rewrite and
recompile your HIT as often as necessary.
How to Publish Your HIT
When you are satisfied with your HIT, publish it on the Amazon Mechanical Turk production system. This
makes your HIT available for Workers to complete.
To publish your HIT
1. In the sample code, find the following line and comment it out:
@mturk = Amazon::WebServices::MechanicalTurkRequester.new :Host => :Sandbox
API Version 2008-08-02
27](https://image.slidesharecdn.com/amtgettingstarted-110825182926-phpapp02/85/AMT-Getting-Started-30-320.jpg)
![Amazon Mechanical Turk Getting Started Guide
Symbol Conventions
Symbol Conventions
This section describes the common use of symbols.
Convention Symbol Description/Example
Mutually (Parentheses | and Within a code description, bar separators denote options from
exclusive | vertical | bars) which one must be chosen.
parameters
% data = hdfread (start | stride | edge)
Optional [square brackets] Within a code description, square brackets denote completely
parameters optional commands or parameters.
XML variable
text % sed [-n, -quiet]
Use square brackets in XML examples to differentiate them from
tags.
<CustomerId>[ID]</CustomerId>
Variables <arrow brackets> Within a code sample, arrow brackets denote a variable that
must be replaced with a valid value.
% ec2-register <your-s3-bucket>/image.manifest
API Version 2008-08-02
36](https://image.slidesharecdn.com/amtgettingstarted-110825182926-phpapp02/85/AMT-Getting-Started-39-320.jpg)
AMT: Getting Started
- 1. Amazon Mechanical Turk Getting Started Guide API Version 2008-08-02
- 2. Amazon Mechanical Turk Getting Started Guide Amazon Mechanical Turk: Getting Started Guide Copyright © 2011 Amazon Web Services LLC or its affiliates. All rights reserved.
- 3. Amazon Mechanical Turk Getting Started Guide Table of Contents Welcome ............................................................................................................................................................. 1 Introduction to Amazon Mechanical Turk ............................................................................................................ 4 Setting Up Accounts and Tools ........................................................................................................................... 7 Creating a HIT .................................................................................................................................................. 13 Implementing Amazon Mechanical Turk ........................................................................................................... 29 How to Cancel Your Registration to Amazon Mechanical Turk ............................................................. 33 Document Conventions .................................................................................................................................... 34 Document History ............................................................................................................................................. 37
- 4. Amazon Mechanical Turk Getting Started Guide Audience Welcome Topics • Audience (p. 1) • How to Use this Guide (p. 2) • Amazon Mechanical Turk Resources (p. 2) This is the Amazon Mechanical Turk Getting Started Guide. This section describes who should read this guide, how the guide is organized, and other resources related to Amazon Mechanical Turk. Amazon Mechanical Turk provides an on-demand, scalable, human workforce to complete jobs that humans can do better than computers. Audience This guide is for developers who want to write scripts or software applications that use the Amazon Mechanical Turk SDKs. Amazon Mechanical Turk has several audiences this guide does not address: • Developers who want to publish many HITs that ask the same questions but with different data. For example, if you want Workers to answer the same question about ten thousand different photos, you would use the Amazon Mechanical Turk Requester User Interface. For more information, go to the Amazon Mechanical Turk Requester User Interface Guide. • Business analysts who do not want to write software but who want to use the Amazon Mechanical Turk command line interface to access the Amazon Mechanical Turk web service. For more information, go to the Amazon Mechanical Turk Developer Guide. Required Knowledge and Skills If you are not a developer, you need to be familiar with the Windows, Mac or Linux command line. You should also be familiar with XML, HTML, and Microsoft Excel. If you are a developer, you should be familiar with: • XML (go to W3 Schools XML Tutorial) API Version 2008-08-02 1
- 5. Amazon Mechanical Turk Getting Started Guide How to Use this Guide • Web service basics (go to W3 Schools Web Services Tutorial) • One or more of the following programming languages: • C# • Java • Perl • Ruby How to Use this Guide This guide provides a high-level introduction and tutorial to Amazon Mechanical Turk. Depending on your AWS programming experience, you can use this guide in the following ways. If you are new to AWS Read the entire guide. It takes you step-by-step through the process of using Amazon Mechanical Turk to create requests and parse responses. The tutorial provides a simple implementation of creating, testing, and publishing an Amazon Mechanical Turk HIT in a variety of programming languages. Each section builds on the previous sections so that if you work through the examples in sequence, you will get a basic understanding of Amazon Mechanical Turk. If you have developed applications for other AWS services You can skip most of the Getting Set Up section. Just sign up to use Amazon Mechanical Turk and move on to the tutorial or implementation section. For more information about signing up for Amazon Mechanical Turk, see Setting Up Your Requester Account (p. 11). If you already know how to issue a web service request and parse an XML response You can skip to the implementation section that lists many different ways to get in-depth knowledge of Amazon Mechanical Turk that go beyond the scope of this guide. To skip to more advanced topics, see Implementing Amazon Mechanical Turk (p. 29). The major sections of this guide are: • Introduction to Amazon Mechanical Turk— Provides a high-level overview of Amazon Mechanical Turk • Setting Up Accounts and Tools— Describes how to set up the tools you need to use this guide • Creating a HIT— Provides step-by-step instructions to write and publish a HIT • Implementing Amazon Mechanical Turk— Describes what to do next after you run your application or script • Document Conventions— Establishes the common typographical and symbol use conventions for AWS technical publications Amazon Mechanical Turk Resources The following table lists related resources that you might find useful as you work with this service. Resource Description Amazon Mechanical Turk Developer The developer guide describes programming concepts for Guide the Amazon Mechanical Turk web service. API Version 2008-08-02 2
- 6. Amazon Mechanical Turk Getting Started Guide Amazon Mechanical Turk Resources Resource Description Amazon Mechanical Turk API Reference The API Reference describes the operations you can use to execute Amazon Mechanical Turk functionality. Amazon Mechanical Turk Technical FAQ The FAQ covers the top 20 questions developers have asked about this product. Amazon Mechanical Turk Release Notes The release notes give a high-level overview of the current release. They specifically note any new features, corrections, and known issues. Amazon Mechanical Turk Developer A central starting point to find documentation, code samples, Resource Center release notes, and other information to help you build innovative applications with Amazon Mechanical Turk. Discussion Forums A community-based forum for developers to discuss technical questions related to Amazon Web Services. AWS Support Center The home page for AWS Technical Support, including access to our Developer Forums, Technical FAQs, Service Status page, and Premium Support. Amazon Mechanical Turk product The primary web page for information about Amazon information Mechanical Turk. Contact Us A central contact point for inquiries concerning AWS billing, account, events, abuse etc. Conditions of Use Detailed information about the copyright and trademark usage at Amazon.com and other topics. The next section provides an overview of the concepts and features of Amazon Mechanical Turk. API Version 2008-08-02 3
- 7. Amazon Mechanical Turk Getting Started Guide Overview of Amazon Mechanical Turk Introduction to Amazon Mechanical Turk Topics • Overview of Amazon Mechanical Turk (p. 4) • Key Amazon Mechanical Turk Concepts (p. 5) • Overview of Examples (p. 6) This introduction to Amazon Mechanical Turk provides a high-level overview of this web service. After reading this section, you should understand the basics you need to work through the examples in this guide. Overview of Amazon Mechanical Turk Amazon Mechanical Turk provides an on-demand, scalable, human workforce to complete jobs that humans can do better than computers. Amazon Mechanical Turk software formalizes job offers to the thousands of Workers willing to do piecemeal work at their convenience. The software also retrieves work performed and compiles it for you, the Requester, who pays the Workers for satisfactory work (only). Optional qualification tests enable you to select competent Workers. The kinds of tasks humans can complete better than computers includes finding objects in photos, writing reviews of restaurants, movies, or businesses, translating text passages into foreign languages, getting the hours of operation of the business center within a hotel, determining if a hotel is family-friendly, or telling you the most relevant search results for a given phrase. This guide presents a very slim slice of the Amazon Mechanical Turk API. For a complete description of the entire API, go to the Amazon Mechanical Turk API Reference. For more information about using the API, go to the Amazon Mechanical Turk Developer Guide Features The following list describes the features of Amazon Mechanical Turk highlighted by the tutorial in this guide. • On-demand workforce—Amazon Mechanical Turk provides access to a virtual community of Workers. API Version 2008-08-02 4
- 8. Amazon Mechanical Turk Getting Started Guide Key Amazon Mechanical Turk Concepts • Create jobs that Workers perform over the Internet—Advertise your job to the thousands of Amazon Mechanical TurkWorkers around the world You prescribe the job (HIT) that Workers complete using their computer, and pay them for their work. • Test and publish your jobs—Test your applications in the Amazon Mechanical Turk sandbox Test your jobs in the Amazon Mechanical Turk sandbox and publish the revised jobs to the outside world. Amazon Mechanical Turk provides SDKs and command line tools to make it easier to build solutions leveraging Amazon Mechanical Turk. Key Amazon Mechanical Turk Concepts Topics • Requester (p. 5) • Human Intelligence Task (p. 5) • Worker (p. 5) • Assignment (p. 5) • Reward (p. 6) This section describes key Amazon Mechanical Turk concepts. Requester A Requester is a company, organization, or person that creates and submits tasks (HITs) to Amazon Mechanical Turk for Workers to perform. As a Requester, you can use a software application to interact with Amazon Mechanical Turk to submit tasks, retrieve results, and perform other automated tasks. You can use the Requester website to check the status of your HITs, and manage your account. Human Intelligence Task A Human Intelligence Task (HIT) is a task that a Requester submits to Amazon Mechanical Turk for Workers to perform. A HIT represents a single, self-contained task, for example, "Identify the car color in the photo." Workers can find HITs listed on the Amazon Mechanical Turk website. For more information, go to the Amazon Mechanical Turk website. Each HIT has a lifetime, specified by the Requester, that determines how long the HIT is available to Workers. A HIT also has an assignment duration, which is the amount of time a Worker has to complete a HIT after accepting it. Worker A Worker is a person who performs the tasks specified by a Requester in a HIT. Workers use the Amazon Mechanical Turk website to find and accept assignments, enter values into the question form, and submit the results. The Requester specifies how many Workers can work on a task. Amazon Mechanical Turk guarantees that a Worker can work on each task only one time. Assignment An assignment specifies how many people can submit completed work for your HIT. When a Worker accepts a HIT, Amazon Mechanical Turk creates an assignment to track the work to completion. The API Version 2008-08-02 5
- 9. Amazon Mechanical Turk Getting Started Guide Reward assignment belongs exclusively to the Worker and guarantees that the Worker can submit results and be eligible for a reward until the time the HIT or assignment expires. Reward A reward is the money you, as a Requester, pay Workers for satisfactory work they do on your HITs Overview of Examples This guide provides examples that show how to use the Amazon Mechanical Turk. It provides SDKs and command line tools to create a survey and publish it as a HIT. Selecting Your Language The HTML version of this guide enables you to hide the text in this section that doesn't pertain to the programming language you are using. There is a language selection menu in the upper-right corner of pages with language-specific text. Select your computer language to show the examples in only that computer language, or select All to show the examples in all available computer languages. You can also select Command Line Tools, which hides all code samples and leaves only information related to the command line tools. The next section explains how to sign up for AWS, Amazon Mechanical Turk, and set up your development environment so that you can actually try the examples explained in the tutorial. You must complete all of these tasks before you can use Amazon Mechanical Turk. API Version 2008-08-02 6
- 10. Amazon Mechanical Turk Getting Started Guide Installing Your Programming Tools Setting Up Accounts and Tools Topics • Installing Your Programming Tools (p. 7) • Creating an AWS Account (p. 9) • Viewing Your AWS Security Credentials (p. 10) • Setting Up Your Requester Account (p. 11) • Prepay for Your HITs (p. 12) This section describes the tasks you need to perform before you can use Amazon Mechanical Turk. Tip If you have already developed applications for another AWS product, you only need to sign up for Amazon Mechanical Turk. For more information, see Setting Up Your Requester Account (p. 11). Otherwise, complete all of the tasks in this section. Installing Your Programming Tools Amazon Mechanical Turk provides SDKs and command line tools designed to make it easier for you to build solutions leveraging Amazon Mechanical Turk. These SDKs and tools hide the complexity and simplify using the Amazon Mechanical Turk APIs. The sections below provide instructions for installing the SDKs and command line tools. You must install one of the SDKs or the command line tools to run the examples in this guide. Showing Your Preferred Programming Language If you are viewing the HTML version of this guide, you can hide text in this section that don't pertain to the programming language you are using. There is a language selection menu in the upper-right corner of pages with language-specific text. Select your computer language to show the examples in only that computer language, or select All to show the examples in all available computer languages. API Version 2008-08-02 7
- 11. Amazon Mechanical Turk Getting Started Guide Installing Command Line Tools Installing Command Line Tools You must install and configure the command line tools correctly before you can use the command line to work through the examples in this guide. If you use Unix, use the following procedure. To install the Amazon Mechanical Turk command line tools for Unix users 1. Go to Amazon Mechanical Turk Command Line Tools. 2. Go to the [Command Line Tools Installation Directory] directory and open the file Overview.html. 3. Follow the instructions in the section "Installing the command line tools" in the Overview.html file to install and configure the command line tools. You need your Access Key ID and Secret Access Key for this step. If you use Windows, use the following procedure. To install the Amazon Mechanical Turk command line tools for Windows Users 1. Go to Amazon Mechanical Turk Command Line Tools and download the command line tools. 2. Run mech-turk-setup.exe and follow the instructions. This setup wizard installs and configures the command line tools. You need your Access Key ID and Secret Access Key for this step. Install C# Tools To install and configure the Amazon Mechanical Turk SDK for .Net 1. Go to Amazon Mechanical Turk SDK for .NET and download the Amazon Mechanical Turk SDK for .NET. 2. Open the file [SDK Installation Directory]Overview.html. 3. Verify that you meet the prerequisites listed in the "Prerequisites" section of the Overview.html file. 4. Follow the instructions in the section "Installing the Amazon Mechanical Turk SDK for .NET" of the Overview.html file to install and configure the SDK. You need your Access Key ID and Secret Access Key for this step. You must configure the SDK correctly before you can use the examples in this guide. Install Java Tools To install the Amazon Mechanical Turk SDK for Java 1. Go to Amazon Mechanical Turk SDK for Java and download the SDK for Java. 2. Open the file [SDK Installation Directory]Overview.html. 3. Verify that you meet the prerequisites listed in the "Prerequisites" section of the Overview.html file. 4. Follow the instructions in the section "Installing the SDK" of the Overview.html file to install and configure the SDK. API Version 2008-08-02 8
- 12. Amazon Mechanical Turk Getting Started Guide Install Perl Tools You need your Access Key ID and Secret Access Key for this step. You must configure the SDK correctly before you can use the examples in this guide. Install Perl Tools To install the Amazon Mechanical Turk SDK for Perl 1. Go to Amazon Mechanical Turk SDK for Perl and download the SDK for Perl. 2. Open the file [SDK Installation Directory]README. 3. Verify that you meet the prerequisites listed in the "Prerequisites" section of the README file. 4. Follow the instructions in the "Installation" section of the README file to install and configure the SDK. You need your Access Key ID and Secret Access Key for this step. You must configure the SDK correctly before you can use the examples in this guide. Install Ruby Tools To install the Ruby Libraries for Amazon Web Services 1. Go to Ruby Libraries for Amazon Web Services and download the Ruby libraries. 2. Open the file [SDK Installation Directory]README. 3. Verify that you meet the prerequisites listed in the "Prerequisites" section of the README file. 4. Follow the instructions in the "Installation" section of the README file to install and configure the libraries. You need your Access Key ID and Secret Access Key for this step. You must configure the SDK correctly before you can use the examples in this guide. Creating an AWS Account To develop with AWS web services, you must first create an AWS account. An AWS account is an Amazon.com account that enables you to use AWS web services. You can use the login name and password of your Amazon.com account to create your AWS account. Important If you have a personal Amazon.com account, you might want to have a separate Amazon.com account reserved for your AWS activity. You could provide a new email address not already in the Amazon.com system, or provide an email address for an existing Amazon.com account you have but use a different password. You can have multiple Amazon.com accounts that use the same email address, but different passwords. From your AWS account, you can view your AWS account activity, view usage reports, and manage your AWS account access identifiers. Tip If you already have an AWS account, you can skip to the next section. For more information, see Viewing Your AWS Identifiers (p. 10). If you have already know how to view your AWS identifiers, API Version 2008-08-02 9
- 13. Amazon Mechanical Turk Getting Started Guide Viewing Your AWS Security Credentials you can skip right to signing up for Amazon Mechanical Turk. For more information, see Setting Up Your Requester Account (p. 11). Otherwise, complete the tasks in this section. To set up an AWS account 1. Go to http://aws.amazon.com. 2. In the Sign Up for AWS box, click Sign up today. The Sign In page displays. 3. Enter a valid email address, select the button for No, I am a new customer, and click Continue. The next page asks for a password and a name that you want to associate with the account. If you have an Amazon.com account, the email address for the account displays as the default login name. 4. Enter the name and password you want to associate with the account and click Continue. The Account Info page displays. 5. Enter your contact information and select how you learned about AWS.Then read the AWS Customer Agreement, select the check box to indicate that you've read and agree to the terms, and click Continue. The process is complete and you've created your AWS account. Viewing Your AWS Security Credentials AWS uses special identifiers to help protect your data. In this section, we show you how to view your identifiers so you can use them. Tip If you already know how to view your AWS security credentials, skip to the next section. AWS assigns you the following credentials when you create your AWS account: • Access Key ID (a 20-character, alphanumeric sequence, for example: 022QF06E7MXBSH9DHM02) You include your Access Key ID in all AWS service requests to identify yourself as the sender of the request. • Secret Access Key (a 40-character sequence, for example: kWcrlUX5JEDGM/LtmEENI/aVmYvHNif5zB+d9+ct) Caution Your Secret Access Key is a shared secret between you and AWS. Keep this ID secret; we use it to bill you for the AWS services you use. Never include the ID in your requests to AWS and never email the ID to anyone even if an inquiry appears to originate from AWS or Amazon.com. No one who legitimately represents Amazon will ever ask you for your Secret Access Key. The Access Key ID is not a secret, and anyone could use your Access Key ID in requests to AWS. To provide proof that you truly are the sender of the request, you also include a digital signature calculated using your Secret Access Key. The sample code handles this for you. Your Access Key ID and Secret Access Key display when you create your AWS account. They are not emailed to you. If you need to see them again, you can view them at any time from your AWS account. API Version 2008-08-02 10
- 14. Amazon Mechanical Turk Getting Started Guide Setting Up Your Requester Account To view your AWS security credentials 1. Go to http://aws.amazon.com/security-credentials. If you're not logged in, you are asked to. If you are logged in, the Security Credentials page displays. 2. Click Access Key ID or Secret Access Key to display your IDs. Setting Up Your Requester Account Before you can use Amazon Mechanical Turk, you must have an Amazon Mechanical Turk Requester account. To create and register a Requester account 1. Go to http://requester.mturk.amazon.com. 2. Click Register. 3. Enter your email address. Note If you already have an Amazon.com account for your email address, you can sign in using your email address and password. However, we recommend creating a new account to use as a Requester. 4. Follow the prompts to complete your Requester account registration. When prompted, you must enter your mailing address and you must accept the Amazon Mechanical Turk Participation Agreement. API Version 2008-08-02 11
- 15. Amazon Mechanical Turk Getting Started Guide Prepay for Your HITs Prepay for Your HITs This tutorial uses the Amazon Mechanical Turk sandbox in which you can execute Amazon Mechanical Turk operations without having to pay Workers for working on your HITs. We recommend that you use the sandbox to test your applications before moving them to the production system. Before you use the production version of Amazon Mechanical Turk you need to prepay for the HITs you create. Otherwise, you can't post your HITs to Workers. To post your HITs to Workers, you must have money in your Prepaid HIT Balance to prepay for all of your HITs. You can provide banking information, credit card or debit card information, or an Amazon Payments account to prepay for the HITs. If you use a bank account, it can take up to one week for your transfer to be approved. During that time you can test your HITs in the Amazon Mechanical Turk Developer Sandbox, but you cannot create HITs on the Amazon Mechanical Turk production system. If you use a credit card, debit card, or Amazon Payments account to prepay, you can use the Amazon Mechanical Turk production system immediately. For instructions on how to prepay for your HITs, go to the Requester website. The next section is a tutorial that takes you step-by-step through using Amazon Mechanical Turk to create a HIT. The tutorial is written procedurally so you should follow it from beginning to end. After completing the tutorial, you should have a good feel for the major tasks you can complete using Amazon Mechanical Turk. Alternately, you can skip the tutorial and jump right to the last section that provides links to code samples, application examples, forums, and other resources designed to help you learn Amazon Mechanical Turk. For more information, see Implementing Amazon Mechanical Turk (p. 29). API Version 2008-08-02 12
- 16. Amazon Mechanical Turk Getting Started Guide Workflow Creating a HIT Topics • Workflow (p. 13) • Working with the Examples (p. 14) • What's Next? (p. 28) In the previous section you set up your AWS account, viewed your AWS identifiers, and installed the tools you need to use Amazon Mechanical Turk. In this section, you learn to write, publish, and manage a HIT. This section also contains code examples that demonstrate how to create, test, and publish your HIT. Workflow The following procedure gives you an overview of creating, testing, publishing, and managing a HIT. Workflow for Requesters 1 Write your HIT. Write the question or task for Workers to answer or perform. 2 Test your HIT. Publish your HIT on the Amazon Mechanical Turk Developer Sandbox. The Amazon Mechanical Turk Developer Sandbox is a simulated environment that allows you to view your HIT as it would appear to Workers. For more information about the Amazon Mechanical Turk Developer Sandbox and how to use it, go to the Amazon Mechanical Turk Developer Sandbox. 3 Publish your HIT on the Amazon Mechanical Turk production system. This step makes your HIT available to Workers. 4 Workers accept your HIT and complete the assignment. You can view the status of your HITs. For more information, go to the Requester website. 5 Process the assignment results. When a Worker completes an assignment, you can view the results, output the results to a file, and accept or reject the work. Accepting the work means that you agree to pay the Worker. API Version 2008-08-02 13
- 17. Amazon Mechanical Turk Getting Started Guide Working with the Examples 6 Manage your HIT. You can extend the completion time for your HIT, expire the HIT early, add additional assignments, modify the HIT properties, or block Workers whose work does not meet your standards. The examples in this section provide instructions for performing tasks 1, 2, and 3. For information about tasks 5 and 6, see Implementing Amazon Mechanical Turk (p. 29). Working with the Examples The following examples use SDK operations or the command line tools to show you how to create a survey that asks the question "How many movies have you seen this month?" The samples create a HIT and print the HIT ID to the console. These examples demonstrate how to publish the HIT to the Amazon Mechanical Turk Developer Sandbox for testing and then how to publish the HIT on the Amazon Mechanical Turk production system. The following sections show you how to create and publish a HIT using the command line interface or the API and a programming language: • Creating a HIT Using the Command Line Interface (p. 14) • API and C# (p. 17) • API and Java (p. 19) • API and Perl (p. 22) • API and Ruby (p. 25) Showing Your Preferred Programming Language The HTML version of this guide enables you to hide the text in this section that doesn't pertain to the programming language you are using. There is a language selection menu in the upper-right corner of pages with language-specific text. Select your computer language to show the examples in only that computer language, or select All to show the examples in all available computer languages. You can also select Command Line Tools, which hides all code samples and leaves only information related to the command line tools. Creating a HIT Using the Command Line Interface Topics • How to Create a HIT (p. 15) • How to Test Your HIT (p. 16) • How to Publish Your HIT (p. 16) This example uses the commands in the Amazon Mechanical Turk command line tools to create a survey. You must have the command line tools installed and configured correctly to run this example. API Version 2008-08-02 14
- 18. Amazon Mechanical Turk Getting Started Guide Creating a HIT Using the Command Line Interface How to Create a HIT The following procedure describes how to create the HIT, "MovieSurvey." To create the HIT 1. Create an input file, moviesurvey.input, a tab-delimited text file, and populate it with the variable data for the HIT. question How many movies have you seen this month? 2. Create a question template file, moviesurvey.question, and add the text of your HIT template. This XML file contains placeholders for the fields defined in the input file and conforms to the QuestionForm schema. <?xml version="1.0" encoding="UTF-8"?> <QuestionForm xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurk DataSchemas/2005-10-01/QuestionForm.xsd"> <Question> <QuestionIdentifier>1</QuestionIdentifier> <QuestionContent> <Text>${question}</Text> </QuestionContent> <AnswerSpecification> <FreeTextAnswer/> </AnswerSpecification> </Question> </QuestionForm> 3. Create a HIT properties file, moviesurvey.properties, and populate it with the properties of the HIT (title, description, etc.) ###################################### ## HIT Properties ###################################### title:Movie Survey description:This is a survey to find out how many movies you have watched recently. keywords:movie, survey reward:0.05 assignments:100 annotation:sample#command ###################################### ## HIT Timing Properties ###################################### # this Assignment Duration value is 60 * 60 = 1 hour assignmentduration:3600 API Version 2008-08-02 15
- 19. Amazon Mechanical Turk Getting Started Guide Creating a HIT Using the API # this HIT Lifetime value is 60*60*24*3 = 3 days hitlifetime:259200 # this Auto Approval period is 60*60*24*15 = 15 days autoapprovaldelay:1296000 4. Navigate to the [Command Line Tools Installation Directory]bin directory to run the commands. How to Test Your HIT To test your HIT, publish it in the sandbox by including the -sandbox argument with the loadHITs command. To test your HIT 1. Open a command prompt, navigate to the [Command Line Tools Installation Directory]bin directory, and run the following command: loadHITs -input c:moviesurveymoviesurvey.input -question c:moviesur veymoviesurvey.question -properties c:moviesurveymoviesurvey.properties -sandbox 2. Go to the Amazon Mechanical Turk Developer Sandbox and view your HIT. You can rewrite and rerun your HIT as often as you like. How to Publish Your HIT When you are satisfied with your HIT, publish it to the production system. To publish your HIT to the production system • Open a command prompt, navigate to the [Command Line Tools Installation Directory]bin directory and run the following command: loadHITs -input c:moviesurveymoviesurvey.input -question c:moviesur veymoviesurvey.question -properties c:moviesurveymoviesurvey.properties Your HIT is now on the production site. Creating a HIT Using the API Topics • C# (p. 17) • Java (p. 19) API Version 2008-08-02 16
- 20. Amazon Mechanical Turk Getting Started Guide Creating a HIT Using the API • Perl (p. 22) • Ruby (p. 25) The following sections explain how to create a HIT using the Amazon Mechanical Turk API. C# The following example uses the methods of the Amazon Mechanical Turk SDK for .Net to create the movie survey. You must have the SDK installed and configured correctly to run this example. How to Create a HIT This section shows how to create a HIT. To create the HIT 1. Add a project reference to [SDK Installation Directory]libAmazon.WebServices.MechanicalTurk.dll. 2. Add the following using statements to your source code: • using Amazon.WebServices.MechanicalTurk • using Amazon.WebServices.MechanicalTurk.Domain 3. Copy the app.config file from the [SDK Installation Directory]src directory to your project directory and add the file to your project. This file contains the configuration and the AWS identifier information for your application. 4. Create a SimpleClient object. This class provides a client used to invoke single operations for Mechanical Turk. Typically, you create this object once and use it throughout your application. static SimpleClient client = new SimpleClient(); 5. Use one of the CreateHIT() methods in the SimpleClient class to create a HIT. The following example uses the CreateHIT() method that requires values for the title, description, reward, question, and maxAssignments parameters of the method. HIT hit = client.CreateHIT( "Movie Survey", "This is a survey to find out how many movies you have watched recently.", new decimal(0.05), "How many movies have you seen this month?", 100); The following example pulls together all the code described in the preceding procedure. using System; using System.Collections.Generic; using System.Text; using Amazon.WebServices.MechanicalTurk; API Version 2008-08-02 17
- 21. Amazon Mechanical Turk Getting Started Guide Creating a HIT Using the API using Amazon.WebServices.MechanicalTurk.Domain; namespace CreateHITExample { class Program { // Create a client as a class member. static SimpleClient client = new SimpleClient(); static void Main(string[] args) { CreateNewHIT(); } static void CreateNewHIT() { // Create a HIT with the specified parameters. HIT hit = client.CreateHIT( "Movie Survey", // title "This is a survey to find out how many movies you have watched recently.", // description new decimal(0.05), // reward "How many movies have you seen this month?", // question 100); // number of assignments // Write the new HIT Id to the console. Console.WriteLine("Created HIT: {0}", hit.HITId); Console.WriteLine("Hit Location: {0}", client.GetPreviewURL(hit.HIT TypeId)); } } } How to Test Your HIT When you compile and run the code example, your HIT is published on the Amazon Mechanical Turk Developer Sandbox by default. This is a simulated environment that enables you to view your HIT as it would appear to Workers. The sandbox is a free test environment for all Requesters. To test your HIT 1. Compile and run your project. If no errors occur, you see output similar to the following: Created HIT: 2X6T66XZQARRM98X5030 HIT Location: http://workersandbox.mturk.com/mturk/preview?groupId=2X6T66XZQAR RM98X5030 API Version 2008-08-02 18
- 22. Amazon Mechanical Turk Getting Started Guide Creating a HIT Using the API 2. Go to the Amazon Mechanical Turk Developer Sandbox and view your HIT. You can rewrite and recompile your HIT as often as necessary. How to Publish Your HIT When you are satisfied with your HIT, publish it on the Amazon Mechanical Turk production system. This makes your HIT available for Workers to complete. To publish your HIT 1. Open the App.config file for your project. 2. Under element <appSettings>, find the following entry: <add key="MechanicalTurk.ServiceEndpoint" value="http://mechanicalturk.sand box.amazonaws.com?Service=AWSMechanicalTurkRequester"/> 3. Replace the entry with the following string: <add key="MechanicalTurk.ServiceEndpoint" value="http://mechanicalturk.amazon aws.com/?Service=AWSMechanicalTurkRequester"/> 4. Save and close the file. 5. Run your application. Your HIT is now on the production site. Java The following example uses the APIs of the Amazon Mechanical Turk SDK for Java to create the movie survey. You must have the SDK installed and configured correctly before you run this example. How to Create a HIT This section shows how to create a HIT. To create the HIT 1. Specify all the *.jar files in the [SDK Installation Directory]lib directory and in the [SDK Installation Directory]libthird-party directory in your classpath. 2. Specify all the *.jar files in the [SDK Installation Directory]buildlib directory in your classpath. 3. Copy the mturk.properties file to your project. This file contains the configuration information needed for your project. 4. Import the following classes to your application. • com.amazonaws.mturk.service.axis.RequesterService • com.amazonaws.mturk.service.exception.ServiceException • com.amazonaws.mturk.util.ClientConfig • com.amazonaws.mturk.requester.HIT API Version 2008-08-02 19
- 23. Amazon Mechanical Turk Getting Started Guide Creating a HIT Using the API 5. Create a RequesterService object.This class provides the configuration information for your application. service = new RequesterService(new PropertiesClientConfig()); 6. Use one of the CreateHIT() methods in the RequesterService class to create a HIT. The following example uses the CreateHIT() method with parameter values for the title, description, reward, and maxAssignments properties of the HIT. HIT hit = service.createHIT ( title, description, reward, RequesterService.getBasicFreeTextQuestion( "How many movies have you seen this month?"), numAssignments); The following example pulls together all the code described in the preceding procedure. package createnewhit; import com.amazonaws.mturk.service.axis.RequesterService; import com.amazonaws.mturk.service.exception.ServiceException; import com.amazonaws.mturk.util.PropertiesClientConfig; import com.amazonaws.mturk.requester.HIT; /** * The MovieSurvey sample application creates a simple HIT using the * Amazon Mechanical Turk SDK for Java. The file mturk.properties must be found in the current file path. */ public class MovieSurvey{ private RequesterService service; // Define the properties of the HIT to be created. private String title = "Movie Survey"; private String description = "This is a survey to find out how many movies you have watched recently."; private int numAssignments = 100; private double reward = 0.05; /** * Constructor */ public MovieSurvey() { service = new RequesterService(new PropertiesClientConfig()); } /** * Create a simple survey. API Version 2008-08-02 20
- 24. Amazon Mechanical Turk Getting Started Guide Creating a HIT Using the API * */ public void createMovieSurvey() { try { // The createHIT method is called using a convenience static method // RequesterService.getBasicFreeTextQuestion() that generates the question format // for the HIT. HIT hit = service.createHIT ( title, description, reward, RequesterService.getBasicFreeTextQuestion( "How many movies have you seen this month?"), numAssignments); // Print out the HITId and the URL to view the HIT. System.out.println("Created HIT: " + hit.getHITId()); System.out.println("HIT location: "); System.out.println(service.getWebsiteURL() + "/mturk/preview?groupId=" + hit.getHITTypeId()); } catch (ServiceException e) { System.err.println(e.getLocalizedMessage()); } } /** * Main method * * @param args */ public static void main(String[] args) { // Create an instance of this class. MovieSurvey app = new MovieSurvey(); // Create the new HIT. app.createMovieSurvey(); } } How to Test Your HIT This section shows how to test your HIT. When you compile and run the code example, your HIT is published on the Amazon Mechanical Turk Developer Sandbox. This is a simulated environment that enables you to view your HIT as it would appear to Workers. The sandbox is a free test environment for all Requesters. To test your HIT 1. Compile and run your project. API Version 2008-08-02 21
- 25. Amazon Mechanical Turk Getting Started Guide Creating a HIT Using the API If no errors occur, you see output similar to the following: Created HIT: 2X6T66XZQARRM98X5030 HIT Location: http://workersandbox.mturk.com/mturk/preview?groupId=2X6T66XZQARRM98X5030 2. Go to the Amazon Mechanical Turk Developer Sandbox and view your HIT. You can rewrite and recompile your HIT as often as necessary. How to Publish Your HIT When you are satisfied with your HIT, publish it on the Amazon Mechanical Turk production system. This makes your HIT available for Workers to complete. To publish your HIT 1. Open the mturk.properties file for your project. 2. Comment out the Developer Sandbox service_url with a "#". #service_url=http://mechanicalturk.sandbox.amazonaws.com/?Service=AWSMechan icalTurkRequester 3. Remove the comment mark # from the Production site service_url. service_url=http://mechanicalturk.amazonaws.com/?Service=AWSMechanicalTurkRe quester 4. Save and close the file. 5. Compile and run your application. Your HIT is now on the production site. Perl This example creates a movie survey using the methods of the Amazon Mechanical Turk SDK for Perl. You must have the SDK installed and configured correctly before you can run this example. How to Create a HIT You can use several different methods to create a HIT. You can define the format for the question and answer in a file. The following example writes the question format and the question in the script file. The example prints out the ID and the location of the new HIT to the console. To create the HIT 1. Add the following line to your module to use the MechanicalTurk class. use NET::Amazon::MechanicalTurk; 2. Define the question format. In this example, this is a string that defines the XML format of the question. API Version 2008-08-02 22
- 26. Amazon Mechanical Turk Getting Started Guide Creating a HIT Using the API my $questionXml = <<END_XML; <?xml version="1.0" encoding="UTF-8"?> <QuestionForm xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurk DataSchemas/2005-10-01/QuestionForm.xsd"> <Question> <QuestionIdentifier>1</QuestionIdentifier> <QuestionContent> <Text>$question</Text> </QuestionContent> <AnswerSpecification> <FreeTextAnswer/> </AnswerSpecification> </Question> </QuestionForm> END_XML 3. Create a string that specifies the question for the HIT. my $question = "How many movies have you seen this month?"; 4. Create a client by creating an instance of the MechanicalTurk class. my $mturk = Net::Amazon::MechanicalTurk->new; 5. Use the CreateHIT() method of the MechanicalTurk class and specify the properties of the HIT. my $result = $mturk->CreateHIT( Title => 'Movie Survey', Description => 'This is a survey to find out how many movies you have watched recently', Keywords => 'movie, survey', Reward => { CurrencyCode => 'USD', Amount => 0.05 }, RequesterAnnotation => 'Movie Survey', AssignmentDurationInSeconds => 60 * 60 * 24, AutoApprovalDelayInSeconds => 60 * 60 * 10, MaxAssignments => 100, LifetimeInSeconds => 60 * 60, Question => $questionXml ); The following example pulls together all the code described in the preceding procedure. #!/usr/bin/perl use strict; use warnings; use Net::Amazon::MechanicalTurk; use Net::Amazon::MechanicalTurk::IOUtil; API Version 2008-08-02 23
- 27. Amazon Mechanical Turk Getting Started Guide Creating a HIT Using the API # Create the question to ask in the HIT. my $question = "How many movies have you seen this month?"; # Create the format for the question. my $questionXml = <<END_XML; <?xml version="1.0" encoding="UTF-8"?> <QuestionForm xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkData Schemas/2005-10-01/QuestionForm.xsd"> <Question> <QuestionIdentifier>1</QuestionIdentifier> <QuestionContent> <Text>$question</Text> </QuestionContent> <AnswerSpecification> <FreeTextAnswer/> </AnswerSpecification> </Question> </QuestionForm> END_XML # Create a MechanicalTurk object. my $mturk = Net::Amazon::MechanicalTurk->new; # Create the HIT with the properties specified. my $result = $mturk->CreateHIT( Title => 'Movie Survey', Description => 'This is a survey to find out how many movies you have watched recently', Keywords => 'movie, survey', Reward => { CurrencyCode => 'USD', Amount => 0.05 }, RequesterAnnotation => 'Movie Survey', AssignmentDurationInSeconds => 60 * 60 * 24, AutoApprovalDelayInSeconds => 60 * 60 * 10, MaxAssignments => 100, LifetimeInSeconds => 60 * 60, Question => $questionXml ); # Print the HIT Id to the console. printf "Created HIT:n"; printf "HITId: %sn", $result->{HITId}[0]; printf "nHIT Location: %sn", $mturk->getHITTypeURL($result->{HITTypeId}[0]); How to Test Your HIT When you run this code example, your HIT is published on the Amazon Mechanical Turk Developer Sandbox by default. This is a simulated environment that enables you to view your HIT as it would appear to Workers. The sandbox is a free test environment for all Requesters. To test your HIT 1. Run the sample to publish the HIT on the Amazon Mechanical Turk Developer Sandbox. If no errors occur, you see output similar to the following: API Version 2008-08-02 24
- 28. Amazon Mechanical Turk Getting Started Guide Creating a HIT Using the API Created HIT: 2X6T66XZQARRM98X5030 HIT Location: http://workersandbox.mturk.com/mturk/preview?groupId=2X6T66XZQAR RM98X5030 2. Go to the Amazon Mechanical Turk Developer Sandbox and view your HIT. You can rewrite and recompile your HIT as often as necessary. How to Publish Your HIT When you are satisfied with your HIT, publish it on the Amazon Mechanical Turk production system. This makes your HIT available for Workers to complete. To publish your HIT 1. Specify the production system in the constructor of the MechanicalTurk object. Your code should look like the following: # Create a MechanicalTurk object. my $mturk = Net::Amazon::MechanicalTurk->new(serviceUrl=>"prod"); 2. Save and close the file. 3. Compile and run your application. Your HIT is now on the production site. Note To go back to using the Developer Sandbox, change the constructor to "sandbox": # Create a MechanicalTurk object. my $mturk = Net::Amazon::MechanicalTurk->new(serviceUrl=>"sandbox"); Ruby This example uses the methods in the Ruby Libraries for Amazon Web Services to create the movie survey. You can use several different methods to create a HIT. You can write the question format and the question in the script file. In this example we create the question and the format in a file, and then print the ID of the new HIT to the console. You must have the Ruby Libraries for Amazon Web Services installed and configured correctly before you run this example. The first time you run this example, or one of the examples in the Ruby Libraries for Mechanical Turk, you must provide your Access Key ID and Secret Access Key. How to Create a HIT This section shows how to create a HIT. To write the HIT 1. Create a question file, moviesurvey.question, that contains the question for your HIT and the template for the question and answer.This is an XML file that conforms to the QuestionForm schema. API Version 2008-08-02 25
- 29. Amazon Mechanical Turk Getting Started Guide Creating a HIT Using the API <?xml version="1.0" encoding="UTF-8"?> <QuestionForm xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurk DataSchemas/2005-10-01/QuestionForm.xsd"> <Question> <QuestionIdentifier>1</QuestionIdentifier> <QuestionContent> <Text>How many movies have you seen this month?</Text> </QuestionContent> <AnswerSpecification> <FreeTextAnswer/> </AnswerSpecification> </Question> </QuestionForm> 2. Require the ruby-aws library. require 'ruby-aws' 3. Use the createHIT() method to create a new HIT. def createNewHIT title = "Movie Survey" desc = "This is a survey to find out how many movies you have watched recently." keywords = "movie, survey" numAssignments = 100 rewardAmount = 0.05 The following example pulls together all the code described in the preceding procedure. #!/usr/bin/env ruby # This sample application creates a simple HIT using Libraries for Amazon Web Services. require 'ruby-aws' @mturk = Amazon::WebServices::MechanicalTurkRequester.new :Host => :Sandbox # Use this line instead if you want the production website. #@mturk = Amazon::WebServices::MechanicalTurkRequester.new :Host => :Production def createNewHIT title = "Movie Survey" desc = "This is a survey to find out how many movies you have watched re cently." keywords = "movie, survey" numAssignments = 100 rewardAmount = 0.05 # 5 cents # Define the location of the externalized question (QuestionForm) file. rootDir = File.dirname $0 questionFile = rootDir + "/moviesurvey.question" API Version 2008-08-02 26
- 30. Amazon Mechanical Turk Getting Started Guide Creating a HIT Using the API # Load the question (QuestionForm) file question = File.read( questionFile ) result = @mturk.createHIT( :Title => title, :Description => desc, :MaxAssignments => numAssignments, :Reward => { :Amount => rewardAmount, :CurrencyCode => 'USD' }, :Question => question, :Keywords => keywords ) puts "Created HIT: #{result[:HITId]}" puts "HIT Location: #{getHITUrl( result[:HITTypeId] )}" return result end def getHITUrl( hitTypeId ) if @mturk.host =~ /sandbox/ "http://workersandbox.mturk.com/mturk/preview?groupId=#{hitTypeId}" # Sandbox Url else "http://mturk.com/mturk/preview?groupId=#{hitTypeId}" # Production Url end end createNewHIT How to Test Your HIT When you run this code example, your HIT is published on the Amazon Mechanical Turk Developer Sandbox by default. This is a simulated environment that enables you to view your HIT as it would appear to Workers. The sandbox is a free test environment for all Requesters. To test your HIT 1. Run the sample to publish the HIT on the Amazon Mechanical Turk Developer Sandbox. If no errors occur, you see output similar to the following: Created HIT: 2X6T66XZQARRM98X5030 HIT Location: http://workersandbox.mturk.com/mturk/preview?groupId=2X6T66XZQAR RM98X5030 2. Go to the Amazon Mechanical Turk Developer Sandbox and view your HIT. You can rewrite and recompile your HIT as often as necessary. How to Publish Your HIT When you are satisfied with your HIT, publish it on the Amazon Mechanical Turk production system. This makes your HIT available for Workers to complete. To publish your HIT 1. In the sample code, find the following line and comment it out: @mturk = Amazon::WebServices::MechanicalTurkRequester.new :Host => :Sandbox API Version 2008-08-02 27
- 31. Amazon Mechanical Turk Getting Started Guide What's Next? 2. In the sample code, remove the comment mark # from the following line: #@mturk = Amazon::WebServices::MechanicalTurkRequester.new :Host => :Produc tion 3. Save and close the file. 4. Run your application. Your HIT is now on the production site. What's Next? You now have a HIT on the Amazon Mechanical Turk product site. You've become familiar with the architecture of the system, some of its basic functionality, and the kind of responses you can expect. The following section explains how to learn more about Amazon Mechanical Turk and how to implement advanced Amazon Mechanical Turk functionality in your applications. API Version 2008-08-02 28
- 32. Amazon Mechanical Turk Getting Started Guide Interfaces Implementing Amazon Mechanical Turk In the preceding tutorial you learned how to complete basic Amazon Mechanical Turk tasks..If you didn't use the tutorial, you can learn how to complete basic and advanced Amazon Mechanical Turk tasks using the Amazon Mechanical Turk Developer Guide and by looking at code samples. For more information, go to Amazon Mechanical Turk Developer Guide and Amazon Mechanical Turk Sample Code and Libraries, respectively. This section discusses how you can increase your understanding of Amazon Mechanical Turk so that you can implement it in your applications. Interfaces Amazon Mechanical Turk offers the following interfaces: • Command line • API • Requester user interface The Amazon Mechanical Turk command line interface (CLI) makes it easy to use most of the Amazon Mechanical Turk functionality. When you wish to have a hands-on approach to using Amazon Mechanical Turk and have a relatively small number of assignments and results, the CLI is a good choice. For more information, go to Amazon Mechanical Turk Command Line Tool Reference. When the number of assignments you have or the number of results you have is large, the Amazon Mechanical Turk API is a good choice. The API exercises all of Amazon Mechanical Turk's functionality and enables you to integrate Amazon Mechanical Turk functions programmatically. For more information, go to Amazon Mechanical Turk Developer Guide. If you have a very large number of similar HITs, consider using the Requester user interface. It merges one question template with lots of question data to create many similar HITs. For more information, go to Amazon Mechanical Turk Requester User Interface. API Version 2008-08-02 29
- 33. Amazon Mechanical Turk Getting Started Guide Considerations Considerations Creating a successful HIT involves more than programming. There is a certain art involved, for example, in pricing a HIT correctly, laying out the question correctly, breaking down the task into HITs, and minimizing the Worker's time spent with the HIT. For that reason, we created a best practices guide that gives detailed instructions about creating an effective HIT. For more information, go to Amazon Mechanical Turk Best Practices Guide. Some of the HITs you create require the Workers to have special skills. You might, for example, publish a HIT that asks for a translation. Whenever you have a HIT that requires specialized skills, we recommend that you qualify the Workers. Only those who pass the test receive the opportunity to work on your HITs. For more information, go to CreateHIT and read about the QualificationRequirement parameter. Once a Worker becomes qualified, you can grant them qualification status so that they no longer need to complete a qualification test before working on your HITs. For more information, go to AssignQualification. Considerations for Writing a HIT This guide presented a HIT for you to use. When you have to create your own, there are several things you should consider: • What is the problem you are trying to solve? What questions do you want the Workers to answer? What is the best way to present the task to Workers? You need this information when you write the description and question for your HIT. You should be familiar with the format to create your question or task. For more information, go to the Amazon Mechanical Turk Developer Guide. • How much do you want to pay Workers? You need to specify a reward for your HIT. Setting too low a reward discourages Workers from working on your HITs. You need to determine what a fair price is for the work you're asking the Workers to do. The best way is to look at similar tasks advertised on the Amazon Mechanical Turk website. For more information, go to the Amazon Mechanical Turk website. • How many responses do you want? This is the number of assignments for your HIT. Sometimes you want only one answer per HIT. When the answer is controversial, however, you might like to get multiple answers (and thus use multiple assignments) per HIT and reach an answer by consensus. • How much time do you want to allow to complete the task? Giving a Worker too long a time potentially delays getting results. Making the duration too short frustrates Workers. Common Use Scenarios This section describes some of the ways you can use Amazon Mechanical Turk. Photo and Video Processing Amazon Mechanical Turk is well-suited for processing images. In the past, companies have used Mechanical Turk to: • Tag objects found in an image for easier searching and advertising targeting • Select from a set of images the best picture to represent a product • Audit user-uploaded images for inappropriate content API Version 2008-08-02 30
- 34. Amazon Mechanical Turk Getting Started Guide Data Verification and Clean-up • Classify objects found in satellite imagery Data Verification and Clean-up Companies with large online catalogs use Amazon Mechanical Turk to identify duplicate entries and verify item details. Examples include: • De-duplication of yellow pages directory listings • Identification of duplicate products in an online product catalog • Verification of restaurant details, such as the phone number or hours of operation Information Gathering The Amazon Mechanical Turk workforce enables you to gather information, such as: • Allowing people to ask questions from a computer or mobile device about any topic and have Workers return results to those questions • Filling out survey data on a variety of topics • Writing reviews, descriptions and blog entries for websites • Finding specific fields or data elements in large legal and government documents Data Processing Use Amazon Mechanical Turk to process data, for example: • Podcast editing and transcription • Human powered translation services • Search engine rating Coding Resources To help you code your applications, we provide the following resources: • Sample Code and Libraries—Take a look on the Resource Center for sample code and libraries written for Amazon Mechanical Turk You can use these code samples as a means of understanding how to implement the Amazon Mechanical Turk API. For more information, go to Amazon Mechanical Turk Sample Code and Libraries. • Customer Forum—We recommend you look at the Amazon Mechanical Turk Forum to get an idea of what other users are doing and to benefit from the questions they've asked The forum can help you understand what you can and can't do with Amazon Mechanical Turk. The forum also serves as a place for you to ask questions that other users or Amazon representatives might answer. You can use the forum to report issues with the service, the API, or the documentation. For more information, go to Amazon Mechanical Turk Discussion Forums. API Version 2008-08-02 31
- 35. Amazon Mechanical Turk Getting Started Guide Advanced Functionality Advanced Functionality The tutorial in this guide showed how to accomplish the basic tasks of creating, testing, and publishing your HITs. The Amazon Mechanical Turk API, however, offers advanced functionality, which the following table summarizes. For more information, go to the Amazon Mechanical Turk Developer Guide. Functionality Description Review the work submitted You reward work well done by paying the Worker. If work is not done well, by Workers you can elect not to pay the Worker and block them from future assignments. For more information, go to GetReviewableHITs, RejectAssignment, BlockWorker, and ApproveAssignment. Give bonuses You might like to give a bonus to a Worker that does especially good work. This gives the Worker incentive to work on one of your other HITs. By rewarding Workers, you can create a small group of qualified people who you know do good work. They, in turn, will prioritize your HITs over others so that Workers complete your HITs in a timely manner. For more information about awarding bonuses, go to GrantBonus. Review results Reviewing the results manually is an option when the number of programmatically assignments is small. As the number of assignments grows, reviewing results programmatically becomes more practical.The Amazon Mechanical Turk API enables you to do that. For more information, go to GetReviewableHITs Cancel a HIT There are times when the results, although accurate, are unexpected and unusable by you. In that case, you have to expire the HIT, revise, and recreate it. For more information, go to ForceExpireHIT. Update HIT properties You can use API operations and the command line tools to update HIT properties, such as Title, Description, Reward, and Keywords. For more information, go to ChangeHITTypeOfHIT. Extend or eliminate HITs You can also use the API operations to extend the completion time for a HIT, expire a HIT early, or add additional assignments. For more information, go to ExtendHIT and DisposeHIT. Communicate with Workers You can use NotifyWorkers to send emails to specified Workers. Return the amount of Before you can publish Amazon Mechanical Turk HITs, your account must money in your account that contain the money required to pay for all of the assignments. You can you use to pay Workers programmatically access the amount of money in your account using GetAccountBalance. Create your own We recommend that you use qualification tests when completing your qualifications for Workers HITs requires specialized skills. You can create your own qualification tests using CreateQualificationType. Reference Resources The following list shows additional resources you can use to further your understanding of Amazon Mechanical Turk. • Learn the pricing for Amazon Mechanical Turk. For more information, go to Pricing. API Version 2008-08-02 32
- 36. Amazon Mechanical Turk Getting Started Guide How to Cancel Your Registration to Amazon Mechanical Turk • Use libraries for Amazon Mechanical Turk written in Java and PHP. For more information, go to Sample Code and Libraries. • The Quick Reference Card provides quick access to important Amazon Mechanical Turk operations and functionality. For more information, go to Quick Reference Card. • When you have questions about developing with Amazon Mechanical Turk visit the customer forum to get your questions answered. A wide variety of questions have already been answered in the forum. If your question has not been answered, ask it and wait for a fellow developer or Amazon representative to help. For more information, go to Amazon Mechanical Turk Developer Forums. • The Service Health Dashboard shows you the status of the Amazon Mechanical Turk web service. The dashboard shows you whether Amazon Mechanical Turk (and all other AWS web services) are functioning properly. For more information, go to Service Health Dashboard. • The Amazon Mechanical Turk Developer Guide provides a detailed discussion of the service. For more information, go to Amazon Mechanical Turk Developer Guide. • The HIT page shows the Amazon Mechanical Turk HITs available to work on. For more information, go to the HIT page. How to Cancel Your Registration to Amazon Mechanical Turk You can cancel your registration with Amazon Mechanical Turk at any time. To cancel your registration with Amazon Mechanical Turk 1. Go to aws.amazon.com 2. Point to Your Account and click Account Activity. The Account Activity page displays. 3. Click the View/Edit Service link under Amazon Mechanical Turk. The View/Edit Service page displays. 4. Click the link, cancel this service. This link is typically in the last sentence of the opening paragraph. API Version 2008-08-02 33
- 37. Amazon Mechanical Turk Getting Started Guide Typographical Conventions Document Conventions This section lists the common typographical and symbol use conventions for AWS technical publications. Typographical Conventions This section describes common typographical use conventions. Convention Description/Example Call-outs A call-out is a number in the body text to give you a visual reference. The reference point is for further discussion elsewhere. You can use this resource regularly. Code in text Inline code samples (including XML) and commands are identified with a special font. You can use the command java -version. Code blocks Blocks of sample code are set apart from the body and marked accordingly. # ls -l /var/www/html/index.html -rw-rw-r-- 1 root root 1872 Jun 21 09:33 /var/www/html/index.html # date Wed Jun 21 09:33:42 EDT 2006 Emphasis Unusual or important words and phrases are marked with a special font. You must sign up for an account before you can use the service. Internal cross references References to a section in the same document are marked. See Document Conventions (p. 34). API Version 2008-08-02 34
- 38. Amazon Mechanical Turk Getting Started Guide Typographical Conventions Convention Description/Example Logical values, A special font is used for expressions that are important to identify, but are constants, and regular not code. expressions, abstracta If the value is null, the returned response will be false. Product and feature Named AWS products and features are identified on first use. names Create an Amazon Machine Image (AMI). Operations In-text references to operations. Use the GetHITResponse operation. Parameters In-text references to parameters. The operation accepts the parameter AccountID. Response elements In-text references to responses. A container for one CollectionParent and one or more CollectionItems. Technical publication References to other AWS publications. If the reference is hyperlinked, it is references also underscored. For detailed conceptual information, see the Amazon Mechanical Turk Developer Guide. User entered values A special font marks text that the user types. At the password prompt, type MyPassword. User interface controls Denotes named items on the UI for easy identification. and labels On the File menu, click Properties. Variables When you see this style, you must change the value of the content when you copy the text of a sample to a command line. % ec2-register <your-s3-bucket>/image.manifest See also the following symbol convention . API Version 2008-08-02 35
- 39. Amazon Mechanical Turk Getting Started Guide Symbol Conventions Symbol Conventions This section describes the common use of symbols. Convention Symbol Description/Example Mutually (Parentheses | and Within a code description, bar separators denote options from exclusive | vertical | bars) which one must be chosen. parameters % data = hdfread (start | stride | edge) Optional [square brackets] Within a code description, square brackets denote completely parameters optional commands or parameters. XML variable text % sed [-n, -quiet] Use square brackets in XML examples to differentiate them from tags. <CustomerId>[ID]</CustomerId> Variables <arrow brackets> Within a code sample, arrow brackets denote a variable that must be replaced with a valid value. % ec2-register <your-s3-bucket>/image.manifest API Version 2008-08-02 36
- 40. Amazon Mechanical Turk Getting Started Guide Document History This What's New is associated with the 2008-08-02 release of Amazon Mechanical Turk. This guide was last updated on April 04, 2011. The following table describes the important changes that have taken place since the last release of the Amazon Mechanical Turk Getting Started Guide. Change Description Release Date Various Edits Numerous sections of the document were edited based on May 1, 2009 internal and customer feedback. Reorganization This guide was reorganized, edited, and moved into a new May 1, 2009 template. API Version 2008-08-02 37