crunchbase 0.0.5 → 0.1.0

data/README.rdoc

@@ -9,15 +9,51 @@ use the {YAJL gem}[http://github.com/brianmario/yajl-ruby]; if not, it will
 fall back to the {JSON gem}[http://flori.github.com/json/]. Please ensure one
 of the two is installed.
 
-== Basic Usage
+== Usage
+
+If you already know the permalink for a given entity, you can grab the entry
+with the +get+ method.
 
    require 'crunchbase'
    steve = Crunchbase::Person.get("steve-jobs")
    facebook = Crunchbase::Company.get("facebook")    
+   
+If you know the name of the entity but not the permalink, you can use the
++find+ method.
+
+    steve = Crunchbase::Person.find("Steve", "Jobs")
+    github = Crunchbase::Company.find("Github")
+
+Note that finding using a name performs two HTTP requests internally, the first
+returning the permalink associated with the name, and the second which returns
+the actual data.
+
+=== Search
+
+Searching the Crunchbase is possible with the Search class.
+
+   s = Crunchbase::Search.find("widgets")
+   
+You can access the search results by treating the returned Search instance as
+an array.
+
+   first_result = s[0]
+   s.each { |result| puts result.name }
+  
+While Search does include the Enumerable module, it does not implement all of 
+the methods of Array. If you need to treat the results as an array in a way not
+supported, you can call +to_ary+; this prefetches all result pages (if they have
+not already been loaded), so it may entail a slight delay, depending on the
+number of results.
+
+   all_results = s.to_ary
+   result_slice = s[3..6]
+
+Coming Soon: List of Entities
 
 == Copyright
 
-Copyright (c) 2011 Tyler Cunnion. This software is made available under the 
+Copyright (c) 2011-12 Tyler Cunnion. This software is made available under the 
 MIT/X11 license. See LICENSE.txt for further details.
 
 I am not affiliated in any way with AOL, TechCrunch, Crunchbase, or anyone

data/VERSION

@@ -1 +1 @@
-0.0.5
+0.1.0

data/crunchbase.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{crunchbase}
-  s.version = "0.0.5"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = [%q{Tyler Cunnion}]
-  s.date = %q{2012-02-02}
+  s.date = %q{2012-02-21}
   s.email = %q{tyler.cunnion@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE.txt",
@@ -37,12 +37,16 @@ Gem::Specification.new do |s|
     "lib/crunchbase/relationships/firm_relationship.rb",
     "lib/crunchbase/relationships/person_relationship.rb",
     "lib/crunchbase/relationships/provider_relationship.rb",
+    "lib/crunchbase/search.rb",
+    "lib/crunchbase/search_result.rb",
     "lib/crunchbase/service_provider.rb",
     "spec/crunchbase/api_spec.rb",
     "spec/crunchbase/company_spec.rb",
     "spec/crunchbase/financial_organization_spec.rb",
     "spec/crunchbase/person_spec.rb",
     "spec/crunchbase/product_spec.rb",
+    "spec/crunchbase/search_result_spec.rb",
+    "spec/crunchbase/search_spec.rb",
     "spec/crunchbase/service_provider_spec.rb",
     "spec/fixtures/brad-fitzpatrick.js",
     "spec/fixtures/steve-jobs.js",

data/lib/crunchbase.rb

@@ -11,8 +11,10 @@ require 'crunchbase/relationship'
 require 'crunchbase/relationships/firm_relationship'
 require 'crunchbase/relationships/person_relationship'
 require 'crunchbase/relationships/provider_relationship'
+require 'crunchbase/search'
+require 'crunchbase/search_result'
 require 'crunchbase/crunch_exception'
 
 module Crunchbase
-  VERSION = "0.0.5"
+  VERSION = "0.1.0"
 end

data/lib/crunchbase/api.rb

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 require 'net/http'
 
 begin
@@ -16,6 +17,10 @@ module Crunchbase
   # methods provided on each entity class instead of calling these directly.
   class API
     CB_URL = 'http://api.crunchbase.com/v/1/'
+    @timeout_limit = 60
+    @redirect_limit = 2
+    
+    class << self; attr_accessor :timeout_limit, :redirect_limit end
 
     def self.person(permalink)
       fetch(permalink, 'person')
@@ -38,19 +43,8 @@ module Crunchbase
     end
 
     private
-
-    # Fetches URI and parses JSON. Raises Timeout::Error if fetching times out.
-    # Raises CrunchException if the returned JSON indicates an error.
-    def self.fetch(permalink, object_name)
-      uri = CB_URL + "#{object_name}/#{permalink}.js"
-      resp = Timeout::timeout(60) {
-        get_url_following_redirects(uri, 5)
-      }
-      j = parser.parse(resp)
-      raise CrunchException, j["error"] if j["error"]
-      return j
-    end
-
+    
+    # Returns the JSON parser, whether that's an instance of Yajl or JSON
     def self.parser
       if defined?(Yajl)
         Yajl::Parser
@@ -59,14 +53,48 @@ module Crunchbase
       end
     end
 
+    # Fetches URI for the permalink interface.
+    def self.fetch(permalink, object_name)
+      uri = CB_URL + "#{object_name}/#{permalink}.js"
+      get_json_response(uri)
+    end
+    
+    # Fetches URI for the search interface.
+    def self.search(query, page=1)
+      require "cgi"
+      uri = CB_URL + "search.js?query=#{CGI.escape(query)}&page=#{page}"
+      get_json_response(uri)
+    end
+
+    # Searches for a permalink in a particular category.
+    def self.permalink(parameters, category)
+      require "cgi"
+      qs = parameters.map{|k,v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v)}"}.join('&')
+      uri = CB_URL + "#{category}/permalink?#{qs}"
+      get_json_response(uri)
+    end
+    
+    # Gets specified URI, then parses the returned JSON. Raises Timeout error 
+    # if request time exceeds set limit. Raises CrunchException if returned
+    # JSON contains an error.
+    def self.get_json_response(uri)
+      resp = Timeout::timeout(@timeout_limit) {
+        get_url_following_redirects(uri, @redirect_limit)
+      }
+      j = parser.parse(resp)
+      raise CrunchException, j["error"] if j["error"]
+      j
+    end
+
+    # Performs actual HTTP requests, recursively if a redirect response is
+    # encountered. Will raise HTTP error if response is not 200, 404, or 3xx.
     def self.get_url_following_redirects(uri_str, limit = 10)
       raise CrunchException, 'HTTP redirect too deep' if limit == 0
 
       url = URI.parse(uri_str)
-      req = Net::HTTP::Get.new(url.path)
-      response = Net::HTTP.start(url.host, url.port) { |http| http.request(req) }
+      response = Net::HTTP.start(url.host, url.port) { |http| http.get(url.request_uri) }
       case response
-        when Net::HTTPSuccess
+        when Net::HTTPSuccess, Net::HTTPNotFound
           response.body
         when Net::HTTPRedirection
           get_url_following_redirects(response['location'], limit - 1)

data/lib/crunchbase/cb_object.rb

@@ -8,6 +8,7 @@ module Crunchbase
       @tag_list.respond_to?('split') ? @tag_list.split(', ') : []
     end
     
+    # Returns an array of aliases
     def aliases
       @alias_list.respond_to?('split') ? @alias_list.split(", ") : []
     end

data/lib/crunchbase/company.rb

@@ -1,5 +1,6 @@
 require 'date'
 module Crunchbase
+  # Represents a Company listed in the Crunchbase.
   class Company < CB_Object
     
     include Crunchbase::DateMethods
@@ -18,6 +19,11 @@ module Crunchbase
       c = Company.new(j)
       return c
     end
+
+    # Factory method to return a Company instance from a company name.
+    def self.find(name)
+      get(API.permalink({name: name}, "companies")["permalink"])
+    end
     
     def initialize(json)
       @name = json["name"]
@@ -72,6 +78,7 @@ module Crunchbase
       @deadpooled ||= date_from_components(@deadpooled_year, @deadpooled_month, @deadpooled_day)
     end
     
+    # Returns an array of Product objects, representing this Company's products.
     def products
       @products ||= @products_list.map {|p| Product.get(p['permalink']) }
     end

data/lib/crunchbase/financial_organization.rb

@@ -1,5 +1,6 @@
 require 'date'
 module Crunchbase
+  # Represents a Financial Organization listed in the Crunchbase.
   class FinancialOrganization < CB_Object
     
     include Crunchbase::DateMethods
@@ -16,6 +17,10 @@ module Crunchbase
       f = FinancialOrganization.new(j)
       return f
     end
+
+    def self.find(name)
+      get(API.permalink({name: name}, "financial-organizations")["permalink"])
+    end
     
     def initialize(json)
       @name = json['name']
@@ -53,4 +58,4 @@ module Crunchbase
       @founded ||= date_from_components(@founded_year, @founded_month, @founded_day)    
     end
   end
-end
+end

data/lib/crunchbase/person.rb

@@ -16,6 +16,10 @@ module Crunchbase
       p = Person.new(j)
       return p
     end
+
+    def self.find(first_name, last_name)
+      get(API.permalink({first_name: first_name, last_name: last_name}, "people")["permalink"])
+    end
     
     def initialize(json)
       @first_name = json["first_name"]
@@ -52,4 +56,4 @@ module Crunchbase
     end
     
   end
-end
+end

data/lib/crunchbase/product.rb

@@ -14,6 +14,10 @@ module Crunchbase
       j = API.product(permalink)
       return Product.new(j)
     end
+
+    def self.find(name)
+      get(API.permalink({name: name}, "products")["permalink"])
+    end
     
     def initialize(json)
       @name = json['name']
@@ -63,4 +67,4 @@ module Crunchbase
       return @company
     end
   end
-end
+end

data/lib/crunchbase/search.rb

@@ -0,0 +1,74 @@
+module Crunchbase
+  
+  # The Search class provides access to the Crunchbase search API. To perform a
+  # search, call the find class method, which returns an object of the Search
+  # class. This object represents an array of SearchResult objects, which may
+  # be addressed in a way analogous to an Array. These results are loaded on
+  # demand, in line with the CB API which returns results in pages of 10. When
+  # requesting a result index that has not been loaded yet, a new request is
+  # made to fetch it, resulting in a small delay. The class implements the
+  # Enumerable module, allowing usage of +map+, +select+, etc. If this is not
+  # sufficient, and full access to the underlying array is required, you may
+  # call to_ary, which will return the entire array including all results. If
+  # not all results have been fetched yet, there will be a delay to retrieve
+  # them, so consider this if your search contains a large number of results.
+  class Search
+    include Enumerable
+    
+    attr_reader :size, :crunchbase_url
+    alias :length :size
+    
+    # Performs a Crunchbase search for query.
+    def self.find(query)
+      j = API.search(query)
+      s = Search.new(query, j)
+    end
+    
+    def initialize(query, json)
+      @query = query
+      @results = []
+      @size = json["total"]
+      @crunchbase_url = json["crunchbase_url"]
+      populate_results(json)
+    end
+    
+    def [](key)
+      if key.kind_of?(Integer)
+        r = @results[key]
+        unless r.nil? && key < @size
+          r
+        else
+          retrieve_for_index(key)
+          @results[key]
+        end
+      end
+    end
+    
+    # Returns array of all search results (not just ones currently loaded.)
+    # This enables the user to take advantage of all Array methods, not just
+    # the ones implmented on Search.
+    def to_ary
+      self.map{|result| result}
+    end
+    
+    # Calls _block_ once for each search result, passing that item as a
+    # parameter.
+    def each(&block) # :yields: result
+      0.upto(@size - 1) {|x| yield self[x]}
+    end
+    
+    private
+    
+    def populate_results(json)
+      page = json["page"]
+      results = json["results"].map{|r| SearchResult.new(r)}
+      start = (page - 1) * 10
+      @results[start, results.length] = results
+    end
+    
+    def retrieve_for_index(index)
+      page = (index / 10) + 1
+      populate_results(API.search(@query, page))
+    end
+  end
+end

data/lib/crunchbase/search_result.rb

@@ -0,0 +1,63 @@
+module Crunchbase
+  # Represents a single search result arising from a Search. The information
+  # returned from a search includes the name, namespace (i.e. entity type),
+  # permalink, and an overview. You may also choose to retrieve the full
+  # entity with the entity method.  
+  class SearchResult
+    attr_reader :permalink, :crunchbase_url, :namespace, :overview
+    
+    def first_name
+      raise CrunchException, "Not available for this entity" unless namespace == "person"
+      @first_name
+    end
+    
+    def last_name
+      raise CrunchException, "Not available for this entity" unless namespace == "person"
+      @last_name
+    end
+    
+    # Returns concatenation of first and last names if person, otherwise
+    # returns name. Thus, if you wanted to, for example, iterate over search
+    # results and output the name, you could do so without checking entity type
+    # first.
+    def name
+      if @namespace == "person"
+        @first_name + " " + @last_name
+      else
+        @name
+      end
+    end
+    
+    def initialize(json)
+      @namespace = json["namespace"]
+      if @namespace == "person"
+        @first_name = json["first_name"]
+        @last_name = json["last_name"]
+      else
+        @name = json["name"]
+      end
+      @permalink = json["permalink"]
+      @crunchbase_url = json["crunchbase_url"]
+      @overview = json["overview"]
+    end
+    
+    # Returns the entity associated with the search result, loading from
+    # memory if previously fetched, unless +force_reload+ is set to true.
+    def entity(force_reload=false)
+      return @entity unless @entity.nil? || force_reload
+      @entity = case @namespace
+      when "company"
+        Company.get(@permalink)
+      when "financial-organization"
+        FinancialOrganization.get(@permalink)
+      when "person"
+        Person.get(@permalink)
+      when "product"
+        Product.get(@permalink)
+      when "service-provider"
+        ServiceProvider.get(@permalink)
+      end
+      return @entity
+    end
+  end
+end

data/lib/crunchbase/service_provider.rb

@@ -12,6 +12,10 @@ module Crunchbase
       s = ServiceProvider.new(j)
       return s
     end
+
+    def self.find(name)
+      get(API.permalink({name: name}, "service-providers")["permalink"])
+    end
     
     def initialize(json)
       @name = json["name"]
@@ -32,4 +36,4 @@ module Crunchbase
     
     
   end
-end
+end

data/spec/crunchbase/api_spec.rb

@@ -23,5 +23,11 @@ module Crunchbase
       c.name.should == "Adobe Systems"
     end
 
+    it "should find a permalink from a well-formed search" do
+      j = API.permalink({name: "Accel Partners"}, "financial-organizations")
+      j.class.should == Hash
+      j["permalink"].should == 'accel-partners'
+    end
+
   end
-end
+end

data/spec/crunchbase/company_spec.rb

@@ -7,6 +7,11 @@ module Crunchbase
       company = Company.get("facebook")
       company.name.should == "Facebook"
     end
+
+    it "should find companies by name" do
+      company = Company.find("Adobe Systems")
+      company.permalink.should == "adobe-systems"
+    end
     
     it "should return date for founded" do
       company = Company.new({"founded_year" => 2004, "founded_month" => 2,
@@ -24,4 +29,4 @@ module Crunchbase
       
     
   end
-end
+end

data/spec/crunchbase/financial_organization_spec.rb

@@ -7,6 +7,11 @@ module Crunchbase
       finorg = FinancialOrganization.get("robin-hood-ventures")
       finorg.name.should == "Robin Hood Ventures"
     end    
+
+    it "should find by name" do
+      f = FinancialOrganization.find("Accel Partners")
+      f.permalink.should == "accel-partners"
+    end
     
     it "should return date for founded" do
       finorg = FinancialOrganization.new({"founded_year" => 2004, "founded_month" => 2,
@@ -16,4 +21,4 @@ module Crunchbase
     end
     
   end
-end
+end

data/spec/crunchbase/person_spec.rb

@@ -60,6 +60,11 @@ module Crunchbase
       person = Person.get("steve-jobs")
       person.first_name.should == "Steve"
     end
+
+    it "should find a person by name" do
+      person = Person.find("Steve", "Jobs")
+      person.permalink.should == "steve-jobs"
+    end
     
     it "should be equal to another with the same permalink and last updated" do
       person = Person.get("steve-jobs")
@@ -68,4 +73,4 @@ module Crunchbase
     end
     
   end
-end
+end

data/spec/crunchbase/product_spec.rb

@@ -7,6 +7,11 @@ module Crunchbase
       product = Product.get("iphone")
       product.name.should == "iPhone"
     end
+
+    it "should find by name" do
+      product = Product.find("iPhone")
+      product.permalink.should == "iphone"
+    end
     
     it "should return date for launched" do
       product = Product.new({"launched_year" => 2004, "launched_month" => 2,
@@ -22,4 +27,4 @@ module Crunchbase
       product.deadpooled.should === Date.new(2004, 2, 1)
     end
   end
-end
+end

data/spec/crunchbase/search_result_spec.rb

@@ -0,0 +1,16 @@
+require File.join(File.dirname(__FILE__), "..", "spec_helper.rb")
+require 'net/http'
+
+module Crunchbase
+  describe SearchResult do
+    
+    before(:all) do
+      @result = Search.find('google')[0]
+    end
+    
+    it "should return the entity which is named" do
+      @result.name.should == @result.entity.name
+    end
+
+  end
+end

data/spec/crunchbase/search_spec.rb

@@ -0,0 +1,23 @@
+require File.join(File.dirname(__FILE__), "..", "spec_helper.rb")
+require 'net/http'
+
+module Crunchbase
+  describe Search do
+    
+    it "should retrieve search results" do
+      s = Search.find('google')
+      s[0].class.should == SearchResult
+    end
+    
+    it "should return higher search results" do
+      s = Search.find('google')
+      s[s.size/2].class.should == SearchResult
+    end
+    
+    it "should return nil for array out of bounds" do
+      s = Search.find('google')
+      s[s.size].should be_nil
+    end
+
+  end
+end

data/spec/crunchbase/service_provider_spec.rb

@@ -6,7 +6,12 @@ module Crunchbase
     it "should pull from web api" do
       sp = ServiceProvider.get("fox-rothschild")
       sp.name.should == "Fox Rothschild"
-    end    
+    end
+
+    it "should find by name" do
+      sp = ServiceProvider.find("Fox Rothschild")
+      sp.permalink.should == "fox-rothschild"
+    end
     
   end
-end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: crunchbase
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-02 00:00:00.000000000Z
+date: 2012-02-21 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70273283484480 !ruby/object:Gem::Requirement
+  requirement: &70265569207100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70273283484480
+  version_requirements: *70265569207100
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70273283483700 !ruby/object:Gem::Requirement
+  requirement: &70265569206160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *70273283483700
+  version_requirements: *70265569206160
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70273283482860 !ruby/object:Gem::Requirement
+  requirement: &70265569205140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: 1.6.4
   type: :development
   prerelease: false
-  version_requirements: *70273283482860
+  version_requirements: *70265569205140
 - !ruby/object:Gem::Dependency
   name: rcov
-  requirement: &70273283481660 !ruby/object:Gem::Requirement
+  requirement: &70265569204040 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70273283481660
+  version_requirements: *70265569204040
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &70273283480380 !ruby/object:Gem::Requirement
+  requirement: &70265569202940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,7 +65,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70273283480380
+  version_requirements: *70265569202940
 description: 
 email: tyler.cunnion@gmail.com
 executables: []
@@ -95,12 +95,16 @@ files:
 - lib/crunchbase/relationships/firm_relationship.rb
 - lib/crunchbase/relationships/person_relationship.rb
 - lib/crunchbase/relationships/provider_relationship.rb
+- lib/crunchbase/search.rb
+- lib/crunchbase/search_result.rb
 - lib/crunchbase/service_provider.rb
 - spec/crunchbase/api_spec.rb
 - spec/crunchbase/company_spec.rb
 - spec/crunchbase/financial_organization_spec.rb
 - spec/crunchbase/person_spec.rb
 - spec/crunchbase/product_spec.rb
+- spec/crunchbase/search_result_spec.rb
+- spec/crunchbase/search_spec.rb
 - spec/crunchbase/service_provider_spec.rb
 - spec/fixtures/brad-fitzpatrick.js
 - spec/fixtures/steve-jobs.js
@@ -120,7 +124,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3154475124143607106
+      hash: 4487821890368483707
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: