Skip to main content

The Google Refine Python Client Library provides an interface to communicating with a Google Refine server.

Project description

The Google Refine Python Client Library provides an interface to communicating with a Google Refine server.

Currently, the following API is supported:

  • project creation/import, deletion, export

  • facet computation

    • text

    • text filter

    • numeric

    • blank

    • starred & flagged

    • … extensible class

  • ‘engine’: managing multiple facets and their computation results

  • sorting & reordering

  • clustering

  • transforms

  • transposes

  • single and mass edits

  • annotation (star/flag)

  • column

    • move

    • add

    • split

    • rename

    • reorder

    • remove

  • reconciliation

    • reconciliation judgment facet

    • guessing column type

    • querying reconciliation services preferences

    • perform reconciliation


By default the Google Refine server URL is The environment variables GOOGLE_REFINE_HOST and GOOGLE_REFINE_PORT enable overriding the host & port.

In order to run all tests, a live Refine server is needed. No existing projects are affected.


(Someone with more familiarity with python’s byzantine collection of installation frameworks is very welcome to improve/”best practice” all this.)

  1. Install dependencies, which currently is urllib2_file:

    sudo pip install -r requirements.txt

  2. Ensure you have a Refine server running somewhere and, if necessary, set the envvars as above.

  3. Run tests, build, and install:

    python test # to do a subset, e.g., --test-suite tests.test_facet

    python build

    python install

There is a Makefile that will do this too, and more.


The API so far has been filled out from building a test suite to carry out the actions in David Huynh’s Refine tutorial which while certainly showing off a wide range of Refine features doesn’t cover the entire suite. Notable exceptions currently include:

  • reconciliation support is useful but not complete

  • undo/redo

  • Freebase

  • join columns

  • columns from URL


Patches welcome! Source is at

Useful Tools

One aspect of development is watching HTTP transactions. To that end, I found Fiddler on Windows and HTTPScoop invaluable. The latter won’t URL-decode nor nicely format JSON but the Online JavaScript Beautifier will.


Paul Makepeace, author, <>

David Huynh, initial cut

Artfinder, inspiration

Some data used in the test suite has been used from publicly available sources,

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

refine-client-0.2.1.tar.gz (550.9 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page