jeffcrouse / mturk

Mechanical Turk APi for Node

              __             __  
   ____ ___  / /___  _______/ /__
  / __ `__ \/ __/ / / / ___/ //_/
 / / / / / / /_/ /_/ / /  / ,<   
/_/ /_/ /_/\__/\__,_/_/  /_/|_|  

DEPRICATION NOTICE This repository is NO LONGER MAINTAINED. Please consider using mturk-api.

This module is for working with the Mechanical Turk API.

Install

The development of this package has diverged from what's installed on NPM. For the old version, you may want to see the legacy branch, or perhaps this more active fork.

This package is not currently fully documented and tested, but it is a straightforward replication of the MTurk API, and is used in packages such as TurkServer. The easiest way to install is to check it out as a submodule into your Node project.

Use

You must sign up for a Mechanical Turk account and then find your Access Key and Secret Key.

var creds = {accessKey: "YOUR_ACCESS_KEY", secretKey: "YOUR_SECRET_KEY"};
var mturk  = require("../index")({creds: creds, sandbox: true});

Create a HIT Type

The HIT Type defines a bunch of things about the HIT such as approval time, reward, etc. and can be used for multiple HITs. You must register at least one of these before creating a HIT.

var RegisterHITTypeOptions = { 
	Title: "Your HIT Title"
	, Keywords: "keyword1, keyword2, keyword3" 
	, Description: "Your description"
	, Reward: {Amount: 1.0, CurrencyCode: "USD"}
	, AssignmentDurationInSeconds: 3600
	, AutoApprovalDelayInSeconds: 3600
	, QualificationRequirement: [mturk.QualificationRequirements.Adults]
};

mturk.RegisterHITType(RegisterHITTypeOptions, function(err, HITTypeId){
	if (err) throw err;
	console.log("Registered HIT type "+HITTypeId);
});

Create a HIT

Assumes you have HITTypeId (like the one created in the previous step) and some XML (questionXML) that is a QuestionForm data structure, an ExternalQuestion data structure, an HTMLQuestion data structure, or a HITLayoutId with optional parameters.

Use XML:

var CreateHITOptions = {
	'HITTypeId': HITTypeId
	, 'Question': questionXML
	, 'LifetimeInSeconds': 60 * 20  // How long should the assignment last?
	, 'MaxAssignments': 10 			// How many responses do you want?
};

mturk.CreateHIT(CreateHITOptions, function(err, HITId){
	if (err) throw err;
	console.log("Created HIT "+HITId);
});


Or use a Layout:

var LayoutOptions = {
    'HITTypeId': HITTypeId
    , 'HITLayoutId': layoutId
    , 'HITLayoutParameters': {
    	foo: 'bar'
    }
};

Fetch Reviewable HITs

coming soon...

Approve a HIT

coming soon...

Test

To run tests, you first must make a file called test/aws_creds.js with the following:

module.exports = {accessKey: "YOUR_ACCESS_KEY", secretKey: "YOUR_SECRET_KEY"};

Then you can run

npm test

To Do

• Tests for existing API methods that don't have them
• Systematic API method implementation
• Make some simple examples

Other Reading

Before you use this module, it's very helpful to understand exactly how a a HIT, the fundamental unit of work on MTurk, works. This is a great guide: Overview: Lifecycle of a HIT

This module is a pretty straightforward mirror of the MTurk API. So after you read the previous article, check out the API.

mturk's Issues

setNotification not working.

I am trying to enable the notifications of an hitType with no luck. I am missing something?

HITType.create( ..., function ( err, hitType ) {
  var hitTypeId = hitType.id;

  // Notification data
  var url = 'http/localhost/listen';
  var transport = 'REST';
  var events = [ ... ];
  var notification = Notification.build( url, transport, events );
  hitType.setNotification( notification, true, function ( err ) {

update dependencies

you are using very old versions of the dependencies

don't use `*`

this app breaks with express 4

Master and Dev both don't run

From Master when trying to HIT.get

/Applications/MAMP/htdocs/turkmonkey/node_modules/mturk/model/hit.js:42 this.requesterAnnotation = JSON.parse(this.requesterAnnotation); ^ SyntaxError: Unexpected token B at Object.parse (native) at HIT.populateFromResponse (/Applications/MAMP/htdocs/turkmonkey/node_modules/mturk/model/hit.js:42:39) at /Applications/MAMP/htdocs/turkmonkey/node_modules/mturk/model/hit.js:249:13 at /Applications/MAMP/htdocs/turkmonkey/node_modules/mturk/lib/request.js:115:9 at Request.<anonymous> (/Applications/MAMP/htdocs/turkmonkey/node_modules/mturk/lib/xml-native.js:73:7) at Request.EventEmitter.emit (events.js:95:17) at IncomingMessage.<anonymous> (/Applications/MAMP/htdocs/turkmonkey/node_modules/mturk/node_modules/request/main.js:517:14) at IncomingMessage.EventEmitter.emit (events.js:117:20) at _stream_readable.js:920:16 at process._tickCallback (node.js:415:13)

From Dev branch when trying to just run it

/Applications/MAMP/htdocs/turkmonkey/node_modules/mturk/index.js:8 if( Npm ) { ^ ReferenceError: Npm is not defined at Object.<anonymous> (/Applications/MAMP/htdocs/turkmonkey/node_modules/mturk/index.js:8:5)

TDD for assignment-related operations

I'm working hard on the develop branch of this repo, trying to be a good TDD/BDD developer, but I am new to the TDD/BDD and I am stuck.

I am using mocha/chai, and everything is fine for operations like GetAccountBalance, RegisterHITType, CreateHIT, GetHIT, SearchHITs, etc. ie: operations that don't have anything to do with worker-submitted assignments

But I can't figure out how to write good tests for operations like ApproveAssignment that will play nicely with a continuous integration tool like travis-ci. Originally I thought that there could be 2 different sets of tests: one that creates/searches/browses HITs and another that deals with approving and rejecting assignments, but this couldn't be automated.

It seems like a major purpose of the tests it to make sure that the code interacts successfully with the actual mturk API, so using fake input would not be productive.

Any ideas?

Non 200 status codes messages throwing errors in doRequest

Getting the following error when attempting to make a request to the Mechanical Turk API:

TypeError: Cannot call method 'text' of undefined
  at Request._callback (/opt/app/node_modules/mturk/index.js:1057:49)
  at Request.self.callback (/opt/app/node_modules/mturk/node_modules/request/request.js:123:22)
  at Request.EventEmitter.emit (events.js:98:17)
  at Request.<anonymous> (/opt/app/node_modules/mturk/node_modules/request/request.js:893:14)
  at Request.EventEmitter.emit (events.js:117:20)
  at IncomingMessage.<anonymous> (/opt/app/node_modules/mturk/node_modules/request/request.js:844:12)
  at IncomingMessage.EventEmitter.emit (events.js:117:20)
  at _stream_readable.js:919:16
  at /opt/app/node_modules/newrelic/node_modules/continuation-local-storage/node_modules/async-listener/glue.js:177:31
  at process._tickCallback (node.js:419:13)

Seems to be erroring on ​var errMsg = doc.get("//Error/Message").text();​ Could be that the error message coming back from Amazon is improperly formatted or blank? Perhaps there should be a way to check for this? Not sure. Help me out.

Is this project abandoned? New maintainer, perhaps?

Given the lack of any activity over the past year on this project, I just wanted to check if @jefftimesten had perhaps stopped using mturk and is now doing something else.

@srubin, @marclar, @GeoffreyPlitt, @shawnburke, @dogichow, and @neyric all have open pull requests on this project.

Would any of you guys perhaps be interested in making a new fork that integrates all of these? It could be merged into this project at some point, or it could just be maintained by someone else.

I also noticed that @chbrown has done some extensive revising of this library to take out the notification receptor and ORM stuff. Would be curious if he'd pitch in his rationale behind that.