The freebase-python library 1.0 is now available! It introduces a new syntax for accessing the freebase api, it updates the available commands to reflect the entire web api, and it introduces some cool schema manipulation utilities. It’s backwards compatible with previous versions of the library.

The new syntax makes it easy to start running with freebase:

> > > import freebase
> > > print freebase.mqlread({"id" : "/en/the_beatles", "name" : None})
{u'id': u'/en/the_beatles', u'name': u'The Beatles'}

You can also access freebase.sandbox as easily:

> > > import freebase.sandbox
> > > print freebase.sandbox.mqlread(...)

freebase-python can now do all of the current api calls that the website handles. For a full list of the api calls and examples, you can refer to http://code.google.com/p/freebase-python/wiki/GettingStarted.

The schema manipulation utilities introduced make it easy copy and move types, properties, and objects. This means that you can save bases to your computer so that their survive a sandbox refresh, keep different versions of your bases and types on your own machine, or move types between bases. There are a few recipes on the freebase-python wiki that you can find here: http://code.google.com/p/freebase-python/w/list?can=2&q=label%3ARecipe%2CSchema-Manipulation

freebase-python is also Google App Engine friendly. You can check out how to write your own app at http://code.google.com/p/freebase-python/wiki/GoogleAppEngine. You can also check out a sample app at http://freebase-images.appspot.com.

There are also more test and more docs!

Installing is easy, if you have easy_install, just say

$ easy_install freebase

If you don’t have easy_install, you can get it by running http://peak.telecommunity.com/dist/ez_setup.py

We often get asked by application developers how to clear the cache. The problem occurs when you have an app that reads from Freebase, then you go edit some data via the Freebase.com website, and expect it to be immediately shown in the app. It won’t be, because of the cache.

To fix this, just use our API’s touch service. This resets the “mwLastWriteTime” cookie and effectively clears your cache. It’s the same thing that happens if you’re using our dev toolbar (press F8 when viewing any Freebase page) and click “Refresh cache”.

Suppose you’ve compiled a detailed database of sneezing in film, tracking the character, location, and cause of each sneeze (illness, allergies, etc). Naturally, you’d like to mash up your data with info in Freebase. What production companies are brave enough to push the limits of sneezing cinema? Do actor-directors tend to give sneezing parts to their own characters? These questions burn to be answered!

Fred Ott’s sneeze (1894), the first motion film to be copyrighted in the United States

The first step in creating a mash-up is to determine how your entities — in this case, movies — match against entities in Freebase. We call this the reconciliation problem, but fortunately there are a couple of ways to tackle it.

The best option, when available, is to use a key. Keys are properties that uniquely identify an entity, like the Freebase GUID for each topic. It’s unlikely that you’ll be lucky enough to have Freebase GUIDs for your data, but there are domain-specific keys that you can use. For example, movies have Netflix IDs and IMDB profile pages, books have ISBNs, commercial products have UPCs, and just about everything in modern music has a MusicBrainz ID.

Reconciling with keys is easy. If Freebase has the key, a single mql query will give you the movie in question. For example, if you have the movie Plan 9 from Outer Space in your database, you could find it in Freebase by the Freebase id, wikipedia article name, wikipedia curid, or the imdb_url.

But if you don’t have a key, how can you reconcile your entities? Fortunately, we’ve come up with an experimental new web API service that exposes some of our reconciliation techniques and makes them easy to use. The service takes a name and a list of Freebase types, and then returns a list of the Freebase topics that are the closest match. Because the service is intended for use with automated reconciliation tools, it also returns a recommendation for how to treat the results.

As an example, let’s try to reconcile something simple, like the well-known classic movie The Pumaman. If you look at the query you’ll see some JSON results that begin like this:

{
    "recommendation": "automerge"
    "results": [
      {
            "score": {
                "aggregate": 1.4,
                "type": 1.0,
                "name": 1.0
            },
            "id": "\/topic\/en\/the_pumaman",
            "name": "The Pumaman"
      },
      <snip...>
    ]
}

In the results the service will make one of three recommendations: “automerge,” “autocreate,” or “suggest.” The “automerge” result is ideal. It means that your program is free to treat the first result as the entity that you’re looking for, and we can add or retrieve whatever information we want about /topic/en/the_pumaman. A recommendation of “autocreate” is also good, and means that your program can automatically create a new topic because there’s nothing in Freebase that matches your query. The “suggest” result is returned when the reconciliation service can’t give a conclusive answer, perhaps because there’s not enough information. For example, there are over fifty John Smiths in Freebase, and more than a dozen films named A Christmas Carol (not including The Muppet Christmas Carol, or the planned 3D adaptation with Jim Carrey). When your program gets a “suggest” recommendation, it’s an indication that additional analysis, and perhaps human input, is needed. For movies, a simple heuristic based around the year the movie was released is usually enough to resolve reconciliation problems.

That’s the quick overview of the reconciliation service. The full technical documentation is here (with more examples). Feedback is welcome on the Freebase Developers’ Mailing list!