freebase-api 0.1

data/lib/freebase_api/session.rb

@@ -0,0 +1,114 @@
+require 'httparty'
+require 'json'
+
+module FreebaseAPI
+  class Session
+    include HTTParty
+    disable_rails_query_string_format
+
+    attr_reader :env, :key, :query_options
+
+    # URIs of the Freebase API
+    API_URL = "https://www.googleapis.com/freebase/v1"
+    SANDBOX_API_URL = "https://www.googleapis.com/freebase/v1sandbox"
+
+    # Freebase default values
+    DEFAULT_LIMIT = 10
+    DEFAULT_LANGUAGE = :en
+
+    def initialize(options={})
+      options = { :env => :stable, :query_options => { :limit => DEFAULT_LIMIT, :lang => DEFAULT_LANGUAGE } }.deep_merge(options)
+      @env = options[:env]
+      @key = options[:key] || ENV['GOOGLE_API_KEY']
+      @query_options = options[:query_options]
+    end
+
+    # Execute a MQL read query
+    # @see https://developers.google.com/freebase/v1/mql-overview
+    #
+    # @param [Hash] query the MQL query
+    # @param [Hash] options the MQL query options
+    # @return [Hash] the response
+    def mqlread(query, options={})
+      params = { :query => query.to_json, :lang => "/lang/#{@query_options[:lang]}", :limit => @query_options[:limit] }.merge(options)
+      response = get(surl('mqlread'), params, format: :json)
+      response['result']
+    end
+
+    # Execute a Search query
+    # @see https://developers.google.com/freebase/v1/search
+    #
+    # @param [String] query the query to search
+    # @param [Hash] options the options
+    # @return [Hash] the response
+    def search(query, options={})
+      params = { :query => query, :lang => @query_options[:lang], :limit => @query_options[:limit] }.merge(options)
+      response = get(surl('search'), params, format: :json)
+      response['result']
+    end
+
+    # Execute a Topic query
+    # @see https://developers.google.com/freebase/v1/topic
+    #
+    # @param [String] id the topic ID
+    # @param [Hash] options the options
+    # @return [Hash] the response
+    def topic(id, options={})
+      params = { :lang => @query_options[:lang], :limit => @query_options[:limit] }.merge(options)
+      get(surl('topic') + id, params, format: :json).parsed_response
+    end
+
+    # Execute a Image Service query
+    # @see https://developers.google.com/freebase/v1/topic-response#references-to-image-objects
+    #
+    # @param [String] id the topic ID
+    # @param [Hash] options the options
+    # @return [Hash] the response
+    def image(id, options={})
+      params = options
+      get(surl('image') + id, params).body
+    end
+
+    private
+
+    # Return the URL of a Freebase service
+    #
+    # @param [String] service the service
+    # @return [String] the url of the service
+    def surl(service)
+      service_url = @env == :stable ? API_URL : SANDBOX_API_URL
+      service_url = service_url + "/" + service
+      service_url.gsub!('www', 'usercontent') if service.to_s == 'image'
+      service_url
+    end
+
+    # Make a GET request
+    #
+    # @param [String] url the url to request
+    # @param [Hash] params the params of the request
+    # @return the request response
+    def get(url, params={}, options={})
+      FreebaseAPI.logger.debug("GET #{url}")
+      params[:key] = @key if @key
+      response = self.class.get(url, :format => options[:format], :query => params)
+      handle_response(response)
+    end
+
+    # Handle the response
+    #
+    # If success, return the response body
+    # If failure, raise an error
+    def handle_response(response)
+      case response.code
+      when 200..299
+        response
+      else
+        if response.request.format == :json
+          raise FreebaseAPI::ServiceError.new(response['error'])
+        else
+          raise FreebaseAPI::NetError.new('code' => response.code, 'message' => response.response.message)
+        end
+      end
+    end
+  end
+end

data/lib/freebase_api/topic.rb

