great_schools 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MmVjNzJmYTI4YjA4NjQ5OTFjNzQ5YmJlMTYzOTI0OWJmYzk0Yzk2OQ==
+  data.tar.gz: !binary |-
+    YmZmNjZkZDVkOGE3MDU1MzU2MWYyNDY4MTEyNTFhNmVjZmExZWE2ZA==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    NDg4NWFkYTI1NWIwMTNlZmIxNDVhZTc0ODkwZjkyOWU3N2ZhYWM5NDY0ODNk
+    YTNkMzRkOWEyMzgxNjgwNTc0OTA2MGE4ZTEwYWM0ZTgzZDk2MmQ5MjE0MDky
+    MzY0NmRmNTcyMTFkZTM5MzcyMjhhZDQ5ODYwNDQ5Y2Q2MmQzNDY=
+  data.tar.gz: !binary |-
+    MDA1ZWVhYjcyNjMyMTU5NWJhODI0MjI1Y2M0ZmI1Yjg3MzEwYzA2YmZmMDYx
+    ZWEzNTI0ZDAwM2UwZDAwZmU2ZDJmNjExYzI4ZDFiMjc4ODVlY2Q4OTJmZTQ5
+    OGRhMGI0MWNmZjQ4MTRmZDkyNGVjZjc1M2FlZDI1ZTRmZTI0MGU=

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in great_schools.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Michael Sepcot
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,58 @@
+# GreatSchools
+
+A Ruby interface to the GreatSchools API.
+
+The GreatSchools API allows access to School Profiles, Test Scores, School
+Reviews, GreatSchools Ratings, School Districts, and City Profiles.
+
+Before you can start using the GreatSchool API, you must register and
+request an access key at: http://www.greatschools.org/api/registration.page
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'great_schools'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install great_schools
+
+## Usage
+
+The first call you make should setup your API key:
+
+    GreatSchools::API.key = 'MY_API_KEY'
+
+The first entry point is `GreatSchools::City` to lookup nearby cities; get an
+overview of a specific city; and find the districts and reviews associated with
+it.
+
+    GreatSchools::City.nearby('CA', 'San Francisco') # => list of cities neighboring San Francisco, CA.
+
+    city = GreatSchools::City.overview('CA', 'San Francisco')
+    city.districts # => list of districts in San Francisco, CA
+    city.reviews # => list of reviews for schools in San Francisco, CA
+
+The second main entry point is `GreatSchools::School` to lookup schools in a
+specific city or near an address; get a school profile; and find census data,
+test scores, and reviews associated with it.
+
+    schools = GreatSchools::School.browse('CA', 'San Francisco') # => list of schools
+
+    school = GreatSchools::School.nearby('CA', zip_code: 94105).first
+    school.census # => lunch pricing, student/teacher ratio, ethnicities, etc.
+    school.review # => list of reviews for the school
+    school.score # => GreatSchool rank and recent test results
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+task default: :spec

data/great_schools.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'great_schools/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'great_schools'
+  spec.version       = GreatSchools::Version
+  spec.authors       = ['Michael J. Sepcot']
+  spec.email         = ['developer@sepcot.com']
+  spec.description   = %q{The GreatSchools API allows access to School Profiles, Test Scores, School Reviews, GreatSchools Ratings, School Districts, and City Profiles.}
+  spec.summary       = %q{A Ruby interface to the GreatSchools API.}
+  spec.homepage      = 'https://github.com/msepcot/great_schools'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'fakeweb'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+
+  spec.add_dependency 'activesupport', '>= 3.0.0'
+  spec.add_dependency 'httparty', '~> 0.12.0'
+end

data/lib/great_schools.rb

