# School calendars

> Premium. Whether school is open on a date, for a district and grade, with a source for every answer.

Source: https://api.tailend.dev/docs/school-calendars

Is school open on a given day? The school calendars endpoints answer that for
a school district, one date at a time, and every answer points back to the
district page it came from. They are a premium feature: see
[Premium access](#premium-access).

```bash
curl -sS -H "X-API-Key: $TAILEND_API_KEY" --get \
  https://api.tailend.dev/v1/philadelphia/school-calendars/example-school-district/days \
  --data-urlencode "from=2026-11-25" \
  --data-urlencode "to=2026-11-29"
```

```javascript
const params = new URLSearchParams({ from: "2026-11-25", to: "2026-11-29" });
const res = await fetch(
  `https://api.tailend.dev/v1/philadelphia/school-calendars/example-school-district/days?${params}`,
  { headers: { "X-API-Key": process.env.TAILEND_API_KEY } }
);
const { data } = await res.json();
for (const day of data) console.log(day.date, day.type, day.reason);
```

The district slug above is an example. List the districts we cover in a metro
with `GET /v1/{metro}/school-calendars`.

## The three endpoints

| Endpoint | Use it to |
| --- | --- |
| `GET /v1/{metro}/school-calendars` | List districts, each with its current and upcoming calendar. |
| `GET /v1/{metro}/school-calendars/{district}` | Read the calendar as the district states it: dated entries for one school year. Takes an optional `school_year`, such as `2026-27`. |
| `GET /v1/{metro}/school-calendars/{district}/days` | Get one answer for every date in a window. `from` and `to` are required; `grade` is optional. |

A school year runs 1 July to 30 June and is named by the year it starts in
(`2026-27`). Dates are the metro's local calendar dates, with no time
component. Use the stated calendar to draw a whole year cheaply, and `/days`
when you need a definite answer for particular dates.

## One answer per date

`/days` returns exactly one item for every date from `from` to `to`, inclusive,
weekends included. The window can be at most 366 days; a longer one, a missing
`from` or `to`, or a `to` before `from` is a `400` with the offending
parameter in `error.details.param`.

Each example below is illustrative, not a real district's calendar.

```json
{
  "data": [
    {
      "date": "2026-11-26",
      "type": "no_school",
      "reason": "holiday",
      "label": "Thanksgiving recess",
      "is_school_day": false,
      "basis": "stated",
      "source": {
        "url": "https://www.example.org/calendar",
        "quote": "Thanksgiving recess, November 26-27",
        "verified_at": "2026-10-01T12:00:00Z"
      }
    }
  ],
  "edition": { "school_year": "2026-27", "published_at": "2026-07-15T14:00:00Z", "board_approved_on": "2026-06-18" },
  "meta": { "metro": "philadelphia", "district": "example-school-district", "from": "2026-11-26", "to": "2026-11-26", "count": 1, "unavailable_count": 0 }
}
```

### Day types

| `type` | Meaning |
| --- | --- |
| `school` | Students attend. |
| `no_school` | Students do not attend: a weekend, a holiday, a staff day. |
| `half_day` | Early dismissal. |
| `break` | A stated multi-day closure, such as winter break. |
| `summer` | Between the last day of one school year and the first day of the next, or up to 31 July when the next year is not published yet. |
| `null` | We cannot answer this date. See [Unavailable is not summer](#unavailable-is-not-summer). |

`reason` says why. It is a closed set: `weekend`, `holiday`, `break`,
`staff_day`, `conference`, `first_day`, `last_day`, `make_up_day`,
`conditional_make_up`, `emergency_closure`, `before_first_day`,
`after_last_day`, `unavailable_not_observed`, `unavailable_no_calendar` and
`other`. It can be `null` on an ordinary school day. New values may be added,
so treat an unknown one as `other`. `label` carries the district's own
wording, such as "Thanksgiving recess".

`is_school_day` is the simple answer: `true`, `false`, or `null` when we
cannot answer. Weekends are `no_school` with `reason: weekend`, so a check of
`type !== "school"` needs no special case.

A make-up day that the district has not called yet is flagged with
`reason: conditional_make_up`, so you can show the caveat. On `/days` this
appears only on an ordinary school day or in summer, and `type` is always the
day's normal calendar type; a holiday, break, weekend or first or last day
never shows it. Once the district calls the make-up day, it becomes a `school`
day with `reason: make_up_day`.

### Every stated date carries its source

Every date the district states has a `source`: the page the date was read from, the exact
wording quoted from it, and when we last checked that page (`verified_at`,
UTC). Show the quote next to the date and your users can check it themselves.
Weekends, implied school days, summer and unavailable days have `source: null`.

`basis` says how firmly the district stated it:

- `stated`: the district's calendar names the date.
- `implied`: not named, but follows from the calendar around it, such as an
  ordinary school day between stated dates, or a weekend.
- `unknown`: we cannot answer the date.

Weekends, implied school days, summer days and unavailable days have
`source: null`, because no page states them. Use `basis` to tell "the
district said so" from "this follows from the calendar".

### Unavailable is not summer

When we cannot answer a date, the response says so explicitly: `type`,
`is_school_day` and `source` are `null`, `basis` is `unknown`, and `reason`
starts with `unavailable_`.

```json
{
  "date": "2028-09-05",
  "type": null,
  "reason": "unavailable_no_calendar",
  "label": null,
  "is_school_day": null,
  "basis": "unknown",
  "source": null
}
```

Treat this as "we do not know", never as a closure and never as a school day.
We do not fill gaps with a guess: `summer` is returned only between a
published calendar's last day and the next first day or, when the next
school year is not published yet, up to 31 July. After that the date is
unavailable. A district with no
published calendar for your window still returns `200`, with every date
unavailable, `edition` set to `null` and `meta.unavailable_count` equal to
`meta.count`. Check `unavailable_count` first if you need to know whether you
can rely on a response.

## Grades

Districts often start some grades earlier than others, or dismiss
secondary grades early. Grades are `PK`, `K`, and `1` to `12`.

Without `grade`, a date is `school` only when it is a school day for every
grade. When grades get different answers on a date, the day also carries
`by_grade`, which groups the grades that share an answer:

```json
{
  "date": "2026-08-28",
  "by_grade": [
    { "grades": ["1", "2", "3"], "type": "school", "reason": "first_day", "label": "First day" },
    { "grades": ["K"], "type": "summer", "reason": "before_first_day", "label": null }
  ]
}
```

(Top-level fields omitted. Example values.) `by_grade` is left off when every
grade has the same answer. Pass `grade=4` to get that grade's answer as the
top-level answer instead; `by_grade` is then omitted and `meta.grade` echoes
the grade. Asking for a grade the district does not serve is a `400`. In the
stated calendar, an entry's `grades` lists the grades it applies to, and
`null` means all students.

## What is not covered

- **Snow days and other emergency closures.** The calendars describe the
  published school year. A day closed at short notice is not reflected, and
  the `emergency_closure` reason is not a live feed. Check the district for
  same-day announcements.
- **District policies.** The stated calendar has a `policies` field, but it is
  always an empty array for now, and `meta.policy_count` is `0`.
- **Individual schools.** Calendars are per district.

## Freshness

Each calendar is a published edition with a `published_at` time and, when the
district states it, the date its board approved the calendar
(`board_approved_on`). `edition` appears on `/days` and on the stated
calendar so you can show how current an answer is. We re-check published
calendars and pick up amendments, but a change is not instant: use
`source.verified_at` to see when a date was last checked.

## Premium access

School calendars require the `school_calendars` feature. It is included with
partner keys and can be added to a standard key; free keys cannot use it. A
key without it gets `403 feature_not_in_plan` on all three endpoints, before
anything else is checked:

```json
{
  "error": {
    "code": "feature_not_in_plan",
    "message": "feature 'school_calendars' is not included with this key's plan",
    "details": { "feature": "school_calendars", "upgrade_url": "https://tailend.dev/pricing" },
    "request_id": "req_2c6a19f8d0b34e77"
  }
}
```

A key limited to some metros gets a `403 forbidden` for another metro. An
unknown metro or district is a `404`. See [Plans & access](https://api.tailend.dev/docs/plans-and-access.md)
and [Errors](https://api.tailend.dev/docs/errors.md). Responses are private to your key and are cached
briefly; see [Caching](https://api.tailend.dev/docs/caching.md).
