Ken - A Ruby API for accessing Freebase

I’d like to introduce a project I’ve been working on since a while. I simply called it Ken. Basically Ken is a data layer for knowledge representation. More precisely it’s a Ruby Library that is being built to access the Metaweb Services supplied by Freebase. Just born, the project’s goal is the provision of a concise API for querying and writing structured data.

Freebase is a collaborative database that underlies a huge graph of interconnected nodes, representing knowledge (in a much more structured way than Wikipedia does). That graph can be viewed at a higher level through an object-oriented lens, which leads to easier interaction. To understand the fundamental Metaweb Architecture please read the official MQL Reference Guide (with focus on chapter 2) provided by Freebase.

Normally you would use MQL (Metaweb Query Language) to express queries against the database. If Freebase finds something that matches your request, you get a result back in form of a JSON Hash. With Ken at your hands, you no longer need to parse the JSON result. Instead you can work with Ruby Objects which should be much more convenient.

Enough the talk, let’s play around with young Ken:

Actually this the only way you can use Ken at the moment. But there’s more to come. The development is at an early stage and my focus lies on building a simple API for exploring Freebase Resources first. However, if things go right, you should be able to use this library as a Data Layer (instead of or in addition to ActiveRecord / DataMapper) for your web framework of choice (Merb, Rails).

You can track development progress at Github. There you can find a more detailed explanation on features as well. I’m planning to build a sample app in Ruby On Rails or Merb to demonstrate the features.

Please let me know what you think. There’s so much room for ideas and improvements.
I’d be happy to get your feedback. If you’d like to contribute, I’d be even happier.

Update #1

API Docs now available (generated using the brand-new service).

9 Responses to “Ken - A Ruby API for accessing Freebase”

  1. Is there a way to query for sets of objects rather than individual objects?

    For example if you wanted to retrieve all artists instead of a particular artist.

  2. Michael says:

    Sure. You can retrieve multiple resources by using Ken.all.

    resources = Ken.all(:name => “Apple”, :type => “/music/album”)

    You can specify any MQL Query but in Ruby Hash syntax. Usage is described in the readme (section “Fetching multiple Resources using a query”).

    You may also want to have a look at the Low Level API section.

  3. Thanks. What I’m actually trying to do is retrieve stuff that has geolocation information - e.g. restaurants. It looks like this might be possible but I’m currently going in circles around the graph - e.g. if I do


    I get the British Museum (found the guid by looking thru some freebase dump files!) - but when I look at the attributes I see some stuff about location but never a latitude/longitude. Maybe as it just doesn’t have one? I’m not sure how to tell if I’m searching for something that just isn’t there.

    I’m new to Freebase too in case this isn’t obvious :-)

  4. Michael says:

    Right. It seems not to have latitude/longitude set.

    You should definitely add that missing facts. :)

  5. Can I get at this API via Ken?

    I just tried r=Ken.all(:type=>’/dining/restaurant’) and I guess it is going to take a while :-)

    Doesn’t seem like I can add qualifiers like the geosearch API has, e.g.:

    r=Ken.all(:type=>’/dining/restaurant’, :location=>’San Francisco’, :location_type=>’/location/citytown’,:inside=>true)

    (Incidentally some kind of mix of your gem and the geokit gem would be really cool)

  6. Vlad says:

    Can you give a suggestion on how to get the guid with the article abstract for “New Order” after querying resource = Ken.get(’/en/new_order’)?

    As I understand, I need to get a guid link and then get a guid, but I am a bit lost as to how to do it.

  7. Michael says:

    That’s a good question in general. I didn’t figure out how to get the content of the article abstract at all (even with plain MQL).

    All I know is that it hides somewhere behind /common/topic/article.

    However you can access that attribute like so:

    r = Ken.get(’/en/new_order’)
    r.attribute(’/common/topic/article’).values.first # returns the resource that holds the article abstract.

    But I don’t understand why the following doesn’t work:


    Since I really need that article abstract for my freebase visualization (, I’d love to come around it too ;-)

    Hmm.. maybe so. on the Freebase mailing list has an idea… (


  8. Michael says:

    Ken just got updated.

    Version 0.2.0 now also wraps the new Topic API for easier access of common meta-data.

    Getting the description for New Order is now as simple as:


  9. ELMER says:

    CheapTabletsOnline.Com. Canadian Health&Care.No prescription online pharmacy.Best quality drugs.Special Internet Prices. High quality drugs. Order drugs online

    Buy:Nexium.100% Pure Okinawan Coral Calcium.Prednisolone.Petcam (Metacam) Oral Suspension.Zyban.Retin-A.Valtrex.Mega Hoodia.Human Growth Hormone.Actos.Accutane.Zovirax.Arimidex.Prevacid.Synthroid.Lumigan….