The current state of Mechanical Turk API’s for programming languages is somewhere between “horrible” and “confusing”. It is completely astounding to me how something as simple as a REST/SOAP webservice is confused so much in every single SDK I tried.
The Perl SDK is totally broken and has been for quite some time. I first realized this in one of my first experiences as a Mechanical Turk requester when I had to go through a totally convoluted process to install it to use a script that a friend of mine wrote (think, failing every test and compiling an old version of Perl then forcing the install for it to “work”). This version seems to work, but is not easily discoverable, and is also in Perl. ;)
The PHP SDK is totally confusing. Don’t even try it. It contains gems like building the SOAP responses by itself using string formatting, and this:
/* URL validation - SORT LATER */
function mtValidHTTP($url)
{
return TRUE;
}
All the while being totally confusing internally, coming with no example programs, and renaming a ton of functions.
I didn’t test the C#/Java SDK’s, but seriously, who wants to write a simple program to communicate with Mechanical Turk in C# or Java?
Even when the SDK’s do work, you need to refer to two sets of documentation: to the SDK’s documentation and the official mTurk API documentation. Why? Because many of them come up with their own cutely named methods (get_account_balance → GetAccountBalance).
Python is my favorite language, so after much Google searching I tried to use the boto mTurk connection. It’s a mess, it’s missing a ton of calls (doesn’t seem to have been updated in a long time) and is just overkill for most scripts (all of them).
Download mturkcore.zip (2.4KB) (v 1.0)
Download old SOAP version (requires python-suds, not recommended for future projects) (2.8KB) (v 0.2)
Update 01/26: Version 0.2 released. This fixes a critical bug where the mTurk WDSL was NOT cached! Updating is strongly recommended.
Update 03/19: Version 1.0 released. This is the best version yet! mturkcore no longer uses Suds and now uses the mTurk REST API, the only major SDK I know of to do so! This release however breaks backwards compatibility.
Thanks to all of this, I wrote my own SDK, mturkcore.py. At just 103 lines of code, including documentation, I hope this is a real departure from the past. mturkcore.py is a complete Python Mechanical Turk SDK. It only requires Python 2.7, xmltodict and requests and uses standard Python types for parameters, like str, dict, and list. Some example programs and usage info follows.
Your configuration file, passed as a dict to MechanicalTurk or saved in mturkconfig.json
{
"use_sandbox" : false,
"stdout_log" : false,
"aws_key" : "ACCESSID",
"aws_secret_key" : "PASSWORD",
}
Getting your balance
import mturkcore
m = mturkcore.MechanicalTurk()
m.create_request("GetAccountBalance")
if m.is_valid():
print m.get_response_element("AvailableBalance")
Assigning a qualification
import mturkcore
m = mturkcore.MechanicalTurk()
workers = ["A1ZZZ","A1QQQ"] # Replace these, of course!
for worker in workers:
m.create_request("AssignQualification",{"QualificationTypeId":"2MYQUALIFICATION","WorkerId":worker,"IntegerValue":100})
Known bugs
None anymore :)
I will give this a poke when I get home.
I have been using the CLI as I have little to no experience with Java or C#, so I’m pretty glad I stumbled here from stackoverflow.
Thanks for sharing!
Hey there,
Thanks for making this! I’ve been using it with a good amount of success especially when compared to boto.
I have had one sticking point: sending a create_hit request to sandbox fails when a HITLayoutID is included, but it’s fine when sent to the production site. I get a TypeNotFound error from suds. Any idea why this is? My code is below:
login_dict = {‘use_sandbox’:True,
‘stdout_log’:False,
‘AWS_ACCESS_KEY_ID’:'my_key’,
‘AWS_SECRET_ACCESS_KEY’:'my_secret_key’}
question = {“Title”:”Test Layout”,
“Description”:”Test Description”,
“HITLayoutId”:’the_layout_id’,
“HITLayoutParameter”:[{"Name":"MATCHED_LE_NAME", "Value":LE_NAME},
{"Name":"SOURCE_URL","Value":SOURCE_URL}],
“Reward”:{“Amount”:0.08,”CurrencyCode”:”USD”},
“LifetimeInSeconds”:3600,
“AssignmentDurationInSeconds”:172800
}
mtc.create_request(“CreateHIT”, question)
Also I made sure to use the hit layout ID from the sandbox GUI, so that shouldn’t be an issue.
Any ideas?
@Chris A: That’s very interesting! I have not experimented with this myself, but from what I can see a HIT Layout is what you make on the requester site.
http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_HITLayoutArticle.html
I had no idea that you could use these with the API. That’s quite a cool feature.
I tracked down the issue (sorry for the delay, I also offer paid services if you’re interested ;) ), and it was that for the sandbox I was using an outdated version of the Mechanical Turk WSDL while for production I had the correct version. (2011-12-01 vs 2012-03-29).
To fix this, change the URL in line 58 to http://mechanicalturk.sandbox.amazonaws.com/AWSMechanicalTurk/2012-03-25/AWSMechanicalTurkRequester.wsdl
I’ll update this in mturkcore soon.
Thanks for sharing this neat API : )
Thanks for putting this python SDK together. Really helpful. I am having some difficulty extracting info from API responses though. I can run the examples from the blog post no problem. Here’s where I run into difficulty:
>>a=m.create_request("SearchHITs",{"SortProperty":None,"SortDirection":None})
>>a
...returns list of HITs...
>>m.get_response_element("HITId")
...returns nothing...
>>m.get_all_elements("HITId")
{}
>>type(a)
<type 'instance'>
instance of what? some suds object? I don’t recognize the outputs as a python dict or list. Is it some kind of extracted, formatted xml? I am confused by the format – not sure what it “is”, so I’m not sure how to interact with it.
Thanks again!
Hi,
You’re not doing it right. Take a look at the documentation:
http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_SearchHITsOperation.html
The HIT ID’s are stored in HIT elements. You need to get the HIT element first, then go down to the HITId element.
Actually I recommend using the new mturkcore (I just released it, I’ve been testing it for a few months on my own projects and it seems to be very stable) which outputs OrderedDicts as responses.