You are currently viewing Best API Series: GreatSchools API Integration with Ruby on Rails

Best API Series: GreatSchools API Integration with Ruby on Rails

  • Post published:May 18, 2020

Choosing the right school is a very tricky business. How many of you know that GreatSchools API can be used for this very purpose? Yes, its integration with Ruby on Rails enables a powerful function that enables parents to find the best schools for their kids.

Get to know GreatSchools API

GreatSchools API is a REST-based web service that makes it easier for the users to find great schools in the US by using zip code, city, or full address. It has a large database that contains all the relevant information related to schools, locations, school profiles, detail of scores, school reviews, data metrics by school districts, and government agencies.

In this article, we will together unveil how to integrate GreatSchools API with rails? In addition to this, we will playfully explore API functionality like access to school profiles, scores, school reviews, ratings, school districts, and city profiles in our Rails application.

Discover Educational Opportunities with GreatSchools API

It is easier to explore more educational opportunities with the help of GreatSchools. Because the essential information is easily accessible at all times. You can use GreatSchools Ratings for confirmation and trusted information. Parents can conveniently choose the right school for their children. One can also utilize the data to improve the functioning of schools and the quality of education.

What GreatSchools API has to offer us?

 GreatSchools API enables the users to find nearby U.S. schools by zip code, city, or full address. Once you find a school you can view the information about each school, including address. Dig deeper and retrieve reviews from the users or the students’ test scores.

It is important to mention that GreatSchools is a non-profit entity that provides free and authentic information concerning schools and parenting resources. It has become easier to aid the learning process at home and school as well.

How to do Technical Integration of GreatSchools API?

The foremost thing is to add some gems which will help you greatly in the integration of GreatSchools API. To make this session simple, we are just showing how to interact with the Rest API and get relevant details. We are not storing any data into the database.

Install Gems:

  • great_schools A Ruby interface to the GreatSchools API
  • httparty to query web services and examine the resulting output
gem 'great_schools' 
gem 'httparty' 

httparty to query web services and examine the resulting output. Now you can add the following lines into your Gemfile of a Rails application.

Run Bundle Install to install these gems.

Now we need to get the API keys from GreatSchools API Key Request Portal to use for the authorization while making API’s request.

  1. Create a new great_schools.yml in ./config/ directory to store API keys and add the following code into it.
ENV['GREATSCHOOLS_API_KEY'] = 'YOUR_API_KEY’

If you’re using source control such as git, now would be a good time to exclude the great_schools.yml file from source control to avoid inadvertently leaking your API key.

Sending API requests to GreatSchools API

1. Browse Schools with GreatSchools API

Here is the list of schools according to the search criteria.

Parameters

The “key” parameter is what you use to send us your API key. Other parameters are to describe how you would like to receive the type of data.

 Name Description Sample Values
 State Two letter state abbreviation CA
 City Name of city, with spaces replaced with hyphens. San Francisco becomes “San-Francisco”
 School type Type of school you wish to appear in the list “public”, “charter”, “private”,
 level Level of school you wish to appear in the list “elementary-schools”, “middle-schools”, “high-schools”

Sample Data:

school = GreatSchools::School.nearby('CA', 'Truckee').limit(1)
//Behind API call format:
https://api.greatschools.org/schools/CA/Truckee?key=[yourAPIkey]&limit=1

It assists to GET to the requested endpoint. Then it sends the API_key and includes query parameters that are passed. It returns 1 school in Truckee, CA

Following will be the XML response of the above request:

<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>https://www.ttusd.org</website>
<ncesId>063877011005</ncesId>
<lat>39.3454</lat>
<lon>-120.1735</lon>
<overviewLink>
https://www.greatschools.org/modperl/browse_school/ca/13978?s_cid=gsapi
</overviewLink>
<ratingsLink>
https://www.greatschools.org/school/rating.page?state=CA&id=13978&s_cid=gsapi
</ratingsLink>
</school>
</schools>

2. Browse School Reviews

The below list includes the most recent reviews for a school or for any schools in a city.

Parameters

The “key” parameter is what you use to send us your API key. Other parameters are to describe how you would like to receive the type of data.

 Name Description Sample Values
 State Two-letter state abbreviation CA
 school or city Return reviews for a school or for any schools in a city “school” or “city”
 City Name of city, with spaces replaced with hyphens. San Francisco becomes “San-Francisco”
 gsID Numeric id of school 1
 cutoffAge Reviews must have been published after this many days ago to be returned. Only valid for the recent reviews in a city call. 7
 limit Maximum number of reviews to return. This defaults to 5. 10
 q* Search query string. The query string must be properly URL-encoded. Alameda High School
 topicId To return topical school reviews, specify the topic id. 1

