Headcounts API

The Headcounts API provides access to historical student headcount data at Albion College.

Endpoint


GET /api/data/headcounts

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
`year`	Integer	No	Filter results by a specific year
`startYear`	Integer	No	Start of year range for filtering (must be used with `endYear`)
`endYear`	Integer	No	End of year range for filtering (must be used with `startYear`)
`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 (`year`, `headcount`)
`sortOrder`	String	No	Sort order (`asc` or `desc`)

Note: If none of the filter parameters (year, startYear/endYear) are provided, the API returns data for all available years.

Response Format

The API returns a JSON response with the following structure:


{
  "success": true,
  "data": [
    {
      "id": 1,
      "year": 2023,
      "headcount": 1450
    },
    {
      "id": 2,
      "year": 2022,
      "headcount": 1425
    },
  ],
  "pagination": {
    "total": 20,
    "page": 1,
    "limit": 100,
    "totalPages": 1
  }
}

Response Fields

Field	Description
`success`	Boolean indicating if the request was successful
`data`	Array of headcount records
`data[].id`	Unique identifier for the record
`data[].year`	Academic year of the headcount data
`data[].headcount`	Total number of students enrolled
`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 Headcount Data


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

Filter by Specific Year


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

Filter by Year Range


curl -X GET "https://openalbion.org/api/data/headcounts?startYear=2018&endYear=2023" \
  -H "X-API-Key: your_api_key"

Sorting and Pagination


curl -X GET "https://openalbion.org/api/data/headcounts?sortBy=headcount&sortOrder=desc&page=1&limit=10" \
  -H "X-API-Key: your_api_key"

Python

Get All Headcount Data


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

Filter by Year Range


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

JavaScript

Get All Headcount Data


fetch("https://openalbion.org/api/data/headcounts", {
  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 getHeadcountData() {
  try {
    const response = await fetch("https://openalbion.org/api/data/headcounts?year=2023", {
      method: "GET",
      headers: {
        "X-API-Key": "your_api_key"
      }
    });
    
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error("Error:", error);
  }
}
 
getHeadcountData();

PHP

Get All Headcount Data


<?php
$url = "https://openalbion.org/api/data/headcounts";
 
$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 Range


<?php
$url = "https://openalbion.org/api/data/headcounts?startYear=2018&endYear=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"
}