mturk

Documentation

Overview

This package is in an experimental state, and does not currently follow conventions and style of the rest of goamz or common Go conventions. It must be polished before it's considered a first-class package in goamz.

Index

• type Assignment
  • func (a Assignment) Answers() (answers map[string]string)
• type CreateHITResponse
• type Error
  • func (err *Error) Error() string
• type ExternalQuestion
• type GetAssignmentsForHITResponse
• type GetHITResponse
• type HIT
• type HTMLContent
• type HTMLQuestion
• type Locale
• type MTurk
  • func New(auth aws.Auth, sandbox bool) *MTurk
  • func (mt *MTurk) CreateHIT(title, description string, question interface{}, reward Price, ...) (h *HIT, err error)
  • func (mt *MTurk) CreateHITOfType(hitTypeId string, q ExternalQuestion, lifetimeInSeconds uint, ...) (h *HIT, err error)
  • func (mt *MTurk) GetAssignmentsForHIT(hitId string, addParams ...string) (r []Assignment, err error)
  • func (mt *MTurk) GetHIT(hitId string, addParams ...string) (h *HIT, err error)
  • func (mt *MTurk) SearchHITs(addParams ...string) (s *SearchHITsResult, err error)
• type Price
• type QualificationRequirement
• type SearchHITsResponse
• type SearchHITsResult

Examples

• New

Types

type Assignment

type Assignment struct {
	AssignmentId     string
	WorkerId         string
	HITId            string
	AssignmentStatus string
	AutoApprovalTime string
	AcceptTime       string
	SubmitTime       string
	ApprovalTime     string
	Answer           string
}

func (Assignment) Answers

func (a Assignment) Answers() (answers map[string]string)

type CreateHITResponse

type CreateHITResponse struct {
	RequestId string `xml:"OperationRequest>RequestId"`
	HIT       HIT
}

The wrapper data structure returned by CreateHIT http://goo.gl/PskcX

type Error

type Error struct {
	StatusCode int    // HTTP status code (200, 403, ...)
	Code       string // EC2 error code ("UnsupportedOperation", ...)
	Message    string // The human-oriented error message
	RequestId  string
}

Error encapsulates an error returned by MTurk.

func (*Error) Error

func (err *Error) Error() string

type ExternalQuestion

type ExternalQuestion struct {
	XMLName     xml.Name `xml:"http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2006-07-14/ExternalQuestion.xsd ExternalQuestion"`
	ExternalURL string
	FrameHeight int
}

Data structure holding the contents of an "external" question. http://goo.gl/NP8Aa

type GetAssignmentsForHITResponse

type GetAssignmentsForHITResponse struct {
	RequestId                  string `xml:"OperationRequest>RequestId"`
	GetAssignmentsForHITResult struct {
		Request         xmlRequest
		NumResults      uint
		TotalNumResults uint
		PageNumber      uint
		Assignments     []Assignment `xml:"Assignment"`
	}
}

type GetHITResponse

type GetHITResponse struct {
	RequestId string `xml:"OperationRequest>RequestId"`
	HIT       HIT
}

type HIT

type HIT struct {
	Request xmlRequest

	HITId                        string
	HITTypeId                    string
	CreationTime                 string
	Title                        string
	Description                  string
	Keywords                     string
	HITStatus                    string
	Reward                       Price
	LifetimeInSeconds            uint
	AssignmentDurationInSeconds  uint
	MaxAssignments               uint
	AutoApprovalDelayInSeconds   uint
	QualificationRequirement     QualificationRequirement
	Question                     interface{}
	RequesterAnnotation          string
	NumberofSimilarHITs          uint
	HITReviewStatus              string
	NumberOfAssignmentsPending   uint
	NumberOfAssignmentsAvailable uint
	NumberOfAssignmentsCompleted uint
}

The data structure representing a "human interface task" (HIT) Currently only supports "external" questions, because Go structs don't support union types. http://goo.gl/NP8Aa This type is returned, for example, from SearchHITs http://goo.gl/PskcX

type HTMLContent

type HTMLContent struct {
	Content string `xml:",innerxml"`
}

Holds the html content of the HTMLQuestion.

type HTMLQuestion

type HTMLQuestion struct {
	XMLName     xml.Name `xml:"http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2011-11-11/HTMLQuestion.xsd HTMLQuestion"`
	HTMLContent HTMLContent

	FrameHeight int
}

Data structure holding the contents of an "html" question. http://goo.gl/hQn5An

type Locale

type Locale string

Really just a country string.

Reference:

- http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_LocaleDataStructureArticle.html - http://www.iso.org/iso/country_codes/country_codes

type MTurk

type MTurk struct {
	aws.Auth
	URL *url.URL
}

func New

func New(auth aws.Auth, sandbox bool) *MTurk

Example

