API Documentation

Three APIs are available for anyone to use:

The general search API: http://rpidirectory.appspot.com/api?q=[query][&token=[token]]

The query consists of any number of keywords, separated by spaces. The string returned is JSON formatted as follows:

{ q: <query>, token: <token>, results: [ result1, result2, …] }

The query you searched for is returned to you. Additionally, we support an optional token passed into the API. This token will be returned unmodified. The purpose of the token is to support rapid searches in quick succession, where a search submitted after another might have its results be returned first. There is no guarantee on what order multiple searches are returned in.

Each result is structured as another JSON string:

{ first_name: <first name>, last_name: <last name>, rcsid: <rcsid>, … }

The keys for a result are varied. Different people have different attributes. For example, faculty do not have a “year”, but they have a “title” which most students do not have. The currently (as of 2/22/2013) list is:

'email', 'first_name', 'prefered_name', 'middle_name', 'last_name', 'department', 'email', 'rcsid', 'year', 'major', 'title', 'phone', 'fax', 'homepage', 'office_location', 'campus_mailstop', 'mailing_address', 'directory_id', 'mailing_address_html', 'email_html', 'name', 'type', 'has_pic'

The lastest keys can be found in the “map attributes” object within the models.py file at https://github.com/jewishdan18/RPI-Directory/blob/master/appengine/models.py.

The statistics API: http://rpidirectory.appspot.com/stats_api?q=[query]

[query] can be a name, major, title, or any other field in our database. It will return JSON that returns statistics on your query. For example, a query of daniel returns:

{ "daniel": { "first_name": { "year": { "graduate student": 38, "first-year student": 23, "senior": 25, "junior": 17, "sophomore": 12 }, "first_name": {...}, "last_name": {...}, "title": {...}, "prefered_name": {...}, "major": {...}, "department": {...}, "type": {...} }, "last_name": {...}, "prefered_name": {...} } }

Here we're looking at out of all the daniel's when it's used as a first name (the first node), the breakdown of years. You can see there's so many paths to explore, it's very powerful. To look at the breakdown of majors when daniel is used as a last name you'd use results['daniel']['last_name']['major'].

The suggestion API: http://rpidirectory.appspot.com/suggest_api?q=[query]

[query] can be a name, major, title, or any other field in our database. It will return JSON that uses prefix matching to guess what you most likely the query means. For example, a query of dan returns:

{ "dan": { "danielsen": 1, "daniel": 139, "danison": 1, "daniels": 3, "danika": 1, "dannah": 1, "danner": 1, "danis": 1 } }

So you probably mean daniel is what this API is telling you. Notice they're not sorted in any order.

The image API: http://rpidirectory.appspot.com/picture/

For example, for an rcsid of johnsc12, http://rpidirectory.appspot.com/picture/johnsc12 is the url. The output will be a png image of dimensions 150x150px. If a user has not set a picture, or the rcsid is invalid, a default image will be provided, so you are always guaranteed a picture in response.