@@ -0,0 +1,88 @@
+require 'great_schools/error'
+require 'great_schools/model'
+
+require 'great_schools/census'
+require 'great_schools/city'
+require 'great_schools/district'
+require 'great_schools/ethnicity'
+require 'great_schools/rank'
+require 'great_schools/result'
+require 'great_schools/review'
+require 'great_schools/school'
+require 'great_schools/score'
+require 'great_schools/test'
+
+require 'great_schools/version'
+
+require 'active_support'
+require 'active_support/core_ext/array/wrap'
+require 'active_support/core_ext/hash/slice'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/object/try'
+
+require 'httparty'
+
+# = GreatSchools
+#
+# GreatSchools profiles more than 90,000 public and 30,000 private schools in
+# the United States. With hundreds of thousands of ratings and Parent Reviews
+# about schools nationwide, we provide the most comprehensive data about
+# elementary, middle and high schools.
+module GreatSchools
+  # The GreatSchools API allows you to add valuable information to your
+  # application, including:
+  #
+  # * Schools in a city
+  # * Schools near an address
+  # * Data about specific schools, including school directory information,
+  #   grade levels, enrollment, test scores, ratings and reviews and more.
+  #
+  # Before you can start using the GreatSchool API, you must register and
+  # request an access key at: http://www.greatschools.org/api/registration.page
+  # --
+  # TODO: load API access key from a config file (great_schools.yml or something)
+  # ++
+  class API
+    class << self # Class methods
+      DOMAIN = 'http://api.greatschools.org'
+
+      # The API access key, must be set before making any requests.
+      attr_accessor :key
+
+      # Makes an API request to +path+ with the supplied query +parameters+ (merges
+      # in the API access +key+).
+      #
+      # Returns a +Hash+ or an +Array+ with the encompassing XML container stripped.
+      #
+      # Raises a +GreatSchools::Error+ if the server response code is not 200.
+      #
+      # ==== Attributes
+      #
+      # * +path+        - component path of the URL
+      # * +parameters+  - +Hash+ of query string elements
+      def get(path, parameters = {})
+        parameters.merge!(key: key).keep_if { |_,v| v.present? }
+
+        response = HTTParty.get("#{DOMAIN}/#{path}", query: parameters, format: :xml)
+
+        if response.code.eql?(200)
+          parse(response.values.first) # strip the container element before parsing
+        else
+          raise GreatSchools::Error.new(response)
+        end
+      end
+
+    private
+
+      # Returns a +Hash+ of a single element, or an +Array+ of elements without
+      # the container hash.
+      def parse(hash)
+        if hash.keys.size.eql?(1) # we have an array of elements
+          hash.values.first # strip the container and return the array
+        else # we have one element, return the hash
+          hash
+        end
+      end
+    end
+  end
+end

data/lib/great_schools/census.rb

@@ -0,0 +1,52 @@
+module GreatSchools # :nodoc:
+  # = School Census and Profile Data
+  #
+  # While you can pull census data for a school manually, I'd recommend going
+  # through the school model and letting it make the call for you:
+  #
+  #   schools = GreatSchools::School.browse('CA', 'San Mateo')
+  #   school = schools.first
+  #   school.census # equivalent to: GreatSchools::Census.for_school(school.state, school.id)
+  class Census < Model
+    # --
+    # NOTE: these are all +GreatSchool::School+ attributes, should we build a
+    # school model instead of attaching these attributes?
+    # ++
+    attr_accessor :school_name, :address, :latitude, :longitude, :phone, :type, :district, :enrollment
+
+    attr_accessor :free_and_reduced_price_lunch, :student_teacher_ratio, :ethnicities
+
+    class << self # Class methods
+      # Returns census and profile data for a school.
+      #
+      # ==== Attributes
+      #
+      # * +state+ - Two letter state abbreviation
+      # * +id+    - Numeric id of a school. This GreatSchools ID is included in
+      #             other listing requests like +GreatSchools::School#browse+
+      #             and +GreatSchools::School#nearby+
+      def for_school(state, id)
+        response = GreatSchools::API.get("school/census/#{state.upcase}/#{id}")
+
+        new(response)
+      end
+    end
+
+    # Set an array of +GreatSchools::Ethnicity+.
+    #
+    # ==== Attributes
+    #
+    # * +params+ - a +Hash+ or +Array+ of +GreatSchools::Ethnicity+ attributes.
+    def ethnicities=(params)
+      @ethnicities = []
+
+      params = params['ethnicity'] if params.is_a?(Hash) && params.key?('ethnicity')
+
+      Array.wrap(params).each do |hash|
+        @ethnicities << GreatSchools::Ethnicity.new(hash)
+      end
+
+      @ethnicities
+    end
+  end
+end

data/lib/great_schools/city.rb