@@ -0,0 +1,186 @@
+module FreebaseAPI
+  class Topic
+
+    # The maximum number of property values to return.
+    PROPERTIES_LIMIT = 100
+
+    attr_reader :properties
+
+    class << self
+      # Returns a new Topic filled with all the Freebase properties
+      #
+      # @param [String] id the Freebase ID
+      # @param [Hash] options the options
+      # @return [Topic] the topic
+      def get(id, options={})
+        topic = Topic.new(id, options)
+        topic.sync
+        topic
+      end
+
+      # Search using a query and returns the results as a hash of topics score based
+      #
+      # @param [String] query the string query
+      # @param [Hash] options the options
+      # @return [Hash] the topics
+      def search(query, options={})
+        hash = {}
+        FreebaseAPI.session.search(query, options).each do |topic|
+          hash[topic['score'].to_f] = Topic.new(topic['mid'], :data => construct_data(topic))
+        end
+        hash
+      end
+
+      private
+
+      # @private
+      def construct_data(topic)
+        lang = topic['lang']
+        data = {
+          "id" => topic['mid'],
+          "lang" => lang,
+          "property" => {
+            "/type/object/name" => {
+              "valuetype" => "string",
+              "values" => [
+                {
+                 "text" => "#{topic['name']}",
+                 "lang" => lang,
+                 "value" => "#{topic['name']}"
+                }
+              ]
+            }
+          }
+        }
+        data["property"]["/common/topic/notable_for"] = {
+          "valuetype" => "object",
+          "values" => [
+            {
+             "text" => topic['notable']['name'],
+             "lang" => lang,
+             "id" => topic['notable']['id']
+            }
+          ],
+        } if topic.has_key?('notable')
+        data
+      end
+    end
+
+    def initialize(id, options={})
+      @properties = {}
+      @excluded_properties = parse_exclusion(options.delete(:exclude))
+      @options = { :filter => 'commons' }.merge(options)
+      @data = { 'id' => id }.merge(options[:data] || {})
+      build
+    end
+
+    def id
+      @data['id']
+    end
+
+    def text
+      @data['text']
+    end
+
+    def lang
+      @data['lang']
+    end
+
+    def name
+      @name ||= extract_name
+    end
+
+    def types
+      @types ||= extract_types
+    end
+
+    def description
+      @description ||= extract_description
+    end
+
+    def property(name)
+      @properties[name]
+    end
+
+    def properties_domains
+      domains = {}
+      properties.keys.each do |prop|
+        d = prop.split('/')[1]
+        domains[d] ||= 0
+        domains[d] += properties[prop].size
+      end
+      domains
+    end
+
+    def sync
+      @data = FreebaseAPI.session.topic(self.id, @options)
+      build
+    end
+
+    def image(options={})
+      FreebaseAPI::Image.get(self.id, options)
+    end
+
+    private
+
+    def extract_name
+      if names = property('/type/object/name')
+        names.first.value
+      else
+        text
+      end
+    end
+
+    def extract_types
+      if types = property('/type/object/type')
+        types.map(&:id)
+      else
+        []
+      end
+    end
+
+    def extract_description
+      if articles = property('/common/topic/article')
+        articles.first.property('/common/document/text').first.value
+      end
+    end
+
+    def parse_exclusion(exclusion)
+      if !exclusion
+        []
+      elsif exclusion.is_a?(Array)
+        exclusion
+      else
+        [exclusion]
+      end
+    end
+
+    def build
+      if @data['property']
+        FreebaseAPI.logger.debug("Building topic #{self.id} : #{@data['property'].size} properties")
+        @data['property'].each do |key, value|
+          build_property(key, value)
+        end
+      end
+      invalidate_lazy_properties
+    end
+
+    def build_property(property, content)
+      unless @excluded_properties.select { |p| property.start_with?(p) }.any?
+        case content['valuetype'].to_sym
+        when :compound, :object
+          # Note : some referenced topics have empty ids, we need to exclude them
+          @properties[property] = content['values'].reject { |s| s['id'].empty? }.map { |at| Topic.new(at['id'], :data => at) }
+        else
+          @properties[property] = content['values'].map { |at| Attribute.new(at, :type => content['valuetype']) }
+        end
+      end
+    end
+
+    def invalidate_lazy_properties
+      @name = nil
+      @types = nil
+      @description = nil
+    end
+  end
+end

data/lib/freebase_api/version.rb

@@ -0,0 +1,3 @@
+module FreebaseAPI
+  VERSION = "0.1"
+end

data/spec/attribute_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+
+describe FreebaseAPI::Attribute do
+
+  let(:data) {
+    {
+    "text" => "Github",
+    "lang" => "en",
+    "value" => "Github ()",
+    "creator" => "/user/mwcl_wikipedia_en",
+    "timestamp" => "2008-08-18T10:47:44.000Z"
+    }
+  }
+
+  let(:attribute) { FreebaseAPI::Attribute.new(data, :type => "string") }
+
+  describe "#value" do
+    it "should return the 'value' value" do
+      attribute.value.should == "Github ()"
+    end
+  end
+
+  describe "#text" do
+    it "should return the 'text' value" do
+      attribute.text.should == "Github"
+    end
+  end
+
+  describe "#lang" do
+    it "should return the 'lang' value" do
+      attribute.lang.should == "en"
+    end
+  end
+
+  describe "#type" do
+    it "should return the attribute type" do
+      attribute.type.should == "string"
+    end
+  end
+
+
+end

data/spec/fixtures/search.json