package main

import (
	"fmt"
	"github.com/AdRoll/goamz/aws"
	"github.com/AdRoll/goamz/exp/mturk"
)

var turk *mturk.MTurk

func main() {
	// These are your AWS tokens. Note that Turk do not support IAM.
	// So you'll have to use your main profile's tokens.
	var auth = aws.Auth{AccessKey: "<ACCESS_KEY>", SecretKey: "<SECRET_KEY>"}
	turk = mturk.New(auth, true) // true to use sandbox mode
}

func Examplemturk_CreateHIT_withExternalQuestion() {
	question := mturk.ExternalQuestion{
		ExternalURL: "http://www.amazon.com",
		FrameHeight: 200,
	}
	reward := mturk.Price{
		Amount:       "0.01",
		CurrencyCode: "USD",
	}

	hit, err := turk.CreateHIT("title", "description", question, reward, 30, 30, "key1,key2", 3, nil, "annotation")

	if err == nil {
		fmt.Println(hit)
	}
}

func Examplemturk_CreateHIT_withHTMLQuestion() {
	question := mturk.HTMLQuestion{
		HTMLContent: mturk.HTMLContent{`<![CDATA[
<!DOCTYPE html>
<html>
 <head>
  <meta http-equiv='Content-Type' content='text/html; charset=UTF-8'/>
  <script type='text/javascript' src='https://s3.amazonaws.com/mturk-public/externalHIT_v1.js'></script>
 </head>
 <body>
  <form name='mturk_form' method='post' id='mturk_form' action='https://www.mturk.com/mturk/externalSubmit'>
  <input type='hidden' value='' name='assignmentId' id='assignmentId'/>
  <h1>What's up?</h1>
  <p><textarea name='comment' cols='80' rows='3'></textarea></p>
  <p><input type='submit' id='submitButton' value='Submit' /></p></form>
  <script language='Javascript'>turkSetAssignmentID();</script>
 </body>
</html>
]]>`},
		FrameHeight: 200,
	}
	reward := mturk.Price{
		Amount:       "0.01",
		CurrencyCode: "USD",
	}

	hit, err := turk.CreateHIT("title", "description", question, reward, 30, 30, "key1,key2", 3, nil, "")

	if err == nil {
		fmt.Println(hit)
	}
}

func (*MTurk) CreateHIT

func (mt *MTurk) CreateHIT(
	title, description string,
	question interface{},
	reward Price,
	assignmentDurationInSeconds,
	lifetimeInSeconds uint,
	keywords string,
	maxAssignments uint,
	qualificationRequirement *QualificationRequirement,
	requesterAnnotation string,
	addParams ...string) (h *HIT, err error)

CreateHIT corresponds to the "CreateHIT" operation of the Mechanical Turk API. Currently only supports "external" questions (see "HIT" struct above).

Here are the detailed description for the parameters:

title         Required. A title should be short and descriptive about the
              kind of task the HIT contains. On the Amazon Mechanical Turk
              web site, the HIT title appears in search results, and
              everywhere the HIT is mentioned.
description   Required. A description includes detailed information about the
              kind of task the HIT contains. On the Amazon Mechanical Turk
              web site, the HIT description appears in the expanded view of
              search results, and in the HIT and assignment screens. A good
              description gives the user enough information to evaluate the
              HIT before accepting it.
question      Required. The data the person completing the HIT uses to produce
              the results. Consstraints: Must be a QuestionForm data structure,
              an ExternalQuestion data structure, or an HTMLQuestion data
              structure. The XML question data must not be larger than 64
              kilobytes (65,535 bytes) in size, including whitespace.
reward        Required. The amount of money the Requester will pay a Worker
              for successfully completing the HIT.
assignmentDurationInSeconds   Required. The amount of time, in seconds, that
                              a Worker has to complete the HIT after accepting
                              it. If a Worker does not complete the assignment
                              within the specified duration, the assignment is
                              considered abandoned.  If the HIT is still
                              active (that is, its lifetime has not elapsed),
                              the assignment becomes available for other users
                              to find and accept. Valid Values: any integer
                              between 30 (30 seconds) and 31536000 (365 days).
lifetimeInSeconds     Required. An amount of time, in seconds, after which the
                      HIT is no longer available for users to accept. After
                      the lifetime of the HIT elapses, the HIT no longer
                      appears in HIT searches, even if not all of the
                      assignments for the HIT have been accepted. Valid Values:
                      any integer between 30 (30 seconds) and 31536000 (365 days).
keywords              One or more words or phrases that describe the HIT,
                      separated by commas. These words are used in searches to
                      find HITs. Constraints: cannot be more than 1,000
                      characters.
maxAssignments        The number of times the HIT can be accepted and completed
                      before the HIT becomes unavailable. Valid Values: any
                      integer between 1 and 1000000000 (1 billion). Default: 1
