avvo_api 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+pkg/*
+*.gem
+.bundle
+doc/*

data/Gemfile

@@ -0,0 +1,6 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in avvo_api.gemspec
+gemspec
+
+gem "rake"

data/Gemfile.lock

@@ -0,0 +1,31 @@
+PATH
+  remote: .
+  specs:
+    avvo_api (0.1.0)
+      reactive_resource (~> 0.5.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activeresource (2.3.10)
+      activesupport (= 2.3.10)
+    activesupport (2.3.10)
+    addressable (2.2.2)
+    crack (0.1.8)
+    rake (0.8.7)
+    reactive_resource (0.5.0)
+      activeresource (~> 2.3.10)
+    shoulda (2.11.3)
+    webmock (1.6.2)
+      addressable (>= 2.2.2)
+      crack (>= 0.1.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  avvo_api!
+  rake
+  reactive_resource (~> 0.5.0)
+  shoulda (~> 2.11.3)
+  webmock (~> 1.6.1)

data/README.rdoc

@@ -0,0 +1,63 @@
+= Avvo API Client
+
+This gem provides an
+{ActiveResource}[http://api.rubyonrails.org/classes/ActiveResource/Base.html]-based
+client to information on {Avvo}[http://www.avvo.com], a directory of lawyers and loctors. 
+
+== Requirements
+
+Apart from the gems installed as dependencies, this gem requires an
+account on Avvo associated with an API key. Visit the {API
+Documentation}[http://api.avvo.com] for details.
+
+== Usage
+
+Somewhere during your app's initialization, you should include the gem
+and set it up with your Avvo credentials:
+
+  require 'avvo_api'
+  AvvoApi.setup('user@avvo.com', 'password')
+
+For the most part, the models supplied by this gem should act like
+ActiveRecord models. These models parallel the resources listed on
+http://api.avvo.com, and everything accessible from the Avvo API is
+accessible using this gem.
+
+== Examples
+
+Details about the specific information returned by these calls can be
+found in the documentation at http://api.avvo.com. An example of using
+the API in a command-line program can be found in the +examples+
+subdirectory.
+
+=== Find a lawyer with a known ID
+
+  l = AvvoApi::Lawyer.find(28995)
+
+=== Find a lawyer based on known attributes, like email, zip code, etc.
+
+  l = AvvoApi::Lawyer.resolve(:name => 'Mark Britton', :zip_code => '98101')
+
+=== Search for lawyers matching a keyword in a specific location
+
+  AvvoApi::Lawyer.search(:q => 'criminal defense', :loc => 'seattle')
+
+=== Retrieve the headshot URL for a lawyer
+
+  AvvoApi::Lawyer.find(28995).headshot.headshot_url
+
+or
+
+  AvvoApi::Headshot.find(:one, :params => {:lawyer_id => 28995}).headshot_url
+
+=== Getting a list of addresses for a doctor
+
+  addresses = AvvoApi::Doctor.find(1).addresses
+
+or
+
+  addresses = AvvoApi::Address.find(:all, :params => {:doctor_id => doctor.id})
+
+=== Getting the main address for a doctor
+
+  main_address = AvvoApi::Address.main(:doctor_id => doctor.id)

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler'
+require 'rake/testtask'
+require 'rake/rdoctask'
+Bundler::GemHelper.install_tasks
+
+task :default => :test
+task :build => :test
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+  rd.rdoc_dir = 'doc'
+end

data/avvo_api.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "avvo_api/version"
+
+Gem::Specification.new do |s|
+  s.name        = "avvo_api"
+  s.version     = AvvoApi::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Justin Weiss"]
+  s.email       = ["jweiss@avvo.com"]
+  s.homepage    = "http://api.avvo.com"
+  s.summary     = %q{An ActiveResource client to the Avvo API}
+  s.description = %q{An ActiveResource client to the Avvo API}
+
+  s.add_dependency "reactive_resource", '~> 0.5.0'
+  s.add_development_dependency "shoulda", '~> 2.11.3'
+  s.add_development_dependency "webmock", '~> 1.6.1'
+  
+  s.rubyforge_project = "avvo_api"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/examples/avvo_cli.rb

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+#
+# A command-line interface to the Avvo API, as an example of how the
+# API can be used. Before using the API, you must create a YAML file
+# in ~/.avvo containing your email and password.
+require 'optparse'
+require 'avvo_api'
+
+professional_klass = nil
+professional_param = nil
+
+opts = OptionParser.new("Usage: avvo_cli.rb [options] ID")
+opts.on("-l", "--lawyer", "Get details about a lawyer") { professional_klass = AvvoApi::Lawyer; professional_param = :lawyer_id }
+opts.on("-d", "--doctor", "Get details about a doctor") { professional_klass = AvvoApi::Doctor; professional_param = :doctor_id }
+rest = opts.parse ARGV
+
+if !professional_klass
+  puts "You must specify either --lawyer or --doctor"
+  puts opts
+  exit(1)
+elsif !rest.first
+  puts "You must specify the ID of the professional you are looking for"
+  puts opts
+  exit(1)
+else
+  begin
+    config = YAML.load(File.read(File.expand_path("~/.avvo")))
+  rescue
+    puts "Please put your Avvo API credentials in ~/.avvo. This is a simple yaml file, which should look like:
+email: email@domain.com
+password: your_avvo_password"
+    exit(1)
+  end
+  AvvoApi.setup(config["email"], config["password"])
+  AvvoApi::Base.site = 'http://localhost.local:3000'
+  
+  professional = professional_klass.find(rest.first)
+
+  address = AvvoApi::Address.main(professional_param => professional.id)
+  phones =  address.phones
+  specialties = professional.specialties
+  reviews = professional.reviews
+
+  format = "%12s %s\n"
+  puts
+  printf format, "ID:", professional.id
+  printf format, "Name:", [professional.firstname, professional.middlename, professional.lastname].join(' ')
+  printf format, "Website:", professional.website_url if professional.website_url
+  printf format, "Profile URL:", professional.profile_url
+
+  printf format, "Address:", address.address_line1
+  printf format, "", address.address_line2 if address.address_line2
+  printf format, "", address.city + ", " + address.state + " " + address.postal_code
+
+  phones.each do |phone|
+    printf format, "#{phone.phone_type}:", phone.phone_number
+  end
+  
+  specialties.each_with_index do |specialty, i|
+    header = i == 0 ? "Specialties:" : ""
+    printf format, header, "#{specialty.specialty_name.strip} (#{specialty.specialty_percent}%)"
+  end
+  
+  puts
+  printf format, "Reviews ", ''
+  reviews.each do |review|
+    printf format, "Rating:", review.overall_rating
+    printf format, "Title:", review.title
+    printf format, "URL:", review.url
+    printf format, "By:", review.posted_by
+    puts 
+  end
+  
+end

data/lib/avvo_api.rb

@@ -0,0 +1,28 @@
+require 'avvo_api/base'
+require 'avvo_api/professional_methods'
+
+# The Avvo API Client. All API models live in this module.
+module AvvoApi
+
+  autoload :Lawyer, 'avvo_api/lawyer'
+  autoload :Doctor, 'avvo_api/doctor'
+  autoload :School, 'avvo_api/school'
+  autoload :Address, 'avvo_api/address'
+  autoload :Phone, 'avvo_api/phone'
+  autoload :Language, 'avvo_api/language'
+  autoload :Specialty, 'avvo_api/specialty'
+  autoload :Headshot, 'avvo_api/headshot'
+  autoload :AdvancedTraining, 'avvo_api/advanced_training'
+  autoload :Review, 'avvo_api/review'
+  
+  # Tells this client to use +email+ and +password+ to authenticate to
+  # the Avvo API.
+  def self.setup(email, password)
+    AvvoApi::Base.password = password
+    AvvoApi::Base.user = email
+  end
+end
+
+# Post parameters as <tt>{:lawyer => {...params...}}</tt> so the server
+# can separate the object's params from the request params
+ActiveResource::Base.include_root_in_json = true

data/lib/avvo_api/address.rb

@@ -0,0 +1,35 @@
+# Represents an address. One of the following attributes MUST
+# be set when using this model:
+# 
+# * doctor_id
+# * lawyer_id
+#
+# This model has the following attributes:
+#
+# * id
+# * address_line1
+# * address_line2
+# * city
+# * state
+# * postal_code
+# * latitude
+# * longitude
+# 
+class AvvoApi::Address < AvvoApi::Base
+  belongs_to :lawyer
+  belongs_to :doctor
+  has_many :phones
+
+  # Returns the 'main' address associated with the passed in
+  # professional. This is usually the address you want to
+  # use. +params+ is a hash of <tt>{:lawyer_id => lawyer.id}</tt> or
+  # <tt>{:doctor_id => doctor.id}</tt>
+  def self.main(params)
+    response = self.get(:main, params)
+    if response && response["id"]
+      new(params.merge(response))
+    elsif response && response["address"]
+      new(params.merge(response["address"]))
+    end
+  end
+end

data/lib/avvo_api/advanced_training.rb

@@ -0,0 +1,35 @@
+# Constants representing the possible values of the
+# advanced_training_type_id parameter of AvvoApi::AdvancedTraining
+module AvvoApi::AdvancedTrainingType
+  
+  # Unknown training type
+  UNKNOWN = 1 
+
+  # Represents an internship
+  INTERNSHIP = 2
+  
+  # Represents a residency
+  RESIDENCY = 3
+
+  # Represents a fellowship
+  FELLOWSHIP = 4
+end
+
+# Represents advanced training, like residencies, for doctors. This
+# model is only applicable to doctors. The following attributes MUST
+# be set when using this model:
+# 
+# * doctor_id
+#
+# This model has the following attributes:
+#
+# * id - The model's id
+# * advanced_training_type_id -  an AvvoApi::AdvancedTrainingType constant
+# * specialty_name - The name of the specialty this advanced training is in
+# * hospital_name - The normalized name of the hospital. This will be
+#   resolved by Avvo when it is set by this client.
+# * graduation_date - The date this training was completed
+# 
+class AvvoApi::AdvancedTraining < AvvoApi::Base
+  belongs_to :doctor
+end

data/lib/avvo_api/base.rb

@@ -0,0 +1,18 @@
+require 'reactive_resource'
+
+
+module AvvoApi
+  # The class that all AvvoApi resources inherit from. This sets up the
+  # base URL and URL structure that the rest of the models use to hit
+  # Avvo.
+  class Base < ReactiveResource::Base
+
+    # The current version of the Avvo API
+    API_VERSION = 1
+    
+    self.site = "https://api.avvo.com/"
+    self.prefix = "/api/#{API_VERSION}/"
+    self.format = :json
+    
+  end
+end

data/lib/avvo_api/doctor.rb

@@ -0,0 +1,22 @@
+# Represents a doctor on Avvo. Attributes include:
+# 
+# * id: The id of this doctor
+# * firstname: the first name of this doctor
+# * middlename: the middle name of this doctor
+# * lastname: the last name of this doctor
+# * suffix: the suffix of the doctor's name
+# * avvo_rating: The doctor's Avvo Rating, from 0.0 to 10.0
+# * email_address
+# * website_url
+# * profile_url
+#
+class AvvoApi::Doctor < AvvoApi::Base
+  has_many :addresses
+  has_many :reviews
+  has_many :schools
+  has_many :languages
+  has_many :specialties
+  has_many :advanced_trainings
+  has_one :headshot
+  include AvvoApi::ProfessionalMethods
+end

data/lib/avvo_api/headshot.rb

@@ -0,0 +1,20 @@
+# Represents a professional's headshot. Each professional only has one
+# headshot, so finding a headshot should happen with the following call:
+#
+#   AvvoApi::Headshot.find(:one, :lawyer_id => l.id)
+#
+# When using this model, one of the following attributes MUST be set:
+# 
+# * doctor_id
+# * lawyer_id
+#
+# This model has the following attribute:
+#
+# * headshot_url: The url to the standard-size headshot.
+# 
+class AvvoApi::Headshot < AvvoApi::Base
+  singleton
+
+  belongs_to :lawyer
+  belongs_to :doctor
+end

data/lib/avvo_api/language.rb

@@ -0,0 +1,16 @@
+# Represents a language. One of the following attributes MUST
+# be set when using this model:
+# 
+# * doctor_id
+# * lawyer_id
+#
+# This model has the following attributes:
+#
+# * id 
+# * name: The language name.
+# * specialty_id: The language id. 'name' takes priority over this if both are set.
+# 
+class AvvoApi::Language < AvvoApi::Base
+  belongs_to :lawyer
+  belongs_to :doctor
+end

data/lib/avvo_api/lawyer.rb

@@ -0,0 +1,20 @@
+# Represents a lawyer on Avvo. Attributes include:
+# 
+# * id: The id of this lawyer
+# * firstname: the first name of this lawyer
+# * middlename: the middle name of this lawyer
+# * lastname: the last name of this lawyer
+# * suffix: the suffix of the lawyer's name
+# * email_address
+# * website_url
+#
+class AvvoApi::Lawyer < AvvoApi::Base
+  
+  has_many :addresses
+  has_many :reviews
+  has_many :schools
+  has_many :languages
+  has_many :specialties
+  has_one :headshot
+  include AvvoApi::ProfessionalMethods
+end

data/lib/avvo_api/phone.rb

@@ -0,0 +1,37 @@
+# Constants representing the various values for +phone_type_id+ in AvvoApi::Phone
+module AvvoApi::PhoneType
+
+  # There is no type specified for this number
+  UNKNOWN = 1
+
+  # This is an office number
+  OFFICE = 2
+
+  # This is a fax number
+  FAX = 3
+
+  # This is a mobile number
+  MOBILE = 4
+end
+
+# Represents a phone number tied to an address. One of the
+# following attributes MUST be set when using this model:
+# 
+# * doctor_id
+# * lawyer_id
+#
+# Additionally, the following attribute MUST be set when using this model:
+# 
+# * address_id
+#
+# This model has the following attributes:
+#
+# * id 
+# * phone_number:  The phone number. Will be normalized by Avvo.
+# * phone_type_id: The type of the phone number, as an AvvoApi::PhoneType
+#   constant. (Only applicable when creating or updating records)
+# * phone_type:    A string representation of the phone type
+#
+class AvvoApi::Phone < AvvoApi::Base
+  belongs_to :address
+end