Faculty API

The Faculty API provides access to faculty data across different departments, years, and appointment types at Albion College.

Endpoint


GET /api/data/faculty

Authentication

All requests to this endpoint require authentication using an API key. You can provide your API key in one of the following ways:

HTTP Header: X-API-Key: your_api_key
Bearer Token: Authorization: Bearer your_api_key
Query Parameter: ?apiKey=your_api_key

If you don’t have an API key, you can obtain one from your dashboard settings .

Query Parameters

Parameter	Type	Required	Description
`departmentId`	Integer	No	Filter results by department ID
`year`	String	No	Filter results by academic year (e.g., “2022-2023”)
`appointmentType`	String	No	Filter results by appointment type (e.g., “Tenure-Track”, “Adjunct”)
`page`	Integer	No	Page number for pagination (default: 1)
`limit`	Integer	No	Number of results per page (default: 100, max: 1000)
`sortBy`	String	No	Field to sort by (`department`, `appointment_type`, `year`, `count`)
`sortOrder`	String	No	Sort order (`asc` or `desc`)

Note: If none of the filter parameters (departmentId, year, appointmentType) are provided, the API returns data for all faculty.

Response Format

The API returns a JSON response with the following structure:


{
  "success": true,
  "data": [
    {
      "id": 1,
      "department": "Biology",
      "appointment_type": "Tenure-Track",
      "year": "2022-2023",
      "count": 12
    },
    {
      "id": 2,
      "department": "Biology",
      "appointment_type": "Adjunct",
      "year": "2022-2023",
      "count": 5
    },
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "limit": 100,
    "totalPages": 2
  }
}

Response Fields

Field	Description
`success`	Boolean indicating if the request was successful
`data`	Array of faculty records
`data[].id`	Unique identifier for the record
`data[].department`	Name of the academic department
`data[].appointment_type`	Type of faculty appointment (e.g., “Tenure-Track”, “Adjunct”)
`data[].year`	Academic year of the faculty data (e.g., “2022-2023”)
`data[].count`	Number of faculty members matching the criteria
`pagination.total`	Total number of records available
`pagination.page`	Current page number
`pagination.limit`	Number of records per page
`pagination.totalPages`	Total number of pages available

Examples

cURL

Get All Faculty Data


curl -X GET "https://openalbion.org/api/data/faculty" \
  -H "X-API-Key: your_api_key"

Filter by Department


curl -X GET "https://openalbion.org/api/data/faculty?departmentId=5" \
  -H "X-API-Key: your_api_key"

Filter by Year


curl -X GET "https://openalbion.org/api/data/faculty?year=2022-2023" \
  -H "X-API-Key: your_api_key"

Filter by Appointment Type


curl -X GET "https://openalbion.org/api/data/faculty?appointmentType=Tenure-Track" \
  -H "X-API-Key: your_api_key"

Pagination and Sorting


curl -X GET "https://openalbion.org/api/data/faculty?page=2&limit=50&sortBy=count&sortOrder=desc" \
  -H "X-API-Key: your_api_key"

Python

Get All Faculty Data


import requests
 
url = "https://openalbion.org/api/data/faculty"
headers = {
    "X-API-Key": "your_api_key"
}
 
response = requests.get(url, headers=headers)
data = response.json()
 
print(data)

Filter by Department


import requests
 
url = "https://openalbion.org/api/data/faculty"
headers = {
    "X-API-Key": "your_api_key"
}
params = {
    "departmentId": 5
}
 
response = requests.get(url, headers=headers, params=params)
data = response.json()
 
print(data)

JavaScript

Get All Faculty Data


fetch("https://openalbion.org/api/data/faculty", {
  method: "GET",
  headers: {
    "X-API-Key": "your_api_key"
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error("Error:", error));

Using Async/Await with Filtering


async function getFacultyData() {
  try {
    const response = await fetch("https://openalbion.org/api/data/faculty?appointmentType=Tenure-Track", {
      method: "GET",
      headers: {
        "X-API-Key": "your_api_key"
      }
    });
    
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error("Error:", error);
  }
}
 
getFacultyData();

PHP

Get All Faculty Data


<?php
$url = "https://openalbion.org/api/data/faculty";
 
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    "X-API-Key: your_api_key"
]);
 
$response = curl_exec($curl);
$data = json_decode($response, true);
 
curl_close($curl);
print_r($data);
?>

Filter by Year


<?php
$url = "https://openalbion.org/api/data/faculty?year=2022-2023";
 
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    "X-API-Key: your_api_key"
]);
 
$response = curl_exec($curl);
$data = json_decode($response, true);
 
curl_close($curl);
print_r($data);
?>

Error Responses

Status Code	Description
401	Authentication error (missing or invalid API key)
500	Server error

Example error response:


{
  "success": false,
  "error": "API key missing",
  "message": "Please provide an API key via X-API-Key header, Authorization: Bearer header, or apiKey query parameter.",
  "docs": "https://docs.openalbion.org"
}