Education.com
Try
Brainzy
Try
Plus

SchoolFinder Web Service Documentation

Education.com provides access to comprehensive school data via a free web service API.
If you have any questions about implementing or using the SchoolFinder Web Service, please contact us at api-support@education.com.


  • How to use the web service API

    1. Acquire an API key. An API key is a unique string of characters that is used by the web service to authenticate the user of the API. Any use of any web service method requires an API key. Click here to request an API key.
    2. Execute a web service API method. The simplest way to execute a method is from a web browser using a URL in this format:

      http://api.education.com/service/service.php?f=schoolSearch&sn=sf&key=4c338ac1ee0d6&zip=94063


      In this example, the API method schoolSearch is being executed with service name sn = sf (SchoolFinder), and an API key = '4c338ac1ee0d6' (your API key will be different. Do not use this one). The parameter 'zip' is being passed to the method which causes a search for schools in zipcode '94063' to be executed and the results returned to the caller. Please note that when passing a name parameter, you must insert a "+" where there are spaces in names. Thus, 'New York' would become 'New+York'.
  • School Data Calls

    • schoolSearch
    • getStudentDiversity
    • getTestScores
    • getTeacherStats
    • getStudentStats
    • getReviews
    • numberOf
    • districtSearch
  • Supported request formats

    • REST
    • JSON
    • PHP
  • Supported response formats

    • JSON
    • PHP
    • XML
  • Usage limits:

    When an API key is requested, it is mailed to you and can be used immediately. The following limits are initially placed on clients of the web service. Once your implementation is ready to go live, please email us at api-support@education.com to confirm that it meets our Terms. At that time, we’ll completely lift any limits from your API key.
    • Bandwidth: The amount of data that can be transferred from a web service method is limited to a fixed number of bytes per day.
    • Connections: The number of connections that can be made to the web service API is limited to a fixed number per day.
    • Time: The length of time that an API key is valid is limited. Initally it is valid for two months for development, and can be extended if needed.
  • Web Service Versions:

    This documentation represents the latest web service version. Thus v=3 is added to all example calls. To use older versions, see Version 1 documentation or Version 3 documentation .

schoolSearch

  • Version 2.0
  • Behavior:
    • Returns an array of school profiles that match the search parameters.
  • Parameters:
    • required:
      • sn = sf
      • f = schoolSearch
      • key = (your API key)
      • v = 2
    • optional:
      • nces_id = The NCES id of the school.
      • schoolid = The Education.com id of the school.
      • reqf = The name of the format that the server should expect the request data in
      • resf = The name of the format that the server should return the response in
      • districtid = The internal Education.com id of a school district.
      • districtleaid = The LEA id of a school district.
      • zip = A five digit US postal code
      • city = The name of a city
      • county = The name of a county
      • state = The two letter abbreviation of a state ex: SC
      • distance = A distance in miles from a specific latitude and longitude. Suggested value is around 1.5 miles. Please note that distance is required when including latitude and longitude parameters.
      • latitude = A latitude which serves as the center for distance searches.
      • longitude = A longitude which serves as the center for distance searches.
      • minresult = A minimum number of search results to return. The search will be expanded in increments of 0.5 from the given latitude and longitude or zipcode, until the minresult is reached.
  • Returns: an array of zero or more:
    • schoolid
    • schoolname
    • zip
    • address
    • city
    • districtid
    • districtleaid
    • AYPresult
    • APIScore
    • distance
    • enrollment
    • gradelevel
    • gradesserved
    • latitude
    • longitude
    • phonenumber
    • schooldistrictname
    • schooltype
    • state
    • studentteacherratio
    • website
    • nces_id
    • url - The URL to the Education.com profile page of the school.
  • XSD Schema
  • examples
    • Search for school by zipcode:
      in rest format, in json format, in php format
    • response: in json format, in php format, in xml format

getTestRating

  • Behavior:
    • Returns Education.com TestRating for a single school. The Education.com TestRating is a number ranking (1-10) calculated by Education.com that provides an overview of a school’s test performance for a given year, by comparing the school’s state standardized test results to those of other schools in the same state.
  • Parameters:
    • required:
      • sn = sf
      • f = getTestRating
      • key = (your API key)
      • schoolid = The Education.com id of the school.
      • nces_id = The National Center for Education Statistics (NCES) id of the school.
      • v = 2
  • Returns: an array of the following data:
    • testrating_text
    • testrating_image_small
    • testrating_image_large
    • testrating_year
    • lsp: A link to a school profile on education.com.
  • Note the Education.com TestRating Terms of Use
  • XSD Schema
  • examples
    • Search for school by zipcode:
      in rest format, in json format, in php format
    • response: in json format, in php format, in xml format

