great_schools 0.1.0

data/lib/great_schools/ethnicity.rb

@@ -0,0 +1,5 @@
+module GreatSchools # :nodoc:
+  class Ethnicity < Model # :nodoc:
+    attr_accessor :name, :value, :year
+  end
+end

data/lib/great_schools/model.rb

@@ -0,0 +1,45 @@
+require 'cgi'
+
+module GreatSchools # :nodoc:
+  # = GreatSchools Base Model
+  class Model
+    class << self # Class methods
+    protected
+      # Makes a URL slug from the string.
+      #
+      # Replaces dashes with underscores, spaces with dashes, and URL encodes
+      # any special characters.
+      #
+      # ==== Examples
+      #
+      #   parameterize('San Francisco')       # => 'San-Francisco'
+      #   parameterize('Cardiff-By-The-Sea')  # => 'Cardiff_By_The_Sea'
+      def parameterize(string)
+        CGI.escape(string.gsub('-', '_').gsub(' ', '-'))
+      end
+    end
+
+    # Base initializer, map camelCased XML attributes from the GreatSchools API
+    # response to the appropriately underscored attribute setters.
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        key = underscore(key)
+        send("#{key}=", value) if respond_to?("#{key}=")
+      end
+    end
+
+  protected
+
+    # Makes an underscored, lowercase form from the expression in the string.
+    #
+    # ==== Examples
+    #
+    #   underscore('myACRONYMString') # => 'my_acronym_string'
+    def underscore(word)
+      word = word.to_s.dup # unfreeze any frozen strings
+      word.gsub!(/([a-z])([A-Z])/,'\1_\2')          # myACRONYMString   => my_ACRONYMString
+      word.gsub!(/([A-Z]+)(?=[A-Z][a-z])/, '\1_\2') # my_ACRONYMString  => my_ACRONYM_String
+      word.downcase                                 # my_ACRONYM_String => my_acronym_string
+    end
+  end
+end

data/lib/great_schools/rank.rb

@@ -0,0 +1,5 @@
+module GreatSchools # :nodoc:
+  class Rank < Model # :nodoc:
+    attr_accessor :name, :scale, :year, :description, :score
+  end
+end

data/lib/great_schools/result.rb

@@ -0,0 +1,5 @@
+module GreatSchools # :nodoc:
+  class Result < Model # :nodoc:
+    attr_accessor :grade_name, :score, :subject_name, :test_id, :year
+  end
+end

data/lib/great_schools/review.rb

@@ -0,0 +1,47 @@
+module GreatSchools # :nodoc:
+  # = GreatSchools Review
+  class Review < Model
+    attr_accessor :school_name, :school_address
+    attr_accessor :review_link, :rating, :submitter, :posted_date, :comments
+
+    class << self # Class methods
+      # Returns a list of the most recent reviews for any schools in a city.
+      #
+      # ==== Attributes
+      #
+      # * +state+ - Two letter state abbreviation
+      # * +city+  - Name of 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 for_city(state, city, options = {})
+        options[:cutoffAge] = options.delete(:cutoff_age) # TODO: make helper method to camelCase or map query attributes
+
+        response = GreatSchools::API.get("reviews/city/#{state.upcase}/#{parameterize(city)}", options.slice(:cutoffAge, :limit))
+
+        Array.wrap(response).map { |review| new(review) }
+      end
+
+      # Returns a list of the most recent reviews 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+
+      #
+      # ==== Options
+      #
+      # * +:limit+ - Maximum number of reviews to return. This defaults to 5.
+      def for_school(state, id, options = {})
+        response = GreatSchools::API.get("reviews/school/#{state.upcase}/#{id}", options.slice(:limit))
+
+        Array.wrap(response).map { |review| new(review) }
+      end
+    end
+  end
+end

data/lib/great_schools/school.rb

