# API Documentation

We provide a free public REST API that you can use to incorporate real bell schedule, lunch menu, and event data into your project.

# Introduction

The base URL for all requests is https://bell.dev.harker.org/api (HTTPS is required). For example, the full URL for a request to the /schedule endpoint would be https://bell.dev.harker.org/api/schedule.

Every endpoint supports both JSON and URL-encoded request bodies. The code examples use request bodies that are URL-encoded.

Also note that all dates returned in the JSON response are represented as an ISO 8601 (opens new window) date-time string in UTC time.

Because no authentication is required, we may enforce IP-based rate limiting on all requests. If you encounter problems with accessing our API, please contact dev@harker.org.

# GET /schedule

Gets the bell schedule for a given date.

# Request Structure

{
  "month": number, // between 1 and 12
  "day": number, // between 1 and 31
  "year": number // four-digit year
}

# Response Structure

{
  "date": string, // ISO string for the date at UTC midnight
  "code": string, // usually A, B, C, or D
  "variant"?: string, // usually 'special' or 'adjusted', if applicable
  "name"?: string, // name of the modified schedule or holiday
  "schedule": [
    {
      "start": string, // ISO string in UTC time
      "end": string, // ISO string in UTC time
      "name": string // name of this period
    },
    ...
  ]
}

# Example Request

The following example gets the schedule for August 26, 2019. Copy and paste the code into a terminal window to try it out.

curl --request GET \
  --url https://bell.dev.harker.org/api/schedule \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data month=8 \
  --data day=26 \
  --data year=2019

# GET /lunchmenu

Gets the lunch menu for a given date.

# Request Structure

{
  "month": number, // between 1 and 12
  "day": number, // between 1 and 31
  "year": number // four-digit year
}

# Response Structure

{
  "date": string, // ISO string for the date at UTC midnight
  "lunch": [
    {
      "place": string, // where this menu item is being served
      "food": string // name of the menu item (may contain newline characters)
    },
    ...
  ]
}

# Example Request

curl --request GET \
  --url https://bell.dev.harker.org/api/lunchmenu \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data month=8 \
  --data day=26 \
  --data year=2019

# GET /events

Gets a list of events for a given date.

# Request Structure

{
  "month": number, // between 1 and 12
  "day": number, // between 1 and 31
  "year": number // four-digit year
}

# Response Structure

{
  "date": string, // ISO string for the date at UTC midnight
  "events": [
    {
      "name": string, // name of this event
      "start": string, // ISO string in UTC time
      "end": string, // ISO string in UTC time
      "category": string // see below for possible category names
    },
    ...
  ]
}

# Event Categories

Possible categories (and their corresponding color in the bell schedule app):

Category	Identifier	Color
Schoolwide	schoolwide	Red
Academics	academics	Orange
Important Events	important	Yellow
Athletics & Spirit	athspirit	Green
Other Departments/Extracurriculars	extra	Teal
Performing Arts	perfarts	Blue
Clubs	clubs	Purple
Special Events	special	Pink
Schedule Info	info	Gray
Other	other	Brown

# Example Request

curl --request GET \
  --url https://bell.dev.harker.org/api/events \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data month=8 \
  --data day=26 \
  --data year=2019

# GET /ical/feed

Gets an iCal feed for the schedule surrounding the current or requested date.

# Request Structure

Parameters may be passed via query parameters in the URL or via JSON in the request body. When passing an array through query parameters, it should be a comma-separated string without brackets.

# Response Structure

An iCal feed containing the requested periods and events.

# Example Requests

https://bell.dev.harker.org/api/ical/feed?includeSchedule&includeEvents=all

curl --request GET -G \
  --url https://bell.dev.harker.org/api/ical/feed \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data includeSchedule \
  --data includeEvents=all \
  --data month=3 \
  --data day=31 \
  --data year=2025 \
  --data periodNames=TmV2ZXIsZ29ubmEsZ2l2ZSx5b3UsdXAsTmV2ZXIsZ29ubmEgbGV0IHlvdSBkb3du

# GET /ical/download

# Request Structure

Same as /ical/feed.

# Response Structure

Same as /ical/feed, with the exception that the Content-Type and Content-Disposition headers are set to prompt a download of a .ics file.

# Example Request

curl --request GET -G \
  --url https://bell.dev.harker.org/api/ical/download \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data includeSchedule \
  --data month=2 \
  --data day=10 \
  --data year=2025

# GET /clients

Gets the number of clients currently connected to the Harker Bell websocket server.

# Request Structure

No parameters necessary.

# Response Structure

A number representing the number of connected clients.

# Example Request

curl --request GET \
  --url https://bell.dev.harker.org/api/clients

# GET /clientsInternal

Gets the number of clients currently connected to the Harker Bell websocket server, represented by the length of the response in bytes. For internal use.

# Request Structure

No parameters necessary.

# Response Structure

A string with a size in bytes representing the number of connected clients.