Skip to main content

CrowdLib: A Python Toolkit for Working with Mechanical Turk

Amazon Mechanical Turk is widely used as a platform for research on crowdsourcing. For programmatic use, it provides a web service (REST or SOAP) with a myriad of features. However, the complexity of the API makes it cumbersome to use. In the course of our work on crowdsourcing, we have developed a toolkit that wraps the Mechanical Turk API in a simple object model.


  • Simplifies code needed for Mechanical Turk workflow.
  • You manage HITs using objects with methods and properties that wrap interactions with AMT’s server API.
  • State is automatically stored locally and updated as needed.
  • Encapsulates nearly every aspect of the AMT API. (See Limitations for specifics.)
  • Works with Python 2.5+ (including all 3.x).


# Import CrowdLib and your settings file with your account key and HIT defaults.
import crowdlib as cl, crowdlib_settings, time

# Create a HIT type, with the title and description for this group of HITs.
hit_type = cl.create_hit_type("Who invented this?", "Answer a simple question.")

# Post a HIT.
hit = hit_type.create_hit([cl.text_field("Who invented the umbrella?", "q1")])

# Wait until the HIT has been completed by a worker.
while hit.is_available:
    time.sleep(10) # poll every 10 seconds

# Fetch and print the result.
print( tuple(hit.assignments)[0]["q1"] )

First steps

  1. You can install via easy_install:
    Alternatively, you may download the ZIP file, unzip it, and then either run install or just copy the crowdlib directory to your project.
  2. Get the ZIP file and either run install or just copy the crowdlib directory to your project.
  3. Create a file file and put it in your project directory or somewhere Python can find it.
  4. Write and run your program. The examples might help you get started.