@@ -0,0 +1,72 @@
+module GreatSchools # :nodoc:
+  # = GreatSchools City
+  #
+  # --
+  # TODO: add method to grab nearby schools using +GreatSchools::School#nearby+
+  # with the +city+ and +state+ options.
+  # ++
+  class City < Model
+    attr_accessor :name, :state, :rating, :total_schools
+    attr_accessor :elementary_schools, :middle_schools, :high_schools
+    attr_accessor :public_schools, :charter_schools, :private_schools
+
+    class << self # Class methods
+      # Returns a list of cities near another city.
+      #
+      # ==== Attributes
+      #
+      # * +state+ - Two letter state abbreviation
+      # * +city+  - Name of city
+      #
+      # ==== Options
+      #
+      # * +:radius+ - Radius in miles to confine search to. Defaults to 15 and
+      #               can be in the range 1-100.
+      # * +:sort+   - How to sort the results. Defaults to 'distance'. Other
+      #               options are 'name' to sort by city name in alphabetical
+      #               order, and 'rating' to sort by GreatSchool city rating,
+      #               highest first.
+      # --
+      # TODO: handle validations
+      # ++
+      def nearby(state, city, options = {})
+        options.slice!(:radius, :sort)
+
+        response = GreatSchools::API.get("cities/nearby/#{state.upcase}/#{parameterize(city)}", options)
+
+        Array.wrap(response).map { |city| new(city.merge(state: state)) }
+      end
+
+      # Returns information about a city.
+      #
+      # ==== Attributes
+      #
+      # * +state+ - Two letter state abbreviation
+      # * +city+  - Name of city
+      def overview(state, city)
+        response = GreatSchools::API.get("cities/#{state.upcase}/#{parameterize(city)}")
+
+        new(response.merge(state: state))
+      end
+    end
+
+    alias_method :city, :name
+    alias_method :city=, :name=
+
+    # Returns a list of districts in a city.
+    def districts
+      @districts ||= GreatSchools::District.browse(state, city)
+    end
+
+    # Returns a list of the most recent reviews for any schools in a city.
+    #
+    # ==== Options
+    #
+    # * +:cutoff_age+ - Reviews must have been published after this many days
+    #                   ago to be returned.
+    # * +:limit+      - Maximum number of reviews to return. This defaults to 5.
+    def reviews(options = {})
+      GreatSchools::Review.for_city(state, name, options.slice(:cuttoff_age, :limit))
+    end
+  end
+end

data/lib/great_schools/district.rb

@@ -0,0 +1,29 @@
+module GreatSchools # :nodoc:
+  # = GreatSchools District
+  #
+  # --
+  # TODO: add method to grab schools using +GreatSchools::School#nearby+ with
+  # the +address+, +city+, +state+, and +zip_code+ options (parsing address).
+  # Filter results to schools with a matching district name.
+  # ++
+  class District < Model
+    attr_accessor :name, :address, :phone, :fax, :website
+    attr_accessor :nces_code, :district_rating, :grade_range, :total_schools
+    attr_accessor :elementary_schools, :middle_schools, :high_schools
+    attr_accessor :public_schools, :charter_schools
+
+    class << self # Class methods
+      # Returns a list of school districts in a city.
+      #
+      # ==== Attributes
+      #
+      # * +state+ - Two letter state abbreviation
+      # * +city+  - Name of city
+      def browse(state, city)
+        response = GreatSchools::API.get("districts/#{state.upcase}/#{parameterize(city)}")
+
+        Array.wrap(response).map { |district| new(district) }
+      end
+    end
+  end
+end

data/lib/great_schools/error.rb

@@ -0,0 +1,51 @@
+module GreatSchools # :nodoc:
+  # = GreatSchools Error
+  #
+  # Encompass any errors sent back by the GreatSchools API.
+  #
+  # GreatSchools sends back XML to all API requests. The error response looks
+  # like:
+  #
+  #   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+  #   <error>
+  #     <errorCode>3</errorCode>
+  #     <faultString>Invalid API key.</faultString>
+  #     <date>2013/11/22</date>
+  #     <call>/reviews/city/CA/Foster-City</call>
+  #   </error>
+  #
+  # ==== Examples
+  #
+  # The most common error is trying to request data that your API key does not
+  # have access to.
+  #
+  #   GreatSchools::API.key = 'INVALID_KEY'
+  #   GreatSchools::Review.for_city('CA', 'Foster City')
+  #   # => #<GreatSchools::Error error_code: "3", fault_string: "Invalid API key.", call: "/reviews/city/CA/Foster-City", date: "2013/11/22">
+  class Error < StandardError
+    attr_reader :call, :date, :error_code
+
+    alias_method :fault_string, :message
+
+    # Creates a new +GreatSchools::Error+ from a parsed +HTTParty+ response.
+    # The +faultString+ is used as the error +message+.
+    #
+    # ==== Attributes
+    #
+    # * +response+ - a parsed response object from +HTTParty+
+    # --
+    # TODO: add error handling - ensure we have a +Hash+, use +fetch+ with defaults
+    # ++
+    def initialize(response)
+      super(response['error']['faultString'])
+
+      @call = response['error']['call']
+      @date = response['error']['date']
+      @error_code = response['error']['errorCode']
+    end
+
+    def inspect # :nodoc:
+      "#<#{self.class} error_code: \"#{error_code}\", fault_string: \"#{message}\", call: \"#{call}\", date: \"#{date}\">"
+    end
+  end
+end