qualificationRequirement    A condition that a Worker's Qualifications must
                            meet before the Worker is allowed to accept and
                            complete the HIT. Constraints: no more than 10
                            QualificationRequirement for each HIT.
requesterAnnotation   An arbitrary data field. The RequesterAnnotation
                      parameter lets your application attach arbitrary data to
                      the HIT for tracking purposes.  For example, the
                      RequesterAnnotation parameter could be an identifier
                      internal to the Requester's application that corresponds
                      with the HIT. Constraints: must not be longer than 255
                      characters in length.

Reference: http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_CreateHITOperation.html

func (*MTurk) CreateHITOfType

func (mt *MTurk) CreateHITOfType(hitTypeId string,
	q ExternalQuestion,
	lifetimeInSeconds uint,
	maxAssignments uint,
	requesterAnnotation string,
	addParams ...string) (h *HIT, err error)

Corresponds to the "CreateHIT" operation of the Mechanical Turk API, using an existing "hit type". http://goo.gl/cDBRc Currently only supports "external" questions (see "HIT" struct above). If "maxAssignments" or "requesterAnnotation" are the zero value for their types, they will not be included in the request.

func (*MTurk) GetAssignmentsForHIT

func (mt *MTurk) GetAssignmentsForHIT(hitId string, addParams ...string) (r []Assignment, err error)

Get the Assignments for a HIT.

func (*MTurk) GetHIT

func (mt *MTurk) GetHIT(hitId string, addParams ...string) (h *HIT, err error)

Get a single HIT

func (*MTurk) SearchHITs

func (mt *MTurk) SearchHITs(addParams ...string) (s *SearchHITsResult, err error)

Corresponds to "SearchHITs" operation of Mechanical Turk. http://goo.gl/PskcX Currenlty supports none of the optional parameters.

type Price

type Price struct {
	// The amount of money, as a number. The amount is in the currency specified
	// by the CurrencyCode. For example, if CurrencyCode is USD, the amount will
	// be in United States dollars (e.g. 12.75 is $12.75 US).
	Amount string

	// A code that represents the country and units of the currency. Its value is
	// Type an ISO 4217 currency code, such as USD for United States dollars.
	//
	// Constraints: Currently only USD is supported.
	CurrencyCode string

	// A textual representation of the price, using symbols and formatting
	// appropriate for the currency. Symbols are represented using the Unicode
	// character set. You do not need to specify FormattedPrice in a request.
	// It is only provided by the service in responses, as a convenience to
	// your application.
	FormattedPrice string
}

A Price represents an amount of money in a given currency.

Reference: http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_PriceDataStructureArticle.html

type QualificationRequirement

type QualificationRequirement struct {
	// The ID of the Qualification type for the requirement.
	// See http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QualificationRequirementDataStructureArticle.html#ApiReference_QualificationType-IDs
	QualificationTypeId string

	// The kind of comparison to make against a Qualification's value.
	// Two values can be compared to see if one value is "LessThan",
	// "LessThanOrEqualTo", "GreaterThan", "GreaterThanOrEqualTo", "EqualTo", or
	// "NotEqualTo" the other. A Qualification requirement can also test if a
	// Qualification "Exists" in the user's profile, regardless of its value.
	Comparator string

	// The integer value to compare against the Qualification's value.
	IntegerValue int

	// The locale value to compare against the Qualification's value, if the
	// Qualification being compared is the locale Qualification.
	LocaleValue Locale

	// If true, the question data for the HIT will not be shown when a Worker
	// whose Qualifications do not meet this requirement tries to preview the HIT.
	// That is, a Worker's Qualifications must meet all of the requirements for
	// which RequiredToPreview is true in order to preview the HIT.
	//
	// If a Worker meets all of the requirements where RequiredToPreview is true
	// (or if there are no such requirements), but does not meet all of the
	// requirements for the HIT, the Worker will be allowed to preview the HIT's
	// question data, but will not be allowed to accept and complete the HIT.
	RequiredToPreview bool
}

A QualificationRequirement describes a Qualification a Worker must have before the Worker is allowed to accept a HIT. A requirement may optionally state that a Worker must have the Qualification to preview the HIT.

Reference:

http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QualificationRequirementDataStructureArticle.html

type SearchHITsResponse

type SearchHITsResponse struct {
	RequestId        string `xml:"OperationRequest>RequestId"`
	SearchHITsResult SearchHITsResult
}

The wrapper data structure returned by SearchHITs http://goo.gl/PskcX

type SearchHITsResult

type SearchHITsResult struct {
	NumResults      uint
	PageNumber      uint
	TotalNumResults uint
	HITs            []HIT `xml:"HIT"`
}

The main data structure returned by SearchHITs http://goo.gl/PskcX