@@ -0,0 +1,214 @@
+[
+  {
+    "mid": "/m/01vrncs",
+    "id": "/en/bob_dylan",
+    "name": "Bob Dylan",
+    "notable": {
+      "name": "Singer-songwriter",
+      "id": "/m/016z4k"
+    },
+    "lang": "en",
+    "score": 72.587578
+  },
+  {
+    "mid": "/m/04prwq",
+    "id": "/en/dylan_and_cole_sprouse",
+    "name": "Dylan and Cole Sprouse",
+    "lang": "en",
+    "score": 38.116348
+  },
+  {
+    "mid": "/m/02fkm",
+    "id": "/en/dylan_thomas",
+    "name": "Dylan Thomas",
+    "notable": {
+      "name": "Poet",
+      "id": "/m/05z96"
+    },
+    "lang": "en",
+    "score": 32.650681
+  },
+  {
+    "mid": "/m/03061d",
+    "id": "/en/dylan_mcdermott",
+    "name": "Dylan McDermott",
+    "notable": {
+      "name": "Actor",
+      "id": "/m/02hrh1q"
+    },
+    "lang": "en",
+    "score": 29.216131
+  },
+  {
+    "mid": "/m/02f70",
+    "id": "/en/dylan",
+    "name": "Dylan",
+    "notable": {
+      "name": "Programming Language",
+      "id": "/computer/programming_language"
+    },
+    "lang": "en",
+    "score": 28.707029
+  },
+  {
+    "mid": "/m/035plv",
+    "id": "/en/jakob_dylan",
+    "name": "Jakob Dylan",
+    "notable": {
+      "name": "Singer",
+      "id": "/m/09l65"
+    },
+    "lang": "en",
+    "score": 27.369299
+  },
+  {
+    "mid": "/m/02p7m2",
+    "id": "/en/dylan_moran",
+    "name": "Dylan Moran",
+    "notable": {
+      "name": "Stand-up comedian",
+      "id": "/m/04tkfj6"
+    },
+    "lang": "en",
+    "score": 27.203932
+  },
+  {
+    "mid": "/m/0d0w6b",
+    "id": "/en/dylan_postl",
+    "name": "Hornswoggle",
+    "notable": {
+      "name": "Wrestler",
+      "id": "/m/02nx2gc"
+    },
+    "lang": "en",
+    "score": 26.060364
+  },
+  {
+    "mid": "/m/0219gl",
+    "id": "/en/eric_harris_and_dylan_klebold",
+    "name": "Eric Harris and Dylan Klebold",
+    "lang": "en",
+    "score": 25.414064
+  },
+  {
+    "mid": "/m/07g7jw",
+    "id": "/en/dylan_walsh",
+    "name": "Dylan Walsh",
+    "notable": {
+      "name": "Actor",
+      "id": "/m/02hrh1q"
+    },
+    "lang": "en",
+    "score": 24.362093
+  },
+  {
+    "mid": "/m/03dqyd",
+    "id": "/en/dylan_dog",
+    "name": "Dylan Dog",
+    "notable": {
+      "name": "Fictional Character",
+      "id": "/fictional_universe/fictional_character"
+    },
+    "lang": "en",
+    "score": 23.879669
+  },
+  {
+    "mid": "/m/07nx9j",
+    "id": "/en/dylan_baker",
+    "name": "Dylan Baker",
+    "notable": {
+      "name": "Actor",
+      "id": "/m/02hrh1q"
+    },
+    "lang": "en",
+    "score": 22.494648
+  },
+  {
+    "mid": "/m/0dtb_z3",
+    "id": "/authority/musicbrainz/dd48dca0-74b5-33e0-8a3b-7b5af62a2203",
+    "name": "Dylan",
+    "notable": {
+      "name": "Musical Album",
+      "id": "/music/album"
+    },
+    "lang": "en",
+    "score": 22.073868
+  },
+  {
+    "mid": "/m/05q546",
+    "id": "/en/dylan_ratigan",
+    "name": "Dylan Ratigan",
+    "notable": {
+      "name": "TV Personality",
+      "id": "/tv/tv_personality"
+    },
+    "lang": "en",
+    "score": 21.934017
+  },
+  {
+    "mid": "/m/0lqsy",
+    "id": "/en/full_house",
+    "name": "Full House",
+    "notable": {
+      "name": "TV Program",
+      "id": "/tv/tv_program"
+    },
+    "lang": "en",
+    "score": 21.582886
+  },
+  {
+    "mid": "/m/0gw_yr3",
+    "id": "/authority/imdb/name/nm3729721",
+    "name": "Dylan O'Brien",
+    "notable": {
+      "name": "Actor",
+      "id": "/m/02hrh1q"
+    },
+    "lang": "en",
+    "score": 21.544655
+  },
+  {
+    "mid": "/m/0b2p4m",
+    "id": "/en/dylan_bruno",
+    "name": "Dylan Bruno",
+    "notable": {
+      "name": "Actor",
+      "id": "/m/02hrh1q"
+    },
+    "lang": "en",
+    "score": 21.431660
+  },
+  {
+    "mid": "/m/08c8zn",
+    "id": "/en/sara_dylan",
+    "name": "Sara Dylan",
+    "notable": {
+      "name": "Model",
+      "id": "/m/0d1pc"
+    },
+    "lang": "en",
+    "score": 20.911421
+  },
+  {
+    "mid": "/m/027p9zq",
+    "id": "/en/brad_benton",
+    "name": "Dylan Vox",
+    "notable": {
+      "name": "Actor",
+      "id": "/m/02hrh1q"
+    },
+    "lang": "en",
+    "score": 20.779615
+  },
+  {
+    "mid": "/m/01wk7ld",
+    "id": "/en/dizzee_rascal",
+    "name": "Dizzee Rascal",
+    "notable": {
+      "name": "Rapper",
+      "id": "/m/0hpcdn2"
+    },
+    "lang": "en",
+    "score": 20.738529
+  }
+]