freebase-api

freebase-api provides access to both a raw-access and an abstract-layer to the Freebase API.

Currently supported APIs are :

• Search (doc)
• MQL Read (doc)
• Topic (doc)
• Image support

Add this line to your application's Gemfile:

gem 'freebase-api'

And then execute:

$ bundle

Or install it yourself with:

$ gem install freebase-api

If you have a Google API key, you can set the environment variable GOOGLE_API_KEY, the default session will load it automatically.

You can override the default session by providing some options, like the language or the environment.

FreebaseAPI.session = FreebaseAPI::Session.new(key: 'GOOGLE_API_KEY', env: :stable)

Options are :

• :key : your Google API key
• :env : the environment (sandbox or stable) (default is :stable)
• :proxy : an optional url for a proxy that requests will be sent through
• :query_options : some options that will be used in each query
• :limit : the number of items returned (default is 10)
• :lang : the language you would like the content in (default is 'en')

The DSL of freebase-api is based on 3 main models :

• Topic (used to store topics, types, CVTs)
• Attribute (used to store value typed properties such as string, number, date)
• Image (used to store image data)

To access a specific resource on Freebase, you can use the Topic model which provides some useful methods. The get method is based on the Topic API.

resource = FreebaseAPI::Topic.get('/en/github') # => #<FreebaseAPI::Topic:0x000000021a10d8>

Once the resource is fetched, you can access its properties :

# id
resource.id # => "/m/04g0kcw"

# Name
resource.name # => "GitHub"

# Description
resource.description # => "GitHub is a web-based hosting service for software dev..."

# Types
resource.types # => ["/common/topic", "/internet/website", "/base/technologyofdoing/proposal_agent"]

# Properties
resource.properties.size # => 18

# Access a specific Property
attribute = resource.property('/common/topic/official_website').first # => #<FreebaseAPI::Attribute:0x00000002008500>
attribute.value # => "http://github.com/"

types = resource.property('/type/object/type') # => #<FreebaseAPI::Topic:0x00000002009888>
types.map(&:id) # => equivalent to resource.types

types[1].name # => "Website"
types[1].sync # fetch all the properties of this topic
types[1].description # => "Website or (Web site) is a collection of web pages, typically common..."

# Image
image = property.image(maxwidth: 150, maxheight: 150) # => #<FreebaseAPI::Image:0x00000001fcd4c8>
image.store('/path/to/filename') # record the image

To search topics using a query, you can use FreebaseAPI::Topic.search that returns a Hash ordered by scores (keys). This method supports all the parameters of the official API.

results = FreebaseAPI::Topic.search('jackson') # => [100.55349=>#<FreebaseAPI::Topic:0x000000021e91d0>, 73.209366=>#<FreebaseAPI::Topic:0x000000021f01d8> ...]
best_match = results.values.first # => #<FreebaseAPI::Topic:0x000000021e91d0>
best_match.name # => "Michael Jackson"
best_match.sync
best_match.description # => "Michael Joseph Jackson (August 29, 1958 – June 25, 2009) was an American recording artist..."

FreebaseAPI::Topic.search('Cee Lo Green', filter: '(all type:/music/artist created:"The Lady Killer")')
# => {868.82666=>#<FreebaseAPI::Topic:0x000000029ca250}

To get a raw access to the API, use FreebaseAPI.session. You can use any option or parameter documented in the Freebase API with the following methods.

The search method provides access to Freebase data given a free text query. Please consult the Search Overview and the Search Cookbook for more information on how to construct detailed search queries. All the parameters are supported.

FreebaseAPI.session.search('Cee Lo Green', filter: '(all type:/music/artist created:"The Lady Killer")')

The method returns an Array containing all the results.

[{"mid"=>"/m/01w5jwb",
  "id"=>"/en/cee_lo_1974",
  "name"=>"Cee Lo Green",
  "notable"=>{"name"=>"Singer-songwriter", "id"=>"/m/016z4k"},
  "lang"=>"en",
  "score"=>868.82666}]

The topic method calls a web service that will return all known facts for a given topic including images and text blurbs. You can apply filters to the Topic API so that it only returns the property values that you're interested in. This is ideal for building topic pages and short summaries of an entity. You can consult the API reference here.

FreebaseAPI.session.topic('/en/cee_lo_1974', filter: '/people/person/profession')

The method returns a Hash containing all the properties.

{ "id"=>"/m/01w5jwb",
  "property"=>{
    "/people/person/profession"=>{"valuetype"=>"object", "values"=>[
      {"text"=>"Record producer", "lang"=>"en", "id"=>"/m/0dz3r", "creator"=>"/user/mw_template_bot", "timestamp"=>"2008-10-09T08:34:08.000Z"},
      {"text"=>"Singer-songwriter", "lang"=>"en", "id"=>"/m/016z4k", "creator"=>"/user/mw_template_bot", "timestamp"=>"2008-10-09T08:34:08.000Z"},
      {"text"=>"Actor", "lang"=>"en", "id"=>"/m/02hrh1q", "creator"=>"/user/netflixbot", "timestamp"=>"2011-04-09T04:01:36.001Z"},
      {"text"=>"Rapper", "lang"=>"en", "id"=>"/m/0hpcdn2", "creator"=>"/user/lycel", "timestamp"=>"2011-12-28T07:40:42.002Z"}
    ], "count"=>4.0}
  }
}

The mqlread method provides access to the Freebase database using the Metaweb query language (MQL). You can consult the API reference here.

FreebaseAPI.session.mqlread({
  :type => '/internet/website',
  :id => '/en/github',
  :'/common/topic/official_website' => nil}
)

The method returns a Hash containing the MQL response.

{"/common/topic/official_website"=>"http://github.com/",
 "id"=>"/en/github",
 "type"=>"/internet/website"}

The image method retrieves image data for a given Topic.

FreebaseAPI.session.image('/en/github', maxwidth: 150, maxheight: 150)

The method returns data bytes.

\x89PNG\r\n\x1A\n\x00\x00\x00\rIHDR\x00\x0...

• Check the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
• Check the issue tracker to make sure someone already hasn't requested it and/or contributed it
• Fork the project
• Start a feature/bugfix branch
• Commit and push until you are happy with your contribution
• Make sure to add tests for it. This is important so I don't unintentionally break it in a future version.
• Please try not to mess with the Rakefile, version, or history. If you want, or really need, to have your own version, that is fine, but please isolate it in its own commit so I can cherry-pick around it.

Copyright (c) 2013 Perfect Memory. See LICENSE.txt for further details.