People Finder¶
People Finder is a service that searches the SPIRE directory for people affiliated with UMass. This includes students, faculty, and staff, as well as some retirees who have opted to continue being listed.
From People Finder, you can look up any UMass person’s full name and school email address. Additionally, you can look up any student’s majors and degree program. You may also find any faculty or staff member’s title and department affiliation. If they have chosen to list it you may also find their phone number, physical office location, and homepage.
API information¶
The main endpoint for the Person Finder API is
www.umass.edu/peoplefinder/engine/
. This endpoint only takes POST
requests, and will fail with HTTP error 405 on any other request type. It
requires two parameters, and accepts several other optional ones. The first is
q
, your search query. The second is time
, the time of the
request in milliseconds since the UNIX epoch as an integer.
Note
The People Finder source code does reference and use other POST request parameters that aren’t documented here yet. We’ll get around to those someday.
Response format¶
Upon a successful request, the People Finder API will return a JSON response containing information on matching people. The basic format of the response is as follows:
{
'ErrorCode': integer,
'ErrorHint': string,
'ErrorMsg': string,
'OverflowFlag': boolean,
'Results': array
}
The non-error values are 0 for ErrorCode
, and a blank string
(''
) for both ErrorHint
and ErrorMsg
. I’ve not been
able to trigger an error yet so I can’t say for sure what happens when
there’s an error, but I think the field names are pretty self-explanatory.
The OverflowFlag
field indicates whether there are more results for the
query than are listed in the results. Information on a maximum of 13 people per
query can be returned. If the overflow flag is set to true, be aware that there
are more matching results than are being given to you. There is no way to
paginate or get a different set of 13 people with the same query, so if you
didn’t find the person you’re looking for, you’ll just have to try something
else.
Tip
This 13 person limit doesn’t happen with the UMass Directory on SPIRE.
The Results
field contains all the student data you’re looking for. It
is an array of objects representing students. Fields are only included in the
objects if they have values. Possible fields include:
Name
: String of the person’s full name. Not split into first and last names, even though that’s how you enter it into SPIRE.
Affil
: Array of strings detailing the person’s affiliations to the university. It is possible to have more than one. Possible values includeStudent
andEmployee
.
Major
: Array of strings of the person’s majors and degree plans. Strings will usually be in the format ofSUBJECT ([DEGREE])
. Examples includeComputer Science (BS)
orEconomics (PhD)
. This is not always the case. Here are some real major strings I’ve discovered that do not follow the usual format.
U. Without Walls OffCampus (Non Degree)
Part-Time MBA
Professional MBA (NonDeg)
(WTF?!)
Vcard
: The People Finder API also generates VCards! Throw the string in this field onto the end ofwww.umass.edu
and you’ve got yourself a VCard.
Title
: String of the person’s title at UMass. Employees only.
Phone
: Array of strings containing phone numbers. Employees only.
Building
: Array of strings detailing where the person can be found. I’m guessing that users are free to enter whatever they please here, as the level of detail varies greatly between people. Employees only.
Dept
: Array of strings representing the departments the person is affiliated with. Employees only.
URL
: Array of strings of URLs to the person’s personal websites. Employees only.
Reverse engineering tips¶
The information on this page was found from the People Finder’s JavaScript
source code. There’s still
stuff in there that’s not documented on this page yet. Most of the interesting
stuff is happing in the pf_search
function, found at around line
400-ish.