A gem to interact with the education.com free schoolfinder api.
Register for a Schoolfinder API Key Here: www.education.com/schoolfinder/tools/webservice/
Schoolfinder API Documentation: www.education.com/schoolfinder/tools/webservice/documentation/
gem install schoolfinder
In a rails app:
config.gem 'schoolfinder'
Create a new instance of the Schoolfinder Client
@schoolfinder = Schoolfinder::Client.new('your_api_key')
You can also pass an optional http timeout setting that httparty will pass to net/http
@schoolfinder = Schoolfinder::Client.new('your_api_key', 5)
This would make the response trigger a Timeout::Error on the request. The client then rescues that request and passes a fake response that will trigger a Schoolfinder::Error with the code 0 and message “a timeout occured”. This is because Schoolfinder currently does not have a error code 0 (only 1-7, see here: www.education.com/webservice/documentation/?section=schoolsearch) So this would raise a:
#<Schoolfinder::Error: Schoolfinder Error: a timeout occured (code: 0)>
The following methods are available to the Schoolfinder::Client class, each method corresponds to an api call Each method returns a Schoolfinder::Response which responds to a call to :body
:body is an instance of Hashie::Rash. Hashie::Rash inherits from Hashie::Mash (see the following: github.com/intridea/hashie ) with the only difference being that in a Hashie::Rash all keys (method names) of the original hash are “rubyified”, converted from camelCase to underscore. So, “methodName” would be “method_name”. This in turn looks something like the following example:
@response = @schoolfinder.school_search(:zip => 02215) @response.body.first.schoolname # => 'Fenway Park Academy'
Notes on passing params to each method: All parameter keys should be passed in exactly as stated in the schoolfinder api documentation linked above.
The following default parameters are automatically passed through so you don’t need to worry about them:
sn = sf, key = (your API key), f = (method_name), v = 3
@response = @schoolfinder.school_search
school_search takes an optional params hash. @response.body is an Array of Hashie:Rash objects
@response = @schoolfinder.test_rating(:nces_id => "061029001146")
test_rating requires either an nces_id or schoolid parameter passed through in hash format. @response.body is an Array of Hashie:Rash objects
@response = @response = @schoolfinder.student_diversity(:nces_id => "450231000564")
student_diversity requires one of nces_id, schoolid, city or state @response.body is a Hashie:Rash object
@response = @response = @schoolfinder.test_scores(:nces_id => "450231000564")
test_scores requires one of schoolid, nces_id, districtid, districtleaid @response.body is a Hashie:Rash object
@response = @schoolfinder.teacher_stats(:nces_id => "450231000564", :districtleaid => "4502310")
teacher_stats requires one of schoolid, nces_id, districtid, districtleaid @response.body is a Hashie:Rash object
@response = @schoolfinder.student_stats(:nces_id => "450231000564", :districtleaid => "4502310", :city => "Greenville", :state => "SC")
student_stats requires one of schoolid, nces_id, districtid, districtleaid, city, state @response.body is a Hashie:Rash object
@response = @schoolfinder.get_reviews(:schoolid => "25381")
get_reviews requires one of schoolid, nces_id @response.body is a Hashie:Rash object
@response = @schoolfinder.number_of("Greenville", "SC")
number_of requires 2 parameters (city, state) @response.body is an Array of Hashie:Rash objects
@response = @schoolfinder.district_search(:city => "Greenville", :state => "SC")
district_search requires one of districtid, districtleaid, districtname, state, city, zip @response.body is an Array of Hashie:Rash objects
@response = @schoolfinder.branding_data
branding_data takes optional parameters (as noted in the documentation) @response.body is a Hashie:Rash object
-
Fork the project.
-
Make your feature addition or bug fix.
-
Add tests for it. This is important so I don’t break it in a future version unintentionally.
-
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-
Send me a pull request. Bonus points for topic branches.
Copyright © 2010 Tom Cocca. See LICENSE for details.