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. When autocomplete is present, limit is supported, which will perform the same role as above. You may include loose to remove the strict matching (see the autocomplete API’s definition). (Note that you likely don’t want to include loose). Any or no value for loose and autocomplete 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

Click for response.

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). Required

rankby

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. Optional

ascending

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.