Education.com Web Services

Education.com provides access to some of its data via a web service API.
Any use of this API is subject to the Education.com SchoolFinder Web Service Terms of Service.


  • 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://www.education.com/service/service.php?f=schoolSearch&sn=sf&key=602bbfcf3104c2297cac7f1e9c786268&zip=94063


      In this example, the API method schoolSearch is being executed with service name sn = sf (SchoolFinder), and an API key = '602bbfcf3104c2297cac7f1e9c786268' (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.
  • Supported request formats

    • REST
    • XML-RPC
    • JSON
    • PHP
  • Supported response formats

    • XML-RPC
    • 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 placed on clients of the web service. The limits may vary for each client and if you would like to increase your usage limits then contact us at api-support@education.com
    • 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.


SchoolFinder Web Service API method reference

the following methods allow access to our database of school information.


schoolSearch

  • Behavior:
    • Returns an array of school profiles that match the search parameters.
  • Parameters:
    • required:
      • sn = sf
      • f = schoolSearch
      • key = (your API key)
    • 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
      • 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. If Minresult is used with zipcode,please note that “distance” should not be set.
  • Returns: an array of zero or more:
    • schoolname
    • zip
    • city
    • districtid
    • districtleaid
    • address
    • AYPresult
    • APIScore
    • distance
    • enrollment
    • gradesserved
    • latitude
    • longitude
    • phonenumber
    • schooldistrictname
    • schooltype
    • state
    • studentteacherratio
    • website
    • nces_id
    • url - The URL to the Education.com profile page of the school.
    • schoolid
  • XSD Schema
  • examples
    • Search for school by zipcode:
      in rest format,
      http://www.education.com/service/service.php?f=schoolSearch&key=602bbfcf3104c2297cac7f1e9c786268&zip=29601&sn=sf&address=vardry
      in xmlrpc format, in json format, in php format
    • response: in xmlrpc format, in json format, in php format, in xml format

getStudentDiversity Version 1.0 , 2.0

  • Version: 1.0
  • Behavior:
    • Returns Gender and ethnicity statistics for a single school.
  • Parameters:
    • sn = sf
    • f=getStudentDiversity
    • key= (your API key)
    • schoolid= The id of the school.
    • nces_id= The nces id of the school.
  • Returns: an array
    • gender
    • ethnicity
  • XSD Schema
  • examples
    • Get student diversity information for school where nces_id=450231000564
      http://www.education.com/service/service.php?f=getStudentDiversity&key=602bbfcf3104c2297cac7f1e9c786268&nces_id=450231000564&sn=sf
    • response: in xmlrpc format, in json format, in php format

getTestScores

  • 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
      • value
      • year
      • max_score
      • description
  • XSD Schema
  • examples
    • Get test score information for school where nces_id=450231000564
      http://www.education.com/service/service.php?f=getTestScores&key=602bbfcf3104c2297cac7f1e9c786268&nces_id=450231000564&sn=sf
    • response: in xmlrpc format, in json format, in php format in xml format

getTeacherStats

  • 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://www.education.com/service/service.php?f=getTeacherStats&key=602bbfcf3104c2297cac7f1e9c786268&nces_id=450231000564&districtleaid=4502310&sn=sf
    • response: in xmlrpc format, in json format, in php format

getStudentStats Version 1.0 , 2.0

  • Version: 1.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
  • Returns: an array of zero or more:
    • school
      • stat_type
      • stat_name
      • year
      • value
      • total
    • city
      • stat_type
      • stat_name
      • year
      • value
      • total
      • average
    • district
      • stat_type
      • stat_name
      • year
      • value
      • total
      • average
  • XSD Schema
  • examples
    • Get student statistics for school where nces_id=450231000564 and city='Greenville' and state='SC'
      http://www.education.com/service/service.php?f=getStudentStats&key=602bbfcf3104c2297cac7f1e9c786268&nces_id=450231000564&districtleaid=4502310&sn=sf&city=Greenville&state=SC
    • response: in xmlrpc format, in json format, in php format

getReviews

  • 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://www.education.com/service/service.php?f=getReviews&key=602bbfcf3104c2297cac7f1e9c786268&schoolid=25381&sn=sf
    • response: in xmlrpc format, in json format, in php format

numberOf

  • 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://www.education.com/service/service.php?f=numberOf&key=602bbfcf3104c2297cac7f1e9c786268&city=Greenville&sn=sf&state=SC
      in xmlrpc format, in json format, in php format
    • response: in xmlrpc format, in json format, in php format, in xml format

districtSearch

  • 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 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 is in.
      • zip: The zipcode that the district is in.
  • 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://www.education.com/service/service.php?f=districtSearch&key=602bbfcf3104c2297cac7f1e9c786268&city=Greenville&sn=sf&state=SC
      in xmlrpc format, in json format, in php format
    • response: in xmlrpc format, in json format, in php format, in xml format

gbd

  • Behavior:
    • Returns links back to Education.com.
  • 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.
    • lsr: A link to the schools 'review' page on education.com.
    • lsrs: A link to the schoolfinder 'reviews' landing page 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://www.education.com/service/service.php?f=gbd&key=602bbfcf3104c2297cac7f1e9c786268&sn=sf&nces_id=450231000564
      in xmlrpc format, in json format, in php format
    • response: in xmlrpc format, 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://www.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 xmlrpc format, in json format, in php format
    • response: in xmlrpc format, 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 xmlrpc format, 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.