CrowdFlower API examples

CrowdFlower sample API calls

I've been using the CrowdFlower API. Their documentation is a little lacking, so here are some concrete examples of the API's usage.

CrowdFlower works like this:

There are Jobs.

Jobs have one or more units. This the actual piece of work that is performed.

An order is the submission of the unit of work to the labor pool

You can create and modify jobs and units without actually submitting an order (of course, then no work will be done)

Judgements are the answers that you get from the workers. A unit can have multiple judgements.

I've changed the job and unit numbers, but I've personally ran and verified all of these commands. Honestly, the API is a little buggy, sometimes you'll get a 302 instead of a 200 on success, but it does work, and they've been pretty responsive in answering my questions so far.

Using cURL

Using PHP

Using Python

Using cURL

JOBS

CREATE


curl -X POST -d "key=YOUR_API_KEY&job[title]=Some+title&job[instructions]=Instructions" -H "application/json" "http://api.crowdflower.com/v1/jobs.json"

UPDATE


curl -H "application/json" -X PUT -D - -d "key=YOUR_API_KEY&job[title]=An updatey" "http://api.crowdflower.com/v1/jobs/63645/update.json"

UPDATE with CML (CrowdFlower Markup Language)

CML is their internal language that lets you deeply customize your job. Notice that the cml field is a url_encoded string (in PHP, that's the urlencode function, with double-quotes escaped with backslashes beforehand.


curl -H "application/json" -X PUT -D - -d "key=YOUR_API_KEY&job[cml]=%3Ch2%3E%0ACount+the+Bananas%3C%2Fh2%3E%0A%0A%3Cimg+src%3D%22http%3A%2F%2Fimages.example.com%2Finstr.jpg%22%3E%0A%0A%3Cimg+src%3D%22%7B%7Bimage_url%7D%7D%22%3E%0A%3Ccml%3Atext+label%3D%22How+many+bananas+are+in+the+tree%3F%22+class%3D%22%22+validates%3D%22required+positiveInteger%22+aggregation%3D%22agg%22%2F%3E" "http://api.crowdflower.com/v1/jobs/63645/update.json"

Keep your command line tidy with something like this:


curl -H "application/json" -X PUT -D - -d "key=YOUR_API_KEY&job[cml]=`php foo.php`" "http://api.crowdflower.com/v1/jobs/63645.json"

DELETE


curl -H "application/json" -X DELETE -D - -d "key=YOUR_API_KEY" "http://api.crowdflower.com/v1/jobs/63636.json"

COPY


curl -H "application/json" -X POST -D - -d "key=YOUR_API_KEY&job[title]=A+Copy" "http://api.crowdflower.com/v1/jobs/63645/copy.json"

GET


curl -H "application/json" "http://api.crowdflower.com/v1/jobs/63638.json?key=YOUR_API_KEY"

STATUS/PING


curl -H "application/json" "http://api.crowdflower.com/v1/jobs/63638/ping.json?key=YOUR_API_KEY"

UNITS

CREATE


curl -X POST -d "key=YOUR_API_KEY&unit[golden]=false&unit[data][somekey]=Some+value" -H "application/json" "http://api.crowdflower.com/v1/jobs/63646/units.json"

STATUS/PING

what's the status of THE PROCESSING of the units in your job - in other words, are they in the system yet?


curl -H "application/json" "http://api.crowdflower.com/v1/jobs/63645/units/ping.json?key=YOUR_API_KEY"

You can monitor this on the command line with something like:


while true; do sleep 5; echo -n `date`": "; curl -H "application/json" "http://api.crowdflower.com/v1/jobs/63645/units/ping.json?key=YOUR_API_KEY"; echo ; done

READ - you need the ID from above


curl -H "application/json" "http://api.crowdflower.com/v1/jobs/63646/units/37278905.json?key=YOUR_API_KEY"

UPDATE - some reason this sends back a 302 but works


curl -X PUT -d "key=YOUR_API_KEY&unit[golden]=true&unit[data][somekey]=Some+updated+value" -H "application/json" "http://api.crowdflower.com/v1/jobs/63645/units/37278931.json"

CANCEL

I'm not sure what this actually does, but it does return OK


curl -X POST -d "key=YOUR_API_KEY" -H "application/json" "http://api.crowdflower.com/v1/jobs/63645/units/37278946/cancel.json"

DELETE

you can't do this after it has been started


curl -X DELETE -d "key=YOUR_API_KEY" -H "application/json" "http://api.crowdflower.com/v1/jobs/63645/units/37278931.json"

Using PHP

See my complete PHP implementation of the CrowdFlower API on GitHub: https://github.com/supertom/php-crowdflower

 /**
  * CrowdFlower API example, upload a file with PHP
  * creates a new job from an uploaded.  
  * If you want to add to an existing job, change the URL below to jobs/XXXX/upload.json?key=$api_key and the request method to PUT
  **/

$file = "/tmp/crowd.csv";
$content_type="text/csv";
$api_key="YOUR_CROWDFLOWER_API_KEY_HERE"
$url = "http://api.crowdflower.com/v1/jobs/upload.json?key=$api_key";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_UPLOAD, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type: $content_type"));
curl_setopt($ch, CURLOPT_INFILE, fopen("/tmp/crowd.csv",'r'));
curl_setopt($ch, CURLOPT_READFUNCTION, create_function('$ch, $fd, $size', 'return fread($fd,$size);'));
curl_setopt($ch, CURLOPT_INFILESIZE, filesize($file));
curl_setopt($ch, CURLOPT_VERBOSE, true);
curl_setopt($ch,CURLOPT_URL,$url);
$response = curl_exec($ch);
$info = curl_getinfo($ch);

print_r($info);
print_r($response);

Using Python

import pycurl
KEY="CROWDFLOWER_API_KEY_HERE"
UPLOAD_URL="http://api.crowdflower.com/v1/jobs/upload.json?key=" + KEY
fname="/tmp/crowd.csv"
c = pycurl.Curl()
#c.setopt(pycurl.VERBOSE, 1)                                                                                                                                                                              
c.setopt(pycurl.URL, UPLOAD_URL)
c.setopt(pycurl.UPLOAD, 1)
c.setopt(pycurl.READFUNCTION, open(fname, 'r').read)
filesize = os.path.getsize(fname)
print "filesize is " + str(filesize)
c.setopt(pycurl.INFILESIZE, filesize)
c.setopt(pycurl.HTTPHEADER, ["Content-Type: text/csv"])

# Start transfer                                                                                                                                                                                          
print 'Uploading file %s to url %s' % (fname, UPLOAD_URL)
c.perform()
c.close()

Back to Code