@@ -0,0 +1,177 @@
+module GreatSchools # :nodoc:
+  # = GreatSchools School
+  class School < Model
+    attr_accessor :id, :name, :type, :grade_range, :enrollment, :district_id, :district, :district_nces_id, :nces_id
+    attr_accessor :city, :state, :address, :phone, :fax, :website, :latitude, :longitude
+    attr_accessor :overview_link, :ratings_link, :reviews_link, :parent_reviews, :parent_rating
+
+    alias_method :gs_id=, :id=
+    alias_method :lat=, :latitude=
+    alias_method :lon=, :longitude=
+
+    class << self # Class methods
+      # Returns a list of schools in a city.
+      #
+      # ==== Attributes
+      #
+      # * +state+ - Two letter state abbreviation
+      # * +city+  - Name of city
+      #
+      # ==== Options
+      #
+      # * +:school_types+ - Type of school(s) you wish to appear in the list:
+      #                     'public', 'charter', and/or 'private'
+      # * +:level+        - Level of school you wish to appear in the list:
+      #                     'elementary-schools', 'middle-schools', or 'high-schools'
+      # * +:sort+         - How to sort the results, either by name (ascending),
+      #                     by GreatSchools rating (descending), or by overall
+      #                     parent rating (descending). The default sort is name
+      #                     (ascending). When sorted by rating, schools without
+      #                     a rating will appear last. Options: 'name',
+      #                     'gs_rating', or 'parent_rating'
+      # * +:limit+        - Maximum number of schools to return. This defaults
+      #                     to 200. To get all results, use -1.
+      # --
+      # TODO: handle validations
+      # ++
+      def browse(state, city, options = {})
+        school_types  = Array.wrap(options.delete(:school_types)).join('-')
+        level         = options.delete(:level)
+
+        url = "schools/#{state.upcase}/#{parameterize(city)}"
+        url << "/#{school_types}" if school_types.present?
+        url << "/#{level}"        if level.present?
+
+        response = GreatSchools::API.get(url, options.slice(:sort, :limit))
+
+        Array.wrap(response).map { |school| new(school) }
+      end
+
+      # Returns a list of schools closest to the center of a city, ZIP Code or
+      # address.
+      #
+      # ==== Attributes
+      #
+      # * +state+ - Two letter state abbreviation
+      #
+      # ==== Options
+      #
+      # * +:zip_code+         - 5 digit zip code
+      # * +:city+             - Name of city
+      # * +:address+          - Address of location
+      # * +:latitude+         - Latitude of location
+      # * +:longitude+        - Longitude of location
+      # * +:school_types+     - Type of school(s) you wish to appear in the list:
+      #                         'public', 'charter', and/or 'private'
+      # * +:level+            - Level of school you wish to appear in the list:
+      #                         'elementary-schools', 'middle-schools', or 'high-schools'
+      # * +:minimum_schools+  - Minimum number of schools to return. When provided,
+      #                         if the initial query field yields fewer schools than
+      #                         this value, the radius will be increased in 5 mile
+      #                         increments to a maximum of 50 miles or until the
+      #                         result set has enough schools to meet this value.
+      #                         Maximum value is 200. This value must be less than
+      #                         the limit or else it is ignored.
+      # * +:radius+           - Miles radius to confine search to. This default to 5,
+      #                         with a maximum of 50.
+      # * +:limit+            - Maximum number of schools to return. This defaults to 200.
+      # --
+      # TODO: handle validations
+      # ++
+      def nearby(state, options = {})
+        options[:lat]             = options.delete(:latitude)
+        options[:levelCode]       = options.delete(:level)
+        options[:lon]             = options.delete(:longitude)
+        options[:minimumSchools]  = options.delete(:minimum_schools)
+        options[:schoolType]      = options.delete(:school_types).try(:join, '-')
+        options[:state]           = state
+        options[:zip]             = options.delete(:zip_code)
+
+        options.slice!(:address, :city, :lat, :levelCode, :limit, :lon, :minimumSchools, :radius, :schoolType, :state, :zip)
+
+        response = GreatSchools::API.get('schools/nearby', options)
+
+        Array.wrap(response).map { |school| new(school) }
+      end
+
+      # Returns profile data for a specific 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 profile(state, id)
+        response = GreatSchools::API.get("schools/#{state.upcase}/#{id}")
+
+        new(response)
+      end
+
+      # Returns a list of schools based on a search string.
+      #
+      # ==== Attributes
+      #
+      # * +state+ - Two letter state abbreviation
+      # * +query+ - Search query string
+      #
+      # ==== Options
+      #
+      # * +:level+  - Level of school you wish to appear in the list:
+      #               'elementary-schools', 'middle-schools', or 'high-schools'
+      # * +:sort+   - This call by default sorts the results by relevance. You
+      #               can sort the results alphabetically by using 'alpha'.
+      # * +:limit+  - Maximum number of schools to return. This defaults to
+      #               200 and must be at least 1.
+      # --
+      # TODO: handle validations
+      # ++
+      def search(state, query, options = {})
+        options[:levelCode] = options.delete(:level)
+        options[:q]         = query
+        options[:state]     = state
+        options.slice!(:state, :q, :levelCode, :sort, :limit)
+
+        response = GreatSchools::API.get('search/schools', options)
+
+        Array.wrap(response).map { |school| new(school) }
+      end
+    end
+
+    # Returns census and profile data for the school.
+    def census
+      GreatSchools::Census.for_school(state, id)
+    end
+
+    # Set an array of +GreatSchools::Review+.
+    #
+    # ==== Attributes
+    #
+    # * +params+ - a +Hash+ or +Array+ of +GreatSchools::Review+ attributes.
+    def parent_reviews=(params)
+      @parent_reviews = []
+
+      params = params['review'] if params.is_a?(Hash) && params.key?('review')
+
+      Array.wrap(params).each do |hash|
+        @parent_reviews << GreatSchools::Review.new(hash)
+      end
+
+      @parent_reviews
+    end
+
+    # Returns a list of the most recent reviews for the school.
+    #
+    # ==== Options
+    #
+    # * +:limit+ - Maximum number of reviews to return. This defaults to 5.
+    def reviews(options = {})
+      GreatSchools::Review.for_school(state, id, options.slice(:limit))
+    end
+
+    # Returns test and rank data for the school.
+    def score
+      GreatSchools::Score.for_school(state, id)
+    end
+  end
+end

data/lib/great_schools/score.rb

@@ -0,0 +1,47 @@
+module GreatSchools # :nodoc:
+  # = GreatSchools Score
+  class Score < Model
+    attr_accessor :school_name, :rank, :tests
+
+    class << self # Class methods
+      # Returns test and rank data for a specific 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/tests/#{state.upcase}/#{id}")
+
+        new(response)
+      end
+    end
+
+    # Set the +GreatSchools::Rank+.
+    #
+    # ==== Attributes
+    #
+    # * +params+ - a +Hash+ of +GreatSchools::Rank+ attributes.
+    def rank=(params)
+      @rank = GreatSchools::Rank.new(params)
+    end
+
+    # Set an array of +GreatSchools::Test+.
+    #
+    # ==== Attributes
+    #
+    # * +params+ - a +Hash+ or +Array+ of +GreatSchools::Test+ attributes.
+    def tests=(params)
+      @tests = []
+
+      Array.wrap(params).each do |hash|
+        @tests << GreatSchools::Test.new(hash)
+      end
+
+      @tests
+    end
+    alias_method :test=, :tests=
+  end
+end

data/lib/great_schools/test.rb

@@ -0,0 +1,22 @@
+module GreatSchools # :nodoc:
+  # = GreatSchools Test
+  class Test < Model
+    attr_accessor :name, :id, :description, :abbreviation, :scale, :level_code, :results
+
+    # Set an array of +GreatSchools::Result+.
+    #
+    # ==== Attributes
+    #
+    # * +params+ - a +Hash+ or +Array+ of +GreatSchools::Result+ attributes.
+    def results=(params)
+      @results = []
+
+      Array.wrap(params).each do |hash|
+        @results << GreatSchools::Result.new(hash)
+      end
+
+      @results
+    end
+    alias_method :test_result=, :results=
+  end
+end

data/lib/great_schools/version.rb

@@ -0,0 +1,14 @@
+module GreatSchools # :nodoc:
+  class Version # :nodoc:
+    MAJOR = 0 # version when you make incompatible API changes
+    MINOR = 1 # version when you add functionality in a backwards-compatible manner
+    PATCH = 0 # version when you make backwards-compatible bug fixes
+
+    class << self # Class methods
+      # MAJOR.MINOR.PATCH per Semantic Versioning 2.0.0
+      def to_s
+        "#{MAJOR}.#{MINOR}.#{PATCH}"
+      end
+    end
+  end
+end

