Skip to content

Find listings

School calendars

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

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.

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"

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

The three endpoints

EndpointUse it to
GET /v1/{metro}/school-calendarsList 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}/daysGet 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

typeMeaning
schoolStudents attend.
no_schoolStudents do not attend: a weekend, a holiday, a staff day.
half_dayEarly dismissal.
breakA stated multi-day closure, such as winter break.
summerBetween 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.
nullWe cannot answer this date. See 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 and Errors. Responses are private to your key and are cached briefly; see Caching.