api wrapper for the education.com schoolfinder
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
spec
.document
.gitignore
.rspec
Gemfile
LICENSE
README.rdoc
Rakefile
schoolfinder.gemspec

README.rdoc

schoolfinder

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/

Installation

gem install schoolfinder

In a rails app:

config.gem 'schoolfinder'

Usage

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'

Schoolfinder::Client methods

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

Search for Schools:

@response = @schoolfinder.school_search

school_search takes an optional params hash. @response.body is an Array of Hashie:Rash objects

Get Test Ratings:

@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

Get Student Diversity

@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

Get Test Scores

@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

Get Teacher Stats

@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

Get Student Stats

@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

Get Reviews

@response = @schoolfinder.get_reviews(:schoolid => "25381")

get_reviews requires one of schoolid, nces_id @response.body is a Hashie:Rash object

Number Of (for a city and state)

@response = @schoolfinder.number_of("Greenville", "SC")

number_of requires 2 parameters (city, state) @response.body is an Array of Hashie:Rash objects

District Search

@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

Get Branding Data

@response = @schoolfinder.branding_data

branding_data takes optional parameters (as noted in the documentation) @response.body is a Hashie:Rash object

Note on Patches/Pull Requests

  • 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

Copyright © 2010 Tom Cocca. See LICENSE for details.