node package manager

mturk-api

NPM version Downloads

alt text

Install

npm install mturk-api

Basic usage

var mturk = require('mturk-api');
 
var config = {
    access : 'ACCESS_KEY_GOES_HERE',
    secret : 'SECRET_KEY_GOES_HERE',
    sandbox: true
}
 
 
mturk.createClient(config).then(function(api){
 
 
  api.req('GetAccountBalance').then(function(res){
    //Do something 
  }).catch(console.error);
 
 
  //Example operation, with params 
  api.req('SearchHITs', { PageSize: 100 }).then(function(res){
     //Do something 
  }).catch(console.error)
 
 
  //MTurk limits the velocity of requests. Normally, 
  //if you exceed their request rate-limit, you will receive a 
  //'503 Service Unavailable' response. As of v2.0, our interface 
  //automatically throttles your requests to 3 per second. 
  for(var i=0; i < 20; i++){
    //These requests will be queued and executed at a rate of 3 per second 
    api.req('SearchHITs', { PageNumber: i }).then(function(res){
      //Do something 
    }).catch(console.error);
  }
 
 
}).catch(console.error);
 
 

Create HIT Example

 
//Import an XML file. You can use one of our examples in the templates folder * 
fs.readFile('./templates/HTMLQuestion.xml', 'utf8', function(err, unescapedXML){
  if(err){console.error(err);return}
  
  //HIT options 
  var params = {
    Title: "Create HIT Example",
    Description: "An example of how to create a HIT",
    Question: _.escape(unescapedXML),//IMPORTANT: XML NEEDS TO BE ESCAPED! 
    AssignmentDurationInSeconds: 180, // Allow 3 minutes to answer 
    AutoApprovalDelayInSeconds: 86400 * 1, // 1 day auto approve 
    MaxAssignments: 100, // 100 worker responses 
    LifetimeInSeconds: 86400 * 3, // Expire in 3 days 
    Reward: {CurrencyCode:'USD', Amount:0.50}
  };
  
  api.req('CreateHIT', params).then(function(res){
    //DO SOMETHING 
  }).catch(console.error);
  
})
 

* To see the all available Question templates, go to our templates folder

Supported API Operations

Operation Required Parameters Unit test
ApproveAssignment { AssignmentId:String }
ApproveRejectedAssignment { AssignmentId:String }
AssignQualification { QualificationTypeId:String, WorkerId:String }
BlockWorker { WorkerId:String, Reason:String }
ChangeHITTypeOfHIT { HITId:String, HITTypeId:String}
CreateHIT { Title:String, Description:String, AssignmentDurationInSeconds:Number, LifetimeInSeconds:Number } OR {HITTypeId:String, LifetimeInSeconds:Number }
CreateQualificationType { Name:String, Description:String, QualificationTypeStatus:String }
DisableHIT { HITId:String }
DisposeHIT { HITId:String }
DisposeQualificationType {QualificationTypeId:String}
ExtendHIT { HITId:String }
ForceExpireHIT { HITId:String }
GetAccountBalance None
GetAssignment { AssignmentId:String }
GetAssignmentsForHIT { HITId:String }
GetBlockedWorkers None
GetBonusPayments { HITId:String } OR { AssignmentId:String }
GetFileUploadURL { AssignmentId:String, QuestionIdentifier:String }
GetHIT { HITId:String }
GetHITsForQualificationType { QualificationTypeId:String }
GetQualificationsForQualificationType { QualificationTypeId:String }
GetQualificationRequests None
GetQualificationScore { QualificationTypeId:String, SubjectId:String}
GetQualificationType { QualificationTypeId:String }
GetRequesterStatistic { Statistic:String, TimePeriod:String }
GetRequesterWorkerStatistic {Statistic:String, WorkerId:String, TimePeriod:String }
GetReviewableHITs None
GetReviewResultsForHIT { HITId:String }
GrantBonus { WorkerId:String, AssignmentId:String, BonusAmount:Object, Reason:String }
GrantQualification { QualificationRequestId:String }
NotifyWorkers { Subject:String, MessageText:String, WorkerId:Array}
RegisterHITType { Title:String, Description:String, Reward:Object, AssignmentDurationInSeconds:Number }
RejectAssignment { AssignmentId:String }
RejectQualificationRequest { QualificationRequestId:String }
RevokeQualification { Subject:String, QualificationTypeId:String, Reason:String }
SearchHITs None
SearchQualificationTypes { MustBeRequestable:Boolean }
SendTestEventNotification { Notification:Object, TestEventType:Object }
SetHITAsReviewing { HITId:String }
SetHITTypeNotification { HITTypeId:String, Notification:Object, }
UnblockWorker { WorkerId:String, }
UpdateQualificationScore { QualificationTypeId:String, SubjectId:String, IntegerValue:Number }
UpdateQualificationType { QualificationTypeId:String }

License

MIT © Jose Barrios

Banner derived from Cosmin Cuciureanu's BrainUP