getStudentDiversity

  • Version 2.0
  • Behavior:
    • Returns Gender and ethnicity statistics for a single school and/or city. Note that city totals and averages are based on the number of schools within a city, not the number of students.
  • Parameters:
    • sn = sf
    • f = getStudentDiversity
    • key = (your API key)
    • schoolid = The id of the school.
    • nces_id = The nces id of the school.
    • city = a city name
    • state = a two letter state code
    • v = 2
  • Returns: an array
    • school
      • gender
        • name
        • percentage
        • total
        • year
      • ethnicity
        • name
        • percentage
        • total
        • year
    • city
      • gender
        • name
        • percentage
        • total
        • year
        • average
      • ethnicity
        • name
        • percentage
        • total
        • year
        • average
  • XSD Schema
  • examples
    • Get student diversity information for school where nces_id=450231000564
      http://api.education.com/service/service.php?f=getStudentDiversity&key=4c338ac1ee0d6&nces_id=450231000564&sn=sf&v=2&city=Greenville&state=SC
    • response: in json format, in php format
  • Ethnicity Values

getTestScores

  • Version 2.0
  • Behavior:
    • Returns test score information for a single school, district, or city. Note that city totals and averages are based on the number of schools within a city, not the number of students.
  • Parameters:
    • required:
      • sn = sf
      • f = getTestScores
      • key = (your API key)
        • schoolid = The id of the school.
        • OR nces_id = The nces id of the school.
        • OR districtid = The id of the district.
        • OR districtleaid = The LEA id of the district.
    • optional:
      • sd = true Tells the function to also return test score information about the state that the school is in.
      • dd = true Tells the function to also return test score information about the district that the school is in.
      • cd = true Tells the function to also return test score information about the city that the school is in.
  • Returns: an array of zero or more:
    • school
      • grade
      • testname
      • subject
      • score
      • year
      • max_score
      • description
    • district
      • grade
      • testname
      • subject
      • score
      • year
      • max_score
      • description
    • state
      • grade
      • testname
      • subject
      • score
      • year
      • max_score
      • description
    • city
      • grade
      • testname
      • subject
      • average
      • percentage
      • year
      • max_score
      • description
  • XSD Schema
  • examples
    • Get test score information for school where nces_id=450231000564
      http://api.education.com/service/service.php?f=getTestScores&key=4c338ac1ee0d6&nces_id=450231000564&sn=sf&v=2
    • response: in json format, in php format in xml format

getTeacherStats

  • Version 2.0
  • Behavior:
    • Returns statistics about teachers for a single school and/or district.
  • Parameters:
    • sn = sf
    • f = getTeacherStats
    • key = (your API key)
    • schoolid = The id of the school.
    • nces_id = The nces id of the school.
    • districtid = The id of the district.
    • districtleaid = The LEA id of the district.
  • Returns: an array of zero or more:
    • school
      • stat_type
      • stat_name
      • year
      • percentage
      • total
    • city
      • stat_type
      • stat_name
      • year
      • percentage
      • total
      • average
    • district
      • stat_type
      • stat_name
      • year
      • percentage
      • total
      • average
  • XSD Schema
  • examples
    • Get teacher statistics for school where nces_id=450231000564 and city='Greenville' and state='SC'
      http://api.education.com/service/service.php?f=getTeacherStats&key=4c338ac1ee0d6&nces_id=450231000564&districtleaid=4502310&sn=sf&v=2
    • response: in json format, in php format

getStudentStats

  • Version: 2.0
  • Behavior:
    • Returns statistics about students for a single school and/or city and/or district. Note that city totals and averages are based on the number of schools within a city, not the number of students.
  • Parameters:
    • sn = sf
    • f = getStudentStats
    • key= (your API key)
    • schoolid = The id of the school.
    • nces_id = The nces id of the school.
    • districtid = The id of the district.
    • districtleaid = The LEA id of the district.
    • city = The name of a city
    • state = The two letter abbreviation of a state ex: SC
    • v = 2
  • Returns: an array of zero or more:
    • school
      • stat_type
      • data
        • stat_name
        • year
        • percentage
        • total
    • city
      • stat_type
      • data
        • stat_name
        • year
        • percentage
        • total
        • average
    • district
      • stat_type
      • data
        • stat_name
        • year
        • percentage
        • total
        • average
  • XSD Schema
  • examples
    • Get student statistics for school where nces_id=450231000564 and city='Greenville' and state='SC'
      http://api.education.com/service/service.php?f=getStudentStats&key=4c338ac1ee0d6&nces_id=450231000564&districtleaid=4502310&sn=sf&city=Greenville&state=SC&v=2
    • response: in json format, in php format