Sample Data:

reviews = GreatSchools::School.reviews('CA', 'Alameda Christian')
reviews.first
Behind API call format:
https://api.greatschools.org/search/schools?key=[yourAPIKey]&state=CA&q=Alamed
a+Christian&limit=1

It aids a GET request to the requested endpoint and returns the found result in the response. It will Return most recent review for Alameda Christian school in the city of Alameda, CA.

Following will be the XML response of the above request.

<schools>
<school>
<gsId>8485</gsId>
<name>Alameda Christian School</name>
<type>private</type>
<gradeRange>K-8</gradeRange>
<enrollment>52</enrollment>
<parentRating>5</parentRating>
<city>Alameda</city>
<state>CA</state>
<address>2226 Pacific Ave,
Alameda, CA 94501
</address>
<phone>(510) 523-1000</phone>
<ncesId>00079445</ncesId>
<lat>37.768623</lat>
<lon>-122.243965</lon>
<overviewLink>
https://www.greatschools.org/cgi-bin/ca/private/8485?s_cid=gsapi
</overviewLink>
<ratingsLink>
https://www.greatschools.org/school/rating.page?state=CA&id=8485&s_cid=gsapi
</ratingsLink>
<reviewsLink>
https://www.greatschools.org/school/parentReviews.page?state=CA&id=8485&s_cid=gsapi
</reviewsLink>
</schools>

3. School Census Data

This call will return census and profile data for a school.

Parameters

The “key” parameter is what you use to send us your API key. Other parameters are to describe how you would like to receive the type of data.

 Name Description Sample Values
 State Two letter state abbreviation CA
 gsID Numeric id of school 1

Sample Data:

gsID = 20
#North Dakota
State = ‘ND’
reviews = GreatSchools::CENSUS.for_school(state, gsID)
Behind API call format:
https://api.greatschools.org/school/census/ND/20?key=[yourkey]

It makes a GET request and returns census and profile data for the requested school in North Dakota with GreatSchools ID of 20 including lunch pricing, student/teacher ratio, ethnicity, etc.

Following will be the XML response of the above request.

<census-data>
<schoolName>Simle Middle School</schoolName>
<address>1215 N 19th St, Bismarck, ND 58501</address>
<latitude>46.8179</latitude>
<longitude>-100.7631</longitude>
<phone>(701) 221-3570</phone>
<type>public</type>
<district>Bismarck 1</district>
<enrollment>851</enrollment>
<freeAndReducedPriceLunch>23.3843</freeAndReducedPriceLunch>
<studentTeacherRatio>14.1</studentTeacherRatio>
<ethnicities>
<ethnicity>
<name>White, non-Hispanic</name>
<value>91.0693</value>
<year>2007</year>
</ethnicity>
<ethnicity>
<name>Black, non-Hispanic</name>
<value>0.587544</value>
<year>2007</year>
</ethnicity>
<ethnicity>
<name>Hispanic</name>
<value>0.822562</value>
<year>2007</year>
</ethnicity>
<ethnicity>
<name>Asian/Pacific Islander</name>
<value>0.705053</value>
<year>2007</year>
</ethnicity>
<ethnicity>
<name>Native American or Native Alaskan</name>
<value>6.81551</value>
<year>2007</year>
</ethnicity>
</ethnicities>
</census-data>

Is it easier to get a customized API?

You can make desired changes as per your customized data attained from the GreatSchools API. If you’d like to explore more about the APIs, you can also check the GreatSchools API Technical Overview for official documentation.

The best thing about their site is that you have lots of options. So if you are thinking to build something similar with the integration of this GreatSchools API, here is an inside look for you:

GreatSchools API Vs Niche

  GreatSchools Niche
License Non-Profit, Just request API key and
start using it.
Paid, Annual license starts at $5,000
Rest API Dedicate Rest Based Web API to Access
all the data
Deliver data as a custom file, don’t
have API Service
Calculate Data Using
Factors
Student Achievement (SA) Academics (A)
Student Growth (SG) Culture & Diversity (CD)
College Readiness (CR) Health & Safety (HS)
  Teachers (T)
  Resources & Facilities (RF)
  Clubs & Activities (CA)

If you want to launch a new school search tool or looking for the best educational APIs. vteams can help you get the best APIs and you can create your own customized product with the API of your choice.

You can also feature GreatSchools data on your site, or better yet integrate the API for more convenience. Either way, it’s a win-win for those looking for a cost-effective method to create similar sites and customized educational sites with LMS.

Build your next project with us, lets talk!