data/spec/fixtures/browse_districts.xml

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<districts>
+  <district>
+    <name>San Francisco Unified School District</name>
+    <ncesCode>0634410</ncesCode>
+    <districtRating>6</districtRating>
+    <address>555 Franklin St., San Francisco, CA 94102</address>
+    <phone>(415) 241-6000</phone>
+    <fax>(415) 241-6012</fax>
+    <website>http://www.sfusd.k12.ca.us</website>
+    <gradeRange>K-12 &amp; ungraded</gradeRange>
+    <totalSchools>121</totalSchools>
+    <elementarySchools>84</elementarySchools>
+    <middleSchools>36</middleSchools>
+    <highSchools>34</highSchools>
+    <publicSchools>113</publicSchools>
+    <charterSchools>8</charterSchools>
+  </district>
+  <district>
+    <name>San Francisco County Office of Education</name>
+    <ncesCode>0691111</ncesCode>
+    <districtRating>1</districtRating>
+    <address>555 Franklin St., San Francisco, CA 94102</address>
+    <phone>(415) 241-6000</phone>
+    <fax>(415) 241-6012</fax>
+    <website>http://www.sfusd.k12.ca.us</website>
+    <gradeRange>K-12</gradeRange>
+    <totalSchools>4</totalSchools>
+    <elementarySchools>2</elementarySchools>
+    <middleSchools>3</middleSchools>
+    <highSchools>4</highSchools>
+    <publicSchools>4</publicSchools>
+    <charterSchools>0</charterSchools>
+  </district>
+</districts>

data/spec/fixtures/browse_schools.xml

@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<schools>
+  <school>
+    <gsId>13978</gsId>
+    <name>Alder Creek Middle School</name>
+    <type>public</type>
+    <gradeRange>6-8</gradeRange>
+    <enrollment>598</enrollment>
+    <city>Truckee</city>
+    <state>CA</state>
+    <districtId>509</districtId>
+    <district>Tahoe-Truckee Joint Unified School District</district>
+    <districtNCESId>0638770</districtNCESId>
+    <address>10931 Alder Dr., Truckee, CA  96161</address>
+    <phone>(530) 582-2750</phone>
+    <fax>(530) 582-7640</fax>
+    <website>http://www.ttusd.org</website>
+    <ncesId>063877011005</ncesId>
+    <lat>39.3454</lat>
+    <lon>-120.1735</lon>
+    <overviewLink>http://www.greatschools.org/modperl/browse_school/ca/13978?s_cid=gsapi</overviewLink>
+    <ratingsLink>http://www.greatschools.org/school/rating.page?state=CA&amp;id=13978&amp;s_cid=gsapi</ratingsLink>
+    <reviewsLink>http://www.greatschools.org/school/parentReviews.page?state=CA&amp;id=13978&amp;s_cid=gsapi</reviewsLink>
+  </school>
+  <school>
+    <gsId>11039</gsId>
+    <name>Cold Stream Alternative School</name>
+    <type>public</type>
+    <gradeRange>9-12</gradeRange>
+    <enrollment>47</enrollment>
+    <city>Truckee</city>
+    <state>CA</state>
+    <districtId>509</districtId>
+    <district>Tahoe-Truckee Joint Unified School District</district>
+    <districtNCESId>0638770</districtNCESId>
+    <address>11661 Donner Pass Rd., Truckee, CA  96161</address>
+    <phone>(530) 582-2640</phone>
+    <fax>(530) 582-7640</fax>
+    <ncesId>063877006175</ncesId>
+    <lat>39.3259</lat>
+    <lon>-120.2147</lon>
+    <overviewLink>http://www.greatschools.org/modperl/browse_school/ca/11039?s_cid=gsapi</overviewLink>
+    <ratingsLink>http://www.greatschools.org/school/rating.page?state=CA&amp;id=11039&amp;s_cid=gsapi</ratingsLink>
+    <reviewsLink>http://www.greatschools.org/school/parentReviews.page?state=CA&amp;id=11039&amp;s_cid=gsapi</reviewsLink>
+  </school>
+</schools>