.. |boolean| replace:: (supply a ``0`` for "no" and ``1`` for "yes")
.. |---| unicode:: U+2014 .. em dash
	:trim:
.. |->| unicode:: U+2192 .. to
.. |=>| unicode:: U+27FA .. implies
.. |...| unicode:: U+2026 .. ldots
	:trim:
.. |copy| unicode:: U+00A9 .. copy
.. |nc| replace:: Nearby Colleges
.. |unitid| replace:: Endpoint must be a school's unitid (a 6-digit integer).
.. role:: red
.. role:: green
.. role:: mark
.. role:: message
.. role:: strike

.. meta::
        :description: The Nearby Colleges API allows developers to access high-quality, reliable data on 4-year colleges and universities in the United States and territories. It's generally free, fast, and well-structured.


|nc| API specification
----------------------

The |nc| 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 <https://www.jacobinmag.com/2015/03/education-technology-gates-erickson/>`__ 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 available again, as of 2017 November 5 UTC.


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. :red:`Required`
``limit``
        Limit of the number of schools that appear in the response. Ranked alphabetically after matching ``q``. :red:`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``

.. include:: examples/autocomplete.json
	:code: javascript
	:number-lines:


Alias
=====

Provides an official school name and unitid given an alias (recognised acronym of the school or abbreviation).

``q``
        The alias of the school. :red:`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``

.. include:: examples/alias.json
	:code: javascript
	:number-lines:


Everything
==========

Single response with all remaining non-search sections below.

``/<unitid>``
        |unitid|

|...|

**GET** ``/everything/200059``

`Click for response <_static/everything.json>`__.


Schools
=======

Various pieces of general school information (that don't fit into the more specific categories below).


``/<unitid>``
    |unitid|

|...|

**GET** ``/schools/152248`` 

.. include:: examples/school.json
	:code: javascript
	:number-lines:


Tests
=====

Information on 25th and 75th percentile ACT and SAT scores for first-time, full-time undergraduates granted admission to the school.

``/<unitid>``
    |unitid|

|...|

**GET** ``/tests/243780``

.. include:: examples/tests.json
	:code: javascript
	:number-lines:


Enrollment
==========

Enrollment information.

``/<unitid>``
    |unitid|

|...|

**GET** ``/enrollment/243780``

.. include:: examples/enrollment.json
	:code: javascript
	:number-lines:

Admissions
==========

Admissions information. All student-body statistics are for first-time, full-time undergraduates.

``/<unitid>``
    |unitid|

|...|

**GET** ``/admissions/243780``

.. include:: examples/admissions.json
	:code: javascript
	:number-lines:


Locations
=========

Websites, contact information, and physical location of school.

``/<unitid>``
    |unitid|

|...|

**GET** ``/locations/200059``

.. include:: examples/locations.json
	:code: javascript
	:number-lines:

Search
------

.. note::

  An API key, which is generated automatically by completing the form below, is necessary but not sufficient for both search endpoints. Specifically, radius-search access is granted on a case-by-case basis. If you're interested in either search endpoint, please complete the form.


.. raw:: html
  :file: form.html

---- 

#. 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 |boolean|                 |
+------------------------------+-----------------------------------------------+
| ``historicallyBlack``        | historically black school |boolean|           |
+------------------------------+-----------------------------------------------+
| ``offersMasters``            | masters degrees offered |boolean|             |
+------------------------------+-----------------------------------------------+
| ``offersPhD``                | PhD degrees offered |boolean|                 |
+------------------------------+-----------------------------------------------+
| ``freshmanRequiredOnCampus`` | freshman required to live on campus |boolean| |
+------------------------------+-----------------------------------------------+
| ``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). :red:`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``. :green:`Optional`
``ascending``
  Sorts in ascending order of ``rankby`` (default is descending). This endpoint will not apply to a radius-search. :green:`Optional`
``key``
	Your API key. :red:`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``

.. include:: examples/search.json
	:code: javascript
	:number-lines:


Radius search
=============

.. note::

	Access to radius-search is restricted. If your service requires such data, specify you need radius search in the form `above <#search>`__.

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). :green:`Optional`.
``lat``
	Latitude of the origin. :red:`Required`
``lng``
	Longitude of the origin. :red:`Required`
``r``
	Distance, **in miles** from the origin. :red:`Required`
``all_loc``
  Include all physical location information for each school in the response. :green:`Optional`
``key``
	Your API key. :red:`Required`

|...|

``api/rsearch?key=API_KEY&filter=tests.sat75:>2000,tests.sat75:<2400&r=412&lat=39.310784431180664&lng=-87.35107748652342``


.. include:: examples/rsearch.json
	:code: javascript
	:number-lines:


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``)

.. include:: examples/error.json
	:code: javascript
	:number-lines:

or

**GET** ``/locations/12345`` (unitid is not 6 characters)

.. include:: examples/error-2.json
	:code: javascript
	:number-lines:

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 |nc|, LLC, 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 |nc|, LLC you verify your comprehension and acknowledgment of these terms.

About
-----

You may contribute to this documentation by `making a pull-request <https://framagit.org/gdyer/NC-docs>`__. Rest assured, we don't profit off of any work you do (no one pays for API use). The API and documentation are maintained by `2PITAU`_.

.. _Greenberg Educational Group: http://greenbergeducationalgroup.com
.. _2PITAU: https://2pitau.org
.. _disclaimer: https://nearbycolleges.info/api_disclaimer