getReviews

  • Version 2.0
  • Behavior:
    • Returns user reviews and comments for a single school
  • Parameters:
    • sn = sf
    • f = getReviews
    • key = (your API key)
    • schoolid = The id of the school.
    • nces_id = The nces id of the school.
  • Returns: an array of one or more:
    • rating
      • count
      • total
      • average
    • review
      • comment
  • XSD Schema
  • examples
    • Get user ratings and reviews for school where schoolid=25381
      http://api.education.com/service/service.php?f=getReviews&key=4c338ac1ee0d6&schoolid=25381&sn=sf
    • response: in json format, in php format

numberOf

  • Version 2.0
  • Behavior:
    • Returns an array of counts for each type of school in a given city and state. Also includes counts for all schools and all districts.
  • Parameters:
    • required:
      • sn = sf
      • f = numberOf
      • key = (your API key)
      • city = The name of a city
      • state = The two letter abbreviation of a state ex: SC
  • Returns: an array of zero or more of any of the following combinations:
    • school
    • total
    • gradelevel
    • total
    • schooltype
    • total
    • district
    • total
  • XSD Schema
  • examples
    • Get number of schools in Greenville, SC:
      in rest format,
      http://api.education.com/service/service.php?f=numberOf&key=4c338ac1ee0d6&city=Greenville&sn=sf&state=SC&v=2
      in json format, in php format
    • response: in json format, in php format, in xml format

districtSearch

  • Version 2.0
  • Behavior:
    • Returns an array of school district profiles that match a given criteria.
  • Parameters:
    • required:
      • sn = sf
      • f = districtSearch
      • key = (your API key)
      • districtid: The Education.com id of the district.
      • districtleaid: The LEA id of the district.
      • districtname: The name of the district.
      • state: The state that the district is in.
      • city: The city that the district serves. This will call all districts that have schools in this city.
      • zip: The zip code that the distrcit serves. This will call all districts that have schools in this zip code.
  • Returns: an array of zero or more of district profiles:
      district
    • districtid
    • districtname
    • state
    • districtleaid
    • address
    • city
    • gradesserved
    • zip
    • phonenumber
  • XSD Schema
  • examples
    • Get all school districts in Greenville, SC:
      in rest format,
      http://api.education.com/service/service.php?f=districtSearch&key=4c338ac1ee0d6&city=Greenville&sn=sf&state=SC&v=2
      in json format, in php format
    • response: in json format, in php format, in xml format

gbd

  • Behavior:
    • Returns links back to Education.com. Although some links are always required, please refer to our Terms for further clarification on what links need to be displayed based on your chosen implementation.
  • Parameters:
    • required:
      • sn = sf
      • f = gbd
    • optional:
      • schoolid = The id of the school.
      • nces_id = The nces id of the school.
      • city = The name of a city
      • state = The two letter abbreviation of a state ex: SC
  • Returns: an array of the following data:
    • logosrc: a link to an education.com logo image.
    • disclaimer: Disclaimer text.
    • lsp: A link to a school profile on education.com.
    • lsc: A link to a search results page on education.com for the given city and state.
  • XSD Schema
  • examples
    • Get branding data for school having nces_id=450231000564
      in rest format,
      http://api.education.com/service/service.php?f=gbd&key=4c338ac1ee0d6&sn=sf&nces_id=450231000564&v=2
      in json format, in php format
    • response: in json format, in php format, in xml format

system.multiCall

  • Behavior:
    • Allows one or more web service functions to be executed in one request. Responses are returned in the order in which they were requested.
  • Parameters:
    • required:
      • f = system.multiCall
      • methods = an array of web service function call parameters
    • optional:
      • fid = a unique identifier for the function being called. This is returned back to the caller and may be used to identify the results of a web service function.
  • Returns: an array of zero or more:
    • methodName: The name of the web service function.
    • methodId: The unique identifier for the function. (set by fid
    • methodResponse: The response of the function.
  • examples
    • Call web service functions 'gbd' and 'getVersion' at the same time.
      in rest format,
      http://api.education.com/service/service.php?f=system.multiCall&methods%5B0%5D%5Bf%5D=gbd&methods%5B0%5D%5Bfid%5D=F1&methods%5B1%5D%5Bf%5D=getVersion&methods%5B1%5D%5Bfid%5D=F2
      in json format, in php format
    • response: in json format, in php format, in xml format


WebService Error Responses

If a method fails, it may return any one of the following fault codes along with a fault message:
  • faultCode: 1 faultString: an unknown error ocurred
  • faultCode: 2 faultString: invalid parameters
  • faultCode: 3 faultString: invalid api key
  • faultCode: 4 faultString: invalid hostname
  • faultCode: 5 faultString: usage limits exceeded
  • faultCode: 6 faultString: invalid function
  • faultCode: 7 faultString: api key is disabled
  • XSD Schema
example: in json format, in php format, in xml format

If you have any questions about the SchoolFinder Web Service, please contact us at api-support@education.com.