For more than 20 years, The Mathematics Genealogy Project, founded by Harry Coonce, has amassed a trove of unique material concerning the academic profession of mathematics in the form of data about mathematicians' advanced degrees (Ph.D., D.Phil., dr. habil., and similar certifications) and those who were thesis advisors. The records for individual mathematicians have been available to search through a web interface. Now, for the first time, significant portions of the collection are available as machine-readable data: several hundred thousand records for you to search, crawl and compute. Sign up and get access today!
Questions/feedback? Write to: Mitch Keller
You will need to authenticate in order to use the Mathematics Genealogy Project API. You may register if you do not already have an account or log in if you have an existing account. If you have forgotten your password, you may request a password reset.
At this time, most API endpoints return JSON results. Two endpoints allow the user to select between JSON or CSV as part of the query. (Note that for most queries, CSV output would not be possible, so do not request that be added as a feature.) If there is sufficient demand, XML output may also be supported in the future. Each section of this documentation includes sample output.
Description: This endpoint returns an HTML page with documentation about the API endpoints.
Request URL: https://mathgenealogy.org:8000/api/v2/MGP/
Request Values: None.
Return Values: An HTML page with documentation about the MGP API endpoints and example output.
Example Request: https://mathgenealogy.org:8000/api/v2/MGP/ gives this documentation page.
Description: This endpoint returns a result that matches the record with the given ID.
Request URL: https://mathgenealogy.org:8000/api/v2/MGP/acad?id=[number]
Request Values: One ID, e.g., 25321
Return Values: A one-entry dictionary in JSON form, giving the value for an MGP_academic. The corresponding properties are given as key:value pairs, where the values may themselves be list of key-value pairs. An academic may have several degrees; a degree may be jointly granted by several institutions; a student may have several advisors for a given degree; the students whom the academic has advised are listed under advisees. Other academics than the one sought in the search query have their MGP IDs appended in brackets.
{
"MGP_academic": {
"ID": "25321",
"family_name": "Frank",
"given_name": "Peter",
"other_names": "",
"student_data": {
"degrees": [
{
"advised by": {
8692: "Derman, Cyrus"
},
"degree_msc": "60",
"degree_type": "Ph.D.",
"degree_year": "1959",
"schools": [
"Columbia University, United States"
],
"thesis_title": "Taboo Generating Functions and Other Topics in Markov Chains"
}
],
"descendants": {
"advisees": {
25357: "Slakter, Malcolm J.",
25358: "Prather, Ronald E.",
25359: "DeGray, Ronald"
},
"descendant_count": 4
}
}
}
}
Example Request: https://mathgenealogy.org:8000/api/v2/MGP/acad?id=25321 gives the result shown above. Note that the way a browser page displays JSON output varies with browser. However, the browser is being sent the ASCII format as in illustrative example above.
Description: This endpoint returns a list of a MGP academics with IDS in a specified range; start stop and, optionally, step size of the integer range required should be specified.
Request URL: https://mathgenealogy.org:8000/api/v2/MGP/acad/range?start=[number]&stop=[number]&step=[number]
Request Value: A value for the start point of the range, for the stop point of the range, and, optionally, for the step size to be used in traversing the range; if omitted the step value is taken to be 1. The number of expected returned values (= (stop - start)/step ) cannot exceed 10,000.
Return Values: A JSON dictionary of
MGP_academic values as illustrated above, up to 10,000 items long. This is not a query that receives a fast answer. Since it is intended for bulk downloads, it does not do browser paging.
Example Request: https://mathgenealogy.org:8000/api/v2/MGP/acad/range?start=1000&stop=1100&step=2
Note that if you use the command line curl, you may have to enclose the URL in quotation marks, as, for instance in curl -i "https://mathgenealogy.org:8000/api/v2/MGP/acad/range?start=1000&stop=1100&step=2"
Description: This endpoint returns the ID numbers all MGP academics. Note this does not return all the details provided with the endpoints documented above. The idea is that you could use this list of IDs to retreive records one-by-one.
Request URL: https://mathgenealogy.org:8000/api/v2/MGP/acad/all/
Request Value: None.
Return Values: A list (in JSON format) of all MGP IDs, part of which is illustrated below.
[ 1, 2, 3, 4, 5, 6, ... ]
Example Request: https://mathgenealogy.org:8000/api/v2/MGP/acad/all
Description: This endpoint returns the ID numbers MGP academics matching a provided query. The search works similarly to the MGP advanced search. Partial string matching is done, but regular expression replacement to match variant UTF-8 characters (using a to search for ä and a, for instance) is not currently implemented in this search. Note this only returns ID numbers, similar to fetching all MGP IDs. The idea is that you could use this list of IDs to retreive records one-by-one.
Request URL: https://mathgenealogy.org:8000/api/v2/MGP/search?family_name=[string]&given_name=[string]&other_names=[string]&school=[string]&year=[int]&thesis=[string]&country=[string]&msc=[char(2)]
Request Values: Family name, given name, other names, school, degree year, thesis title, country, and math subject classification. Supply as few of these as you can. Too restrictive of a search will likely return no results.. Use the school endpoint to get accurate school names for our database. Country names in your query should not contain spaces!
Return Values: A list (in JSON format) of all MGP IDs matching the query.
[[2298], [3045], [3595], [26056],...]
Example Request: https://mathgenealogy.org:8000/api/v2/MGP/acad/search?family_name=Keller&given_name=M
Description: Returns the school (academic institution) with a given internal school ID in the Mathematics Genealogy Project
Request URL: https://mathgenealogy.org:8000/api/v2/MGP/schoolname_from_id/?school_id=[number]
Request Value: A numerical school id.
Return Values: A single answer with a school name and country as below:
School key: school name, country 122: Donetsk University, Ukraine For a full list use the endpoint /api/v2/MGP/schoolnames/, although this may take some time.
Example Request: https://mathgenealogy.org:8000/api/v2/MGP/schoolname_from_id/?school_id=122
Description: Returns names of all degree-granting institutions (schools, universities, etc.) listed in the Mathematics Genealogy Project organized by their IDs. The results are returned as a dictionary with keys the IDs, listed alphabetically (not in numerical order). The Values are the school names including the country. The snippet below shows the start of such a result
Request URL: https://mathgenealogy.org:8000/api/v2/MGP/schoolnames_by_id/
Request Value: No URL parameters required.
Return Values: A JSON dictionary with structure as illustrated in the following example from the start of the list.
{
"10": "Ain Shams University, Egypt",
"100": "Clemson University, United States",
"1000": "University of North Texas, United States",
"1001": "University of Northern Colorado, United States",
"1002": "University of Notre Dame, United States",
"1003": "University of Nottingham, United Kingdom",
"1004": "University of Oregon, United States",
"1005": "Osaka University, Japan",
"1006": "University of Otago, New Zealand",
"1008": "University of Ottawa, Canada",
"1009": "University of Oxford, United Kingdom",
"101": "Coll\u00e8ge de France, France",
"1012": "University of Patras, Greece",
...
"1998": "Abdus Salam School of Mathematical Sciences GC University, Lahore, Pakistan",
"1999": "Research Institute for Symbolic Computation (RISC), Linz, Austria",
"2": "Alexandru Ioan Cuza University of Iasi, Romania",
"20": "All-Russian Scientific Research Institute of Automation (VNIIA), Russia",
"200": "Hochschule f\u00fcr Architektur und Bauwesen Weimar, Germany",
"2000": "Politechnika Lwowska, Poland",
"2001": "Federal Urdu University of Arts, Sciences and Technology, Karachi, Pakistan",
...
}
Example Request: https://mathgenealogy.org:8000/api/v2/MGP/schoolnames_by_country/
Description: Returns all schools as listed in the Mathematics Genealogy Project grouped by country. The results are returned as a dictionary with keys the country names, and the values dictionaries with keys the school names and values the school ids. The following snippet shows the start of such a result
Request URL: https://mathgenealogy.org:8000/api/v2/MGP/schoolnames_by_country/
Request Value: No URL parameters required.
Return Values: A JSON dictionary with structure as illustrated in the following example from the start of the list.
{
"Albania": {
"University of Tirana ": 2058,
"University of Vlora": 2093
},
....
}
Example Request: https://mathgenealogy.org:8000/api/v2/MGP/schoolnames_by_country/
Description:
Returns all siblings (defined as having a common advisor and
degree from the same university) of the mathematician whose ID is
supplied. Report is as a CSV file by default, but the optional
format parameter may be set to json to return a JSON
dictionary with information as above. The window parameter is optional. If supplied, only siblings whose degree year is within window years of the degree of the mathematician whose ID is supplied will be returned.
Request URL: https://mathgenealogy.org:8000/api/v2/MGP/siblings?id=[number]&window=[number]&format=[csv|json]
Request Value: A numerical MGP ID as id and an optional integer window of years as window. If window is not supplied, no year restriction will be imposed. If format is not supplied, CSV will be returned.
Return Values (CSV): CSV results consisting of query_id,id,family_name,given_name,year,msc,school. (The query_id is the one you searched for.) A few lines of sample output are shown below.
query_id,id,family_name,given_name,year,msc,school 263629,263625,Emadzadeh,Amir,2009,93,"University of California, Los Angeles" 263629,263632,Wolfe,Jonathan,2001,93,"University of California, Los Angeles" 263629,263626,Enright,John,2008,93,"University of California, Los Angeles" 263629,263635,Shoarinejad,Kambiz,2001,93,"University of California, Los Angeles" 263629,106839,Lu,Yumao,2006,62,"University of California, Los Angeles" 263629,263636,Chen,Robert,2000,93,"University of California, Los Angeles"
Example Request: https://mathgenealogy.org:8000/api/v2/MGP/siblings?id=263629&window=5
Return Values (JSON): A JSON dictionary (as above) of academic records. A few lines of sampmle output are shown below.
[
{
"MGP_academic": {
"ID": "263625",
"family_name": "Emadzadeh",
"given_name": "Amir",
"mrauth_id": "",
"other_names": "Abbas",
"student_data": {
"degrees": [
{
"advised by": {
"106744": "Speyer, Jason Lee"
},
"degree_msc": "93",
"degree_type": "Ph.D.",
"degree_year": "2009",
"schools": [
"University of California, Los Angeles, United States"
],
"thesis_title": "Relative navigation between two spacecraft using X-ray pulsars"
}
],
"descendants": {
"advisees": [
""
],
"descendant_count": 0
}
}
}
},
{
"MGP_academic": {
"ID": "263632",
"family_name": "Wolfe",
"given_name": "Jonathan",
"mrauth_id": "",
"other_names": "David",
"student_data": {
"degrees": [
{
"advised by": {
"106744": "Speyer, Jason Lee"
},
"degree_msc": "93",
"degree_type": "Ph.D.",
"degree_year": "2001",
"schools": [
"University of California, Los Angeles, United States"
],
"thesis_title": "Nonlinear estimation, detection, and fault-tolerant control"
}
],
"descendants": {
"advisees": [
""
],
"descendant_count": 0
}
}
}
},
...
]
Example Request: https://mathgenealogy.org:8000/api/v2/MGP/siblings?id=263629&window=5&format=json
Note that if you use the command line curl, you may have to enclose the URL in quotation marks, as, for instance in curl -L "https://mathgenealogy.org:8000/api/v2/MGP/acad/siblings?id=263629&window=5" . The CSV results will not render well in most browsers.
Description: Returns all individuals who graduated from the same university within window years on either side of the degree date of the mathematician whose ID is
supplied. Report is as a CSV file by default, but the optional
format parameter may be set to json to return a JSON
dictionary with information as all. The window parameter is optional. If supplied, only cohort relatives whose degree year is within window years of the degree of the mathematician whose ID is supplied will be returned. If window is not supplied, it defaults to 2 to keep result sizes manageable.
Request URL: https://mathgenealogy.org:8000/api/v2/MGP/cohort?id=[number]&window=[number]&format=[csv|json]
Request Value: A numerical MGP ID as id and an optional integer window of years as window. (Default value is 2.) If format is not supplied, CSV will be returned.
Return Values (CSV): CSV results consisting of query_id,id,family_name,given_name,year,msc,school. (The query_id is the ID that was searched for.) A few lines of sample output are shown below.
id,family_name,given_name,year,msc,school 263629,250561,Watson,Ching Tai,2004,91,"University of California, Los Angeles" 263629,250624,Caves,Kevin,2005,91,"University of California, Los Angeles" 263629,17000,Balbas,Jorge,2004,,"University of California, Los Angeles" 263629,17002,Chaudhary,Suneal,2004,91,"University of California, Los Angeles" 263629,17004,Davey,Owen,2004,14,"University of California, Los Angeles" 263629,17045,Kao,Chiu-Yen,2004,,"University of California, Los Angeles" 263629,17046,Lee,Arthur,2004,65,"University of California, Los Angeles" 263629,17048,Moelich,Mark,2004,,"University of California, Los Angeles"
Example Request: https://mathgenealogy.org:8000/api/v2/MGP/cohort?id=263629&window=1
Return Values (JSON): A JSON dictionary (as above) of academic records. A few lines of sampmle output are shown below.
[
{
"MGP_academic": {
"ID": "250561",
"family_name": "Watson",
"given_name": "Ching Tai",
"mrauth_id": "",
"other_names": "",
"student_data": {
"degrees": [
{
"advised by": {
"231458": "Ellickson, Bryan Carl"
},
"degree_msc": "91",
"degree_type": "Ph.D.",
"degree_year": "2004",
"schools": [
"University of California, Los Angeles, United States"
],
"thesis_title": "Essays on Asset Pricing"
}
],
"descendants": {
"advisees": [
""
],
"descendant_count": 0
}
}
}
},
{
"MGP_academic": {
"ID": "250624",
"family_name": "Caves",
"given_name": "Kevin",
"mrauth_id": "1142524",
"other_names": "Wayne",
"student_data": {
"degrees": [
{
"advised by": {
"241367": "Ackerberg, Daniel Abraham"
},
"degree_msc": "91",
"degree_type": "Ph.D.",
"degree_year": "2005",
"schools": [
"University of California, Los Angeles, United States"
],
"thesis_title": "Empirical Studies of Supply and Demand Dynamics"
}
],
"descendants": {
"advisees": [
""
],
"descendant_count": 0
}
}
}
},
...
]
Example Request: https://mathgenealogy.org:8000/api/v2/MGP/cohort?id=263629&window=1&format=json
Note that if you use the command line curl, you may have to enclose the URL in quotation marks, as, for instance in curl -L "https://mathgenealogy.org:8000/api/v2/MGP/acad/cohort?id=263629&window=5" . The CSV results will not render well in most browsers.
Description: Returns all IDs of graph neighbors of the ID given.
Request URL: https://mathgenealogy.org:8000/api/v2/MGP/graph/neighbors?id=[number]
Request Values: An ID parameters is required.
Return Values: A JSON dictionary with structure as illustrated in the following result from the example request below. The entries give a node number and the lists of nodes that received or gave advice to or from that node.
{
"node_neighbors": {
"ID": "28321",
"adviceFrom": [
"11775"
],
"adviceTo": [
"28250",
"28251",
"120858",
"120859"
]
}
}
Example Request: https://mathgenealogy.org:8000/api/v2/MGP/graph/neighbors?id=29321
Description: Returns all edges representing advice in the MGP.
Request URL: https://mathgenealogy.org:8000/api/v2/MGP/graph/edges/
Request Values: No parameters are required.
Return Values: A JSON dictionary with structure as illustrated in the following result from the example request below. The entries give the total numbers of nodes and edges, then the full list of directed edges as node pairs where the first node gave advice to the second.
{
"number_of_edges": 238053,
"number_of_nodes": 213504,
"directed_edges": [
[12025, 37587],
[37587,149783],
[258, 3],
[239, 4],
[258, 5],
[258, 6],
[281, 7],
[258, 8],
[281, 9],
[258, 10]
....
]
}
Example Request: https://mathgenealogy.org:8000/api/v2/MGP/graph/edges/
The Mathematics Genealogy Project API documentation on this page is a derivative of the fine example of documentation provided by The New York Public Library Digital Collections site. The materials offered here are fewer and of a different type but the style of plain explanation offered by the NYPL has been an inspiration.