@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api SchoolDigger API V1
@base https://api.schooldigger.com
@version v1
@auth ApiKey appKey in query
@common_fields {appID: any # Your API app id, appKey: any # Your API app key}
@endpoints 6
@toc districts(2), rankings(2), schools(2)

@group districts
@endpoint GET /v1/districts
@desc Returns a list of districts
@required {st: any # Two character state (e.g. 'CA') - required}
@optional {q: any # Search term - note: will match district name or city (optional), city: any # Search for districts in this city (optional), zip: any # Search for districts in this 5-digit zip code (optional), nearLatitude: any # Search for districts within (distanceMiles) of (nearLatitude)/(nearLongitude) (e.g. 44.982560) (optional) (Pro, Enterprise API levels only. Enterprise API level will flag districts that include lat/long in its attendance boundary.), nearLongitude: any # Search for districts within (distanceMiles) of (nearLatitude)/(nearLongitude) (e.g. -124.289185) (optional) (Pro, Enterprise API levels only. Enterprise API level will flag districts that include lat/long in its attendance boundary.), boundaryAddress: any # Full U.S. address: flag returned districts that include this address in its attendance boundary. Example: '123 Main St. AnyTown CA 90001' (optional) (Enterprise API level only), distanceMiles: any # Search for districts within (distanceMiles) of (nearLatitude)/(nearLongitude) (Default 50 miles) (optional) (Pro, Enterprise API levels only), isInBoundaryOnly: any # Return only the districts that include given location (nearLatitude/nearLongitude) or (boundaryAddress) in its attendance boundary (Enterprise API level only), boxLatitudeNW: any # Search for districts within a 'box' defined by (BoxLatitudeNW/BoxLongitudeNW) to (BoxLongitudeSE/BoxLatitudeSE) (optional), boxLongitudeNW: any # Search for districts within a 'box' defined by (BoxLatitudeNW/BoxLongitudeNW) to (BoxLongitudeSE/BoxLatitudeSE) (optional), boxLatitudeSE: any # Search for districts within a 'box' defined by (BoxLatitudeNW/BoxLongitudeNW) to (BoxLongitudeSE/BoxLatitudeSE) (optional), boxLongitudeSE: any # Search for districts within a 'box' defined by (BoxLatitudeNW/BoxLongitudeNW) to (BoxLongitudeSE/BoxLatitudeSE) (optional), page: any # Page number to retrieve (optional, default: 1), perPage: any # Number of districts to retrieve on a page (50 max) (optional, default: 10), sortBy: any # Sort list. Values are: districtname, distance, rank. For descending order, precede with '-' i.e. -districtname (optional, default: districtname), includeUnrankedDistrictsInRankSort: any # If sortBy is 'rank', this boolean determines if districts with no rank are included in the result (optional, default: false)}
@returns(200) OK

@endpoint GET /v1/districts/{id}
@desc Returns a detailed record for one district
@required {id: any # The 7 digit District ID (e.g. 0642150)}
@returns(200) OK

@endgroup

@group rankings
@endpoint GET /v1/rankings/schools/{st}
@desc Returns a SchoolDigger school ranking list
@required {st: any # Two character state (e.g. 'CA')}
@optional {year: any # The ranking year (leave blank for most recent year), level: any # Level of ranking: 'Elementary', 'Middle', or 'High', page: any # Page number to retrieve (optional, default: 1), perPage: any # Number of schools to retrieve on a page (50 max) (optional, default: 10)}
@returns(200) OK

@endpoint GET /v1/rankings/districts/{st}
@desc Returns a SchoolDigger district ranking list
@required {st: any # Two character state (e.g. 'CA')}
@optional {year: any # The ranking year (leave blank for most recent year), page: any # Page number to retrieve (optional, default: 1), perPage: any # Number of districts to retrieve on a page (50 max) (optional, default: 10)}
@returns(200) OK

@endgroup

@group schools
@endpoint GET /v1/schools
@desc Returns a list of schools
@required {st: any # Two character state (e.g. 'CA') - required}
@optional {q: any # Search term - note: will match school name or city (optional), qSearchSchoolNameOnly: any # For parameter 'q', only search school names instead of school and city (optional), districtID: any # Search for schools within this district (7 digit district id) (optional), level: any # Search for schools at this level. Valid values: 'Elementary', 'Middle', 'High', 'Alt', 'Public', 'Private' (optional). 'Public' returns all Elementary, Middle, High and Alternative schools, city: any # Search for schools in this city (optional), zip: any # Search for schools in this 5-digit zip code (optional), isMagnet: any # True = return only magnet schools, False = return only non-magnet schools (optional) (Pro, Enterprise API levels only), isCharter: any # True = return only charter schools, False = return only non-charter schools (optional) (Pro, Enterprise API levels only), isVirtual: any # True = return only virtual schools, False = return only non-virtual schools (optional) (Pro, Enterprise API levels only), isTitleI: any # True = return only Title I schools, False = return only non-Title I schools (optional) (Pro, Enterprise API levels only), isTitleISchoolwide: any # True = return only Title I school-wide schools, False = return only non-Title I school-wide schools (optional) (Pro, Enterprise API levels only), nearLatitude: any # Search for schools within (distanceMiles) of (nearLatitude)/(nearLongitude) (e.g. 44.982560) (optional) (Pro, Enterprise API levels only. Enterprise API level will flag schools that include lat/long in its attendance boundary.), nearLongitude: any # Search for schools within (distanceMiles) of (nearLatitude)/(nearLongitude) (e.g. -124.289185) (optional) (Pro, Enterprise API levels only. Enterprise API level will flag schools that include lat/long in its attendance boundary.), boundaryAddress: any # Full U.S. address: flag returned schools that include this address in its attendance boundary. Example: '123 Main St. AnyTown CA 90001' (optional) (Enterprise API level only) IMPORTANT NOTE: If you have the lat/long of the address, use nearLatitude and nearLongitude instead for much faster response times, distanceMiles: any # Search for schools within (distanceMiles) of (nearLatitude)/(nearLongitude) (Default 5 miles) (optional) (Pro, Enterprise API levels only), isInBoundaryOnly: any # Return only the schools that include given location (nearLatitude/nearLongitude) or (boundaryAddress) in its attendance boundary (Enterprise API level only), boxLatitudeNW: any # Search for schools within a 'box' defined by (boxLatitudeNW/boxLongitudeNW) to (boxLongitudeSE/boxLatitudeSE) (optional), boxLongitudeNW: any # Search for schools within a 'box' defined by (boxLatitudeNW/boxLongitudeNW) to (boxLongitudeSE/boxLatitudeSE) (optional), boxLatitudeSE: any # Search for schools within a 'box' defined by (boxLatitudeNW/boxLongitudeNW) to (boxLongitudeSE/boxLatitudeSE) (optional), boxLongitudeSE: any # Search for schools within a 'box' defined by (boxLatitudeNW/boxLongitudeNW) to (boxLongitudeSE/boxLatitudeSE) (optional), page: any # Page number to retrieve (optional, default: 1), perPage: any # Number of schools to retrieve on a page (50 max) (optional, default: 10), sortBy: any # Sort list. Values are: schoolname, distance, rank. For descending order, precede with '-' i.e. -schoolname (optional, default: schoolname), includeUnrankedSchoolsInRankSort: any # If sortBy is 'rank', this boolean determines if schools with no rank are included in the result (optional, default: false)}
@returns(200) OK

@endpoint GET /v1/schools/{id}
@desc Returns a detailed record for one school
@required {id: any # The 12 digit School ID (e.g. 064215006903)}
@returns(200) OK

@endgroup

@end