Instead of providing a QuestionForm data structure that tells Mechanical Turk how to display your questions and collect answers, you can host the questions on your own web site using an "external" question.
A HIT with an external question displays a web page from your web site in a frame in the Worker's web browser. Your web page displays a form for the Worker to fill out and submit. The Worker submits results using your form, and your form submits the results back to Mechanical Turk. Using your web site to display the form gives your web site control over how the question appears and how answers are collected.
To use an external question with a HIT,
you provide a
structure as the value of the
parameter. As with the
ExternalQuestion is a
string value that consists of XML data. This data must conform
ExternalQuestion schema. See
WSDL and Schema Locations for the
location of this schema. For more information about using XML
data as a parameter or return value, see Using XML
You can only use an external question as the question of a HIT. You cannot use an external question with a Qualification test.
ExternalQuestion data structure is used as a parameter value for the
ExternalQuestion data structure is a
value in a HIT data
All elements in a
ExternalQuestion belong to
a namespace whose name is identical to the URL of the
ExternalQuestion schema document for the
version of the API you are using.
ExternalQuestion data structure has a root element of
ExternalQuestion element contains the following elements:
The URL of your web form, to be displayed in a frame in the Worker's web browser.
Mechanical Turk appends three parameters to this
A valid URL
The height of the frame, in pixels.
A number of pixels
The following is an example of a complete
ExternalQuestion data structure.
Remember that to pass this structure in as the value of a
parameter to an operation, XML characters must be escaped as
character entities. (See Using XML Parameter Values for more information.)
[the ExternalQuestion schema URL]"> <ExternalURL>http://tictactoe.amazon.com/gamesurvey.cgi?gameid=01523</ExternalURL> <FrameHeight>400</FrameHeight> </ExternalQuestion>
When a Worker attempts to complete a HIT with an external question, the external web site is loaded into a frame in the middle of the screen. The web page at that URL should display a form for the Worker to fill out, and all the information the Worker will need to complete the HIT.
The URL used for the frame is the
ExternalURL of the question with two
parameters appended: the
hitId and the
assignmentId. These parameters are appended
CGI-style: The full URL has a question mark (
before the first parameter, and an ampersand
&) between each parameter, with each
parameter consisting of a name, an equal sign
=), and a value. Other parameters already
present in this style in
are preserved, so the final URL will only have one question
mark, and all parameters will be separated by ampersands.
For example, consider an
ExternalURL, the full URL
used for the page in the frame could be as follows:
http://tictactoe.amazon.com/gamesurvey.cgi?gameid=01523 &hitId=123RVWYBAZW00EXAMPLE &assignmentId=123RVWYBAZW00EXAMPLE456RVWYBAZW00EXAMPLE
Your external question will be displayed when a Worker
previews the HIT on the Amazon Mechanical Turk web site,
before the Worker has clicked the "Accept HIT" button. When
the HIT is being previewed, the URL will have a special value
When a Worker previews a HIT, your web page should show her everything she will need to do to complete the HIT, so she can decide whether or not to accept it. The easiest way to do this is to simply display the form as it would appear when the HIT is accepted. However, you may want to take precautions to prevent a Worker from accidentally filling out or submitting your form prior to accepting the HIT.
assignmentId parameter, and change the display
the form if the HIT is being previewed
If a Worker submits your form before accepting the HIT, and your form attempts to post the data back to Mechanical Turk, Mechanical Turk will display an error message to the Worker, and the results will not be accepted.
When a Worker accepts your HIT, you can get the ID of the Worker. If your HIT contains
a Java Applet, an IFrame, or embedded binary data, the URL contains a value for the
workerId. If your HIT does not contain these types of
data, or if a Worker has not accepted the HIT, the
The form on the external web site must post the result data back to Amazon Mechanical Turk using the following URL:
The form must include the
assignmentId field that
was appended to the URL used to access your form. It should
be submitted along with the other form fields submitted by
your form, with a name of
assignmentId and the
same value as was passed to the form. Be sure to spell the
field name as it appears here, with the same letters uppercase
The field names
The form can submit data to that URL using either the "GET" or "POST" methods. The data the form submits should be name-value pairs in the CGI-style:
Each field appears as the name, an equal sign, and the
value. For example:
Data that appears in the posted URL (using the "GET"
method or the form's action URL) is preceded by a question
?), and is delimited by ampersands
&). For example:
Data that appears in the HTTP message body (using the "POST" method) has one data pair per line. For example:
favoriteColor=blue favoriteNumber=7 ...
The easiest way to post the data in the CGI-style is to use an
HTML form on the web page, with the
as the "action," and either "GET" or "POST" as the "method."
When the Worker submits your form, the form sends the field data
to Mechanical Turk using the
and Mechanical Turk records the field data as the results of the
When you retrieve the results using the
GetAssignmentsForHIT operation, the
field data submitted by your form will appear in the
Answer of the Assignment
as if each field were a free-text answer. The
QuestionIdentifier element of the answer
will be the name of the field, and the
FreeText element will contain the value.
See the QuestionFormAnswers data format for more information about the format of answer data.
External questions give your application a great deal of power over how Workers submit results for your HITs. To ensure you get good results for your HITs, you should make sure your web server and web pages can provide your Workers with a quality experience.
Because external questions depend on your web server for rendering the question form, both while Workers are previewing HITs and while Workers are completing HITs, your server will need to be engineered for high availability. The Amazon Mechanical Turk web site gets heavy traffic, so your web server will need to be able to respond quickly and correctly when receiving many requests in a short period of time.
Amazon S3 offers high availability hosting of data, accessible via public URLs. You can host your external questions as web pages in Amazon S3, and not have to run your own high availability web server.
Your web site can do many things inside the frame, but eventually it must cause the Worker's browser to load the "externalSubmit" URL in the frame with the results in POST data. The easiest way to do this is with an HTML form whose fields contain the HIT results, with a submit button that the Worker will click. If an external HIT prevents the Worker from submitting results back to Mechanical Turk using the "externalSubmit" mechanism, the Worker may not be able to claim rewards or continue doing work without restarting their session. Amazon Mechanical Turk reserves the right to remove any external HITs that are not functioning properly.
Remember that a QuestionForm can contain Java applets, Flash applications, and blocks of XHTML formatted content. If the capabilities of a QuestionForm meet the needs of your HIT, using a QuestionForm instead of an ExternalQuestion is the best way to ensure that your HIT will work correctly.
Finally, please remember that external questions must meet the Amazon Mechanical Turk Participation Agreement, and otherwise meet Mechanical Turk's standards for appropriate content. Specifically, the Participation Agreement expressly prohibits the use of Amazon Mechanical Turk for advertising or solicitation. If your web site typically displays advertising to visitors, please make sure those advertisements do not appear in your external questions. Amazon Mechanical Turk reserves the right to remove HITs with inappropriate content.