Nearby Colleges API specification¶
The Nearby Colleges RESTful API is free, with request-limits for more computationally-intensive endpoints.
All our data are exclusive to 4-year schools within the US and its territories. This turns out to be 2885 schools.
Right now, we’re using NCES IPEDS 2013–2014 final release data. Visit them for more detailed variable descriptions.
Before you begin your project (presumably in educational technology), we recommend reading this essay for some perspective.
Important
Prefix all routes with “https://nearbycolleges.info/api”. Non-“https” requests will be 301-redirected to their encrypted equivalent.
Attention
Search and radius-search are suspended as of 17 July 2020. We recommend simply downloading the data from IPEDs and using the Haversine forumla to calculate the distance between two latitude and longitude pairs.
Non-search¶
For all non-search endpoints besides autocomplete
and alias
, schools are referenced by unitids, unique identifiers assigned to each college by the US Dept. of Education. Both autocomplete
and alias
attempt to provide you a means of mapping a school’s name or alias → its unitid. Use the unitid obtained from autocomplete
or alias
to get more data about a school.
Autocomplete¶
Suggests the name of a school as a user types.
q
- The query; a full or partial name of a school. Required
limit
- Limit of the number of schools that appear in the response. Ranked alphabetically after matching
q
. Required strict
- Assume the user is typing from the very beginning of a school’s name and not at some other point. Any or no value will suffice, like
/autocomplete?q=uni&strict
.
…
GET /autocomplete?q=university%20of%20i&limit=3
1 { 2 "ok": 1, 3 "result": [ 4 { 5 "name": "University of Idaho", 6 "state": "Idaho", 7 "unitid": 142285 8 }, 9 { 10 "name": "University of Illinois at Chicago", 11 "state": "Illinois", 12 "unitid": 145600 13 }, 14 { 15 "name": "University of Illinois at Urbana-Champaign", 16 "state": "Illinois", 17 "unitid": 145637 18 } 19 ] 20 }
Alias¶
Provides an official school name and unitid given an alias (recognised acronym of the school or abbreviation).
q
- The alias of the school. Required
autocomplete
- Replicate the
strict
version of autocomplete, but now include aliases. Whenautocomplete
is present,limit
is supported, which will perform the same role as above. You may includeloose
to remove thestrict
matching (see the autocomplete API’s definition). (Note that you likely don’t want to includeloose
). Any or no value forloose
andautocomplete
will suffice, like/alias?q=mit&autocomplete
…
GET /alias?q=uiuc
1 { 2 "ok": 1, 3 "result": [ 4 { 5 "alias": "UIUC", 6 "name": "University of Illinois at Urbana-Champaign", 7 "state": "Illinois", 8 "unitid": 145637 9 } 10 ] 11 }
Everything¶
Single response with all remaining non-search sections below.
/<unitid>
- Endpoint must be a school’s unitid (a 6-digit integer).
…
GET /everything/200059
Schools¶
Various pieces of general school information (that don’t fit into the more specific categories below).
/<unitid>
- Endpoint must be a school’s unitid (a 6-digit integer).
…
GET /schools/152248
1 { 2 "ok": 1, 3 "result": { 4 "calendarSystem": "Semester", 5 "control": "Public", 6 "fourYearGradRate": 9, 7 "freshmanRequiredOnCampus": 0, 8 "historicallyBlack": 0, 9 "img": "http://www.sollitt.com/images/uploads/project-images/Purdue5.jpg", 10 "img_src": "www.sollitt.com", 11 "img_src_page": "http://www.sollitt.com/index.php/structure/project_details/purdue_university_calumet_campus", 12 "instateTuition": 5887, 13 "irregular": 0, 14 "isReligious": 0, 15 "name": "Purdue University-Calumet Campus", 16 "offersMasters": 1, 17 "offersPhD": 0, 18 "outstateTuition": 14109, 19 "religion": "Not applicable", 20 "sixYearGradRate": 30, 21 "studentFacultyRatio": 20, 22 "ts": "Sun, 09 Aug 2015 23:21:16 GMT", 23 "unitid": 152248, 24 "year": 2013 25 } 26 }
Tests¶
Information on 25th and 75th percentile ACT and SAT scores for first-time, full-time undergraduates granted admission to the school.
/<unitid>
- Endpoint must be a school’s unitid (a 6-digit integer).
…
GET /tests/243780
1 { 2 "ok": 1, 3 "result": { 4 "act25": 24, 5 "act25English": 23, 6 "act25Math": 25, 7 "act25Writing": null, 8 "act75": 30, 9 "act75English": 31, 10 "act75Math": 32, 11 "act75Writing": null, 12 "percentUsedACT": 54, 13 "percentUsedSAT": 73, 14 "sat25": 1600, 15 "sat25English": null, 16 "sat25Math": 560, 17 "sat25Reading": 520, 18 "sat25Writing": 520, 19 "sat75": null, 20 "sat75English": null, 21 "sat75Math": 690, 22 "sat75Reading": 630, 23 "sat75Writing": 630, 24 "unitid": 243780 25 } 26 }
Enrollment¶
Enrollment information.
/<unitid>
- Endpoint must be a school’s unitid (a 6-digit integer).
…
GET /enrollment/243780
1 { 2 "ok": 1, 3 "result": { 4 "fulltimeGrad": 6212, 5 "fulltimeTotal": 34871, 6 "fulltimeUndergrad": 28659, 7 "gradTotal": 9348, 8 "percentAmericanIndianOrAlaskaNative": 0, 9 "percentAsian": 5, 10 "percentBlack": 3, 11 "percentLatino": 4, 12 "percentPacificIslander": 0, 13 "percentUndergradAmericanIndianOrAlaskaNative": 0, 14 "percentUndergradAsian": 5, 15 "percentUndergradBlack": 3, 16 "percentUndergradForeign": 15, 17 "percentUndergradInstate": 55, 18 "percentUndergradLatino": 4, 19 "percentUndergradOutstate": 28, 20 "percentUndergradPacificIslander": 0, 21 "percentUndergradWhite": 68, 22 "percentUndergradWomen": 42, 23 "percentWhite": 63, 24 "percentWomen": 42, 25 "retentionRate": 91, 26 "total": 39794, 27 "undergradTotal": 30446, 28 "unitid": 243780 29 } 30 }
Admissions¶
Admissions information. All student-body statistics are for first-time, full-time undergraduates.
/<unitid>
- Endpoint must be a school’s unitid (a 6-digit integer).
…
GET /admissions/243780
1 { 2 "ok": 1, 3 "result": { 4 "TOEFL": "Required", 5 "acceptanceRate": 60, 6 "acceptanceRateFemale": 64, 7 "acceptanceRateMale": 58, 8 "applicationFee": 60, 9 "averageAmountOfFA": "", 10 "numberApps": 31083, 11 "numberFemaleApps": 18258, 12 "numberMaleApps": 12825, 13 "percentOnFA": 50, 14 "secondaryGPA": "Required", 15 "secondarySchoolRecord": "Required", 16 "teacherRecommendations": "Neither required nor recommended", 17 "testScores": "Required", 18 "unitid": 243780, 19 "yield": 34, 20 "yieldFemale": 34, 21 "yieldMale": 35 22 } 23 }
Locations¶
Websites, contact information, and physical location of school.
/<unitid>
- Endpoint must be a school’s unitid (a 6-digit integer).
…
GET /locations/200059
1 { 2 "ok": 1, 3 "result": { 4 "admissionsWebsite": "www.dickinsonstate.com", 5 "city": "Dickinson", 6 "classification": "Small four-year, primarily residential", 7 "faWebsite": "www.dickinsonstate.com", 8 "fax": "7014832409", 9 "lat": 46.882675, 10 "lng": -102.800514, 11 "name": "Dickinson State University", 12 "netPriceWebsite": "financialaidcalculator.dickinsonstate.edu/", 13 "onlineApplication": "www.dickinsonstate.com", 14 "phone": "7014832507", 15 "state": "North Dakota", 16 "streetAddress": "291 Campus Drive", 17 "unitid": 200059, 18 "website": "www.dickinsonstate.com", 19 "zipCode": "58601-4896" 20 } 21 }
Search¶
- If you lose your key, please create a new one.
- 1000 requests / day are provided gratis. Please contact admin@nearbycolleges.info if you find this insufficient. Depending on total traffic, we may be able to increase your limit for free.
- You may check your usage by visiting
https://nearbycolleges.info/usage?key=API_KEY
. - You shouldn’t use your key for non-search queries (your request-count won’t change, although this behaviour is untested).
Available variables¶
Note that the {category}
is at the top of each group (the prefix).
Tests¶
Prefix variables with tests.
variable | description |
---|---|
percentUsedSAT |
% admitted that used SAT |
percentUsedACT |
% admitted that used ACT |
sat75 |
SAT 75th percentile |
sat25 |
SAT 25th percentile |
sat75Reading |
SAT 75th percentile reading |
sat25Reading |
SAT 25th percentile reading |
sat75Writing |
SAT 75th percentile writing |
sat25Writing |
SAT 25th percentile writing |
sat75Math |
SAT 75th percentile math |
sat25Math |
SAT 25th percentile math |
act75 |
ACT 75th percentile |
act25 |
ACT 25th percentile |
act75English |
ACT 75th percentile English |
act25English |
ACT 25th percentile English |
act75Math |
ACT 75th percentile math |
act25Math |
ACT 25th percentile math |
act75Writing |
ACT 75th percentile writing |
act25Writing |
ACT 25th percentile writing |
Enrollment¶
Prefix variables with enrollment.
variable | description |
---|---|
retentionRate |
retention rate |
fulltimeTotal |
fulltime student population |
undergradTotal |
undergraduate population |
fulltimeUndergrad |
full-time undergraduate population |
gradTotal |
graduate student population |
fulltimeGrad |
full-time graduate student population |
percentUndergradWomen |
% undergraduate women |
percentUndergradAmericanIndianOrAlaskaNative |
% undergraduate American Indian or Alaska native |
percentUndergradAsian |
% undergraduate Asian |
percentUndergradBlack |
% undergraduate black |
percentUndergradLatino |
% undergraduate Latino |
percentUndergradPacificIslander |
% undergraduate Pacific Islander |
percentUndergradWhite |
% undergraduate white |
percentWomen |
% total women |
percentAmericanIndianOrAlaskaNative |
% total American Indian or Alaska native |
percentAsian |
% total Asian |
percentBlack |
% total black |
percentLatino |
% total Latino |
percentPacificIslander |
% total Pacific Islander |
percentWhite |
% total white |
percentUndergradInstate |
% undergraduate in-state |
percentUndergradOutstate |
% undergraduate out-of-state |
percentUndergradForeign |
% undergraduate foreign |
Admissions¶
Prefix variables with admissions.
variable | description |
---|---|
applicationFee |
application fee |
numberApps |
number of applications |
numberFemaleApps |
number of female applications |
acceptanceRate |
acceptance rate |
acceptanceRateMale |
acceptance rate male |
acceptanceRateFemale |
acceptance rate female |
yield |
yield (% accepted who attended the school) |
yieldFemale |
yield female |
percentOnFA |
% on financial aid |
averageAmountOfFA |
average amount of financial aid |
School¶
Prefix variables with school.
variable | description |
---|---|
isReligious |
school is religious (supply a 0 for “no” and 1 for “yes”) |
historicallyBlack |
historically black school (supply a 0 for “no” and 1 for “yes”) |
offersMasters |
masters degrees offered (supply a 0 for “no” and 1 for “yes”) |
offersPhD |
PhD degrees offered (supply a 0 for “no” and 1 for “yes”) |
freshmanRequiredOnCampus |
freshman required to live on campus (supply a 0 for “no” and 1 for “yes”) |
instateTuition |
in-state tuition |
outstateTuition |
out-of-state tuition |
fourYearGradRate |
4-year graduaton rate |
sixYearGradRate |
6-year graduation rate |
studentFacultyRatio |
student-faculty ratio |
img |
a URL to an image of the school |
img_src |
the source of img |
img_src_page |
URL to the page on which img lives |
Vanilla search¶
Find schools matching filters regardless of geography; that is, ranked by whatever you want.
api/search
filter
The filter or filters to be applied.
Syntax is
{category}.{attribute}:{>|=|<}{value}[, other filters]
.For instance, all schools where the 75th percentile of accepted students had an ACT score greater or equal to 25 would be
?filter=tests.act75:>25
. Note that inequalities are all inclusive. Please use the same variable more than once to define an interval (other than to the minimum or maximum). Requiredrankby
The variable by which to rank the schools matching
filter
.Syntax is
{category}.{attribute}
.For instance, ranking our previous query by female student body, we could do
?filter=tests.act75:>25&rankby=enrollment.percentWomen
. Optionalascending
- Sorts in ascending order of
rankby
(default is descending). This endpoint will not apply to a radius-search. Optional key
- Your API key. Required
Note that using a variable in filter
or rankby
will automatically include that variable for each school in the response. We also include an irregular
attribute, which, like the non-search endpoints, filters schools that don’t post basic pieces of information (usually online programs and system offices for state schools). As soon as a single filter or rank is applied, all irregular schools will automatically be removed.
…
/api/search?key=API_KEY&filter=admissions.numberApps:>39566,admissions.numberApps:<72677&rankby=tests.act25
1 { 2 "ok": 1, 3 "result": [ 4 { 5 "act25": 30, 6 "irregular": 0, 7 "name": "Cornell University", 8 "numberapps": 39999, 9 "unitid": 190415 10 }, 11 { 12 "act25": 30, 13 "irregular": 0, 14 "name": "Northeastern University", 15 "numberapps": 47364, 16 "unitid": 167358 17 }, 18 { 19 "act25": 29, 20 "irregular": 0, 21 "name": "University of Southern California", 22 "numberapps": 47358, 23 "unitid": 123961 24 }, 25 { 26 "act25": 28, 27 "irregular": 0, 28 "name": "New York University", 29 "numberapps": 57845, 30 "unitid": 193900 31 }, 32 { 33 "act25": 28, 34 "irregular": 0, 35 "name": "University of Michigan-Ann Arbor", 36 "numberapps": 46813, 37 "unitid": 170976 38 }, 39 { 40 "act25": 27, 41 "irregular": 0, 42 "name": "University of California-Berkeley", 43 "numberapps": 61717, 44 "unitid": 110635 45 }, 46 { 47 "act25": 26, 48 "irregular": 0, 49 "name": "Boston University", 50 "numberapps": 44006, 51 "unitid": 164988 52 }, 53 { 54 "act25": 26, 55 "irregular": 0, 56 "name": "University of Minnesota-Twin Cities", 57 "numberapps": 43048, 58 "unitid": 174066 59 }, 60 { 61 "act25": 25, 62 "irregular": 0, 63 "name": "University of California-San Diego", 64 "numberapps": 60832, 65 "unitid": 110680 66 }, 67 { 68 "act25": 25, 69 "irregular": 0, 70 "name": "Pennsylvania State University-Main Campus", 71 "numberapps": 47552, 72 "unitid": 214777 73 }, 74 { 75 "act25": 25, 76 "irregular": 0, 77 "name": "University of California-Los Angeles", 78 "numberapps": 72676, 79 "unitid": 110662 80 }, 81 { 82 "act25": 24, 83 "irregular": 0, 84 "name": "University of California-Santa Barbara", 85 "numberapps": 55258, 86 "unitid": 110705 87 }, 88 { 89 "act25": 24, 90 "irregular": 0, 91 "name": "Drexel University", 92 "numberapps": 43945, 93 "unitid": 212054 94 }, 95 { 96 "act25": 23, 97 "irregular": 0, 98 "name": "University of California-Davis", 99 "numberapps": 49820, 100 "unitid": 110644 101 }, 102 { 103 "act25": 21, 104 "irregular": 0, 105 "name": "University of California-Irvine", 106 "numberapps": 56515, 107 "unitid": 110653 108 }, 109 { 110 "act25": 21, 111 "irregular": 0, 112 "name": "San Diego State University", 113 "numberapps": 51163, 114 "unitid": 122409 115 }, 116 { 117 "act25": 21, 118 "irregular": 0, 119 "name": "St John's University-New York", 120 "numberapps": 51634, 121 "unitid": 195809 122 }, 123 { 124 "act25": 19, 125 "irregular": 0, 126 "name": "Liberty University", 127 "numberapps": 48054, 128 "unitid": 232557 129 }, 130 { 131 "act25": 18, 132 "irregular": 0, 133 "name": "California State University-Long Beach", 134 "numberapps": 55019, 135 "unitid": 110583 136 } 137 ] 138 }
Radius search¶
Note
Access to radius-search is restricted. If your service requires such data, specify you need radius search in the form above.
Find schools within radius r
and matching filter(s) filter
. Automatically ranked by distance from the origin.
filter
The filter or filters to be applied.
Syntax is
{category}.{attribute}:{>|=|<}{value}[, other filters]
.For instance, all schools where the 75th percentile of accepted students had an ACT score greater or equal to 25 would be
?filter=tests.act75:>25
. Note that inequalities are all inclusive. Please use the same variable more than once to define an interval (other than to the minimum or maximum). Optional.lat
- Latitude of the origin. Required
lng
- Longitude of the origin. Required
r
- Distance, in miles from the origin. Required
all_loc
- Include all physical location information for each school in the response. Optional
key
- Your API key. Required
…
api/rsearch?key=API_KEY&filter=tests.sat75:>2000,tests.sat75:<2400&r=412&lat=39.310784431180664&lng=-87.35107748652342
1 { 2 "ok": 1, 3 "result": { 4 "len": 20, 5 "schools": [ 6 { 7 "distance": 72.28542818736818, 8 "irregular": 0, 9 "lat": 40.108864, 10 "lng": -88.230309, 11 "name": "University of Illinois at Urbana-Champaign", 12 "sat75": 2120, 13 "unitid": 145637 14 }, 15 { 16 "distance": 165.47643893183442, 17 "irregular": 0, 18 "lat": 38.648125, 19 "lng": -90.311638, 20 "name": "Washington University in St Louis", 21 "sat75": 2320, 22 "unitid": 179867 23 }, 24 { 25 "distance": 171.75292240071025, 26 "irregular": 0, 27 "lat": 41.789169, 28 "lng": -87.601196, 29 "name": "University of Chicago", 30 "sat75": 2370, 31 "unitid": 144050 32 }, 33 { 34 "distance": 174.9404071926339, 35 "irregular": 0, 36 "lat": 41.833801, 37 "lng": -87.628349, 38 "name": "Illinois Institute of Technology", 39 "sat75": 2020, 40 "unitid": 145725 41 }, 42 { 43 "distance": 180.54467094741852, 44 "irregular": 0, 45 "lat": 37.645103, 46 "lng": -84.779175, 47 "name": "Centre College", 48 "sat75": 2020, 49 "unitid": 156408 50 }, 51 { 52 "distance": 181.1742672502631, 53 "irregular": 0, 54 "lat": 41.870941, 55 "lng": -88.096809, 56 "name": "Wheaton College", 57 "sat75": 2130, 58 "unitid": 149781 59 }, 60 { 61 "distance": 190.6023934800931, 62 "irregular": 0, 63 "lat": 42.058376, 64 "lng": -87.673653, 65 "name": "Northwestern University", 66 "sat75": 2320, 67 "unitid": 147767 68 }, 69 { 70 "distance": 220.81307359565585, 71 "irregular": 0, 72 "lat": 36.144428, 73 "lng": -86.804878, 74 "name": "Vanderbilt University", 75 "sat75": 2340, 76 "unitid": 221999 77 }, 78 { 79 "distance": 225.2951323372389, 80 "irregular": 0, 81 "lat": 42.290382, 82 "lng": -85.601318, 83 "name": "Kalamazoo College", 84 "sat75": 2010, 85 "unitid": 170532 86 }, 87 { 88 "distance": 235.80181564666066, 89 "irregular": 0, 90 "lat": 39.99839, 91 "lng": -83.009003, 92 "name": "Ohio State University-Main Campus", 93 "sat75": 2040, 94 "unitid": 204796 95 }, 96 { 97 "distance": 272.82012251663656, 98 "irregular": 0, 99 "lat": 40.374409, 100 "lng": -82.39798, 101 "name": "Kenyon College", 102 "sat75": 2140, 103 "unitid": 203535 104 }, 105 { 106 "distance": 278.52398531658713, 107 "irregular": 0, 108 "lat": 42.276173, 109 "lng": -83.743134, 110 "name": "University of Michigan-Ann Arbor", 111 "sat75": 2210, 112 "unitid": 170976 113 }, 114 { 115 "distance": 281.078788490156, 116 "irregular": 0, 117 "lat": 43.073856, 118 "lng": -89.405357, 119 "name": "University of Wisconsin-Madison", 120 "sat75": 2070, 121 "unitid": 240444 122 }, 123 { 124 "distance": 291.73823783594753, 125 "irregular": 0, 126 "lat": 41.986382, 127 "lng": -91.657532, 128 "name": "Coe College", 129 "sat75": 2023, 130 "unitid": 153144 131 }, 132 { 133 "distance": 302.9994351683764, 134 "irregular": 0, 135 "lat": 41.294739, 136 "lng": -82.221786, 137 "name": "Oberlin College", 138 "sat75": 2185, 139 "unitid": 204501 140 }, 141 { 142 "distance": 323.8550969331245, 143 "irregular": 0, 144 "lat": 35.144531, 145 "lng": -90.049217, 146 "name": "Visible Music College", 147 "sat75": 2010, 148 "unitid": 449764 149 }, 150 { 151 "distance": 337.95582205431606, 152 "irregular": 0, 153 "lat": 41.500813, 154 "lng": -81.605766, 155 "name": "Case Western Reserve University", 156 "sat75": 2190, 157 "unitid": 201645 158 }, 159 { 160 "distance": 399.8225201562464, 161 "irregular": 0, 162 "lat": 40.444504, 163 "lng": -79.954689, 164 "name": "University of Pittsburgh-Pittsburgh Campus", 165 "sat75": 2000, 166 "unitid": 215293 167 }, 168 { 169 "distance": 400.43530059384483, 170 "irregular": 0, 171 "lat": 40.444614, 172 "lng": -79.942917, 173 "name": "Carnegie Mellon University", 174 "sat75": 2280, 175 "unitid": 211440 176 }, 177 { 178 "distance": 401.1656485521643, 179 "irregular": 0, 180 "lat": 35.069759, 181 "lng": -82.370262, 182 "name": "North Greenville University", 183 "sat75": 2000, 184 "unitid": 218441 185 } 186 ] 187 } 188 }
Error Handling¶
If there’s an error with your query, ok
will be 0
, a message
will appear with the description of the error, and a 400 code will be used.
GET /alias?query=uiuc
(should be ?q=uiuc
)
1 { 2 "message": "missing-params", 3 "ok": 0 4 }
or
GET /locations/12345
(unitid is not 6 characters)
1 { 2 "message": "bad-unitid", 3 "ok": 0 4 }
For queries that don’t have an answer, like a well-formatted although non-existent unitid or non-existent alias, empty arrays or null
will be used, depending on the endpoint.
Bugs¶
If you find spelling mistakes or wrong data, contact the university or college associated with that data—they provided it to the Dept. of Education not us! Unless data are swapped (i.e. one school’s information is appearing for another school), we won’t change it. Basically, we’ll only fix problems with the actual API (decreasing latency, 500s, adding data, etc.). Contact us if you see any of those, being sure to provide a link.
We update all schools’ data every two years (occurring next in 2016), as they’re released in this manner.
In the event you find a bug—especially a 500
-coded error—please contact admin@nearbycolleges.info
.
Pending¶
General stability and speed improvements.
Terms¶
- By using this API or any services offered by Nearby Colleges, you implicitly or otherwise agree to our disclaimer.
- Given that this API is free and comes without throttling, there is no uptime guarantee, but it’s been pretty good so far.
- Access to search endpoints, if granted, can be stripped at any time without notice. For any endpoint, your IP can be blacklisted if you’re clearly abusing the service (as defined by the maintainers).
- By making requests to servers owned or operated by Nearby Colleges you verify your comprehension and acknowledgment of these terms.
About¶
No one pays for API use. The API and documentation are maintained by Foreword Development.