Skip to content

History

Reached as tp.entity(id).history. Both methods page for you and yield rows as they arrive, so a resort's five years never has to fit in memory.

Ask a park id wherever you can. Both history endpoints answer a whole park in one request, and a park-by-park backfill of a large resort costs around a hundred times fewer calls than the same data fetched ride by ride.

History for one entity id, reached as tp.entity(id).history.

coverage

coverage() -> CoverageDocument

What history exists here, field by field. Ask this before a backfill.

span

span() -> HistorySpan

The dates a backfill should run between, as a :class:HistorySpan.

One call, and the same three fields whether this id is a park or a single ride.

days_with_entities

days_with_entities(start: str | date | None = None, end: str | date | None = None, *, max_wait: float = DEFAULT_MAX_WAIT_SECONDS, on_page: Callable[[HistoryPage], None] | None = None) -> Iterator[tuple[EntityRef, HistoryDailyRow]]

days(), but each row arrives with the entity's name and type.

Use this when you are writing history to a file. The name comes from the history response itself, so it is the label that response gives for those rows rather than the park's current /children list -- rides get renamed, and today's name on a row from three years ago is a quiet rewrite of the record.

It also saves a request: the name is already in the payload, so nothing needs to ask what an id refers to.

on_page is called once every row of a page has been yielded, with a :class:HistoryPage. Checkpoint on that, never on the last row you saw.

days

days(start: str | date | None = None, end: str | date | None = None, *, max_wait: float = DEFAULT_MAX_WAIT_SECONDS, on_page: Callable[[HistoryPage], None] | None = None) -> Iterator[tuple[str, HistoryDailyRow]]

One summary row per park-local day, as (entity id, row).

Pages automatically. Given a park id this uses the park call, which answers every entity in the park in one request.

days_with_entities() is the same stream with the entity's name and type attached; this shape is kept because it is public API from 3.0.

changes

changes(date: str | date | None = None, *, start: str | date | None = None, end: str | date | None = None, max_wait: float = DEFAULT_MAX_WAIT_SECONDS) -> HistoryChanges

Every recorded change, as (entity id, row), plus the state before them.

A single day for a park, or up to 31 days for one entity. The caller does not have to know which cap applies: ask for what you want and the API answers or tells you the range is too long.

Iterate the result for the rows. Its opening is each entity's state at the start of the range, which is what a day has to be rebuilt from -- see :class:HistoryChanges.

Asynchronous mirror of :class:HistoryApi.

span async

span() -> HistorySpan

Asynchronous mirror of :meth:HistoryApi.span.

changes

changes(date: str | date | None = None, *, start: str | date | None = None, end: str | date | None = None, max_wait: float = DEFAULT_MAX_WAIT_SECONDS) -> AsyncHistoryChanges

Asynchronous mirror of :meth:HistoryApi.changes.

Not a coroutine, as before: async for pair in history.changes(day) works unchanged. See :class:AsyncHistoryChanges for opening.

Bases: Iterator[tuple[str, HistoryRow]]

What :meth:HistoryApi.changes returns: the rows, and the state before them.

Iterate it exactly as before, for (entity id, row) pairs. Each row is the entity's complete live data from its time until the next row's.

opening is the one thing the rows cannot tell you: the state in force at the START of the range, before the first change. Without it the stretch between midnight and an entity's first change has no known status -- on a night a ride runs past midnight that is real operating time, and a day rebuilt from the rows alone disagrees with the daily summary. It is a dict of :class:HistoryOpening keyed by entity id, with an entry for every entity in the response, including one that did not change at all that day.

Nothing is requested until the result is first used, as when this was a plain generator, and reading opening before or after iterating costs the same single request. close() ends it early, as it did a generator.

An opening can be incomplete: degraded is true when the server could not look far enough back in time for this response, and degradedReason says why. Fields may then be missing from it; ask again a minute later for the full opening. observedAt is when that state was last seen, which can be long before the range for an entity whose feed stopped.

opening property

opening: dict[str, HistoryOpening]

The state at the start of the range, per entity id.

close

close() -> None

Stop iterating. Later next() raises StopIteration; no request is made.

Bases: AsyncIterator[tuple[str, HistoryRow]]

What :meth:AsyncHistoryApi.changes returns. See :class:HistoryChanges.

Iterate it with async for. A property cannot await, so opening is readable once the response has arrived: after the first step of iteration, or straight away with changes = await history.changes(day).load().

opening property

opening: dict[str, HistoryOpening]

The state at the start of the range, per entity id.

load async

load() -> AsyncHistoryChanges

Make the request now, if it has not been made, and return this object.

aclose async

aclose() -> None

Stop iterating, as aclose() did on the async generator this replaced.

Bases: ApiModel

The opening object: the complete state at the start of the range, in the same shape as a row. A field is present only if the entity has it. An unknown value is its empty form (standby {"waitTime": null}, showtimes []); an unknown status is null.

time instance-attribute

time: AwareDatetime

Start of the range (UTC, whole seconds). The state below is effective from this instant.

observedAt class-attribute instance-attribute

observedAt: AwareDatetime | None = None

When this state was last seen (UTC, whole seconds): the newest entry in observedAtByKind. Earlier than time means it was carried in from before the range, possibly from long ago; a ride whose feed stopped keeps its last values. Absent means we hold nothing for this entity from before the range, unless degraded is set.

observedAtByKind class-attribute instance-attribute

observedAtByKind: dict[str, AwareDatetime] | None = None

When each field of the opening was last seen (UTC, whole seconds), keyed by its path: status, queue.StandbyQueue, showtimes and so on. A wait that did not change for weeks is dated weeks back, so check a queue's own entry before treating it as current. Usually, but not always, the moment the value last changed.

degraded class-attribute instance-attribute

degraded: Degraded | None = None

Present, and true, when we could not look far enough back for this response, so the opening may be missing a field we hold. Ask again in a minute for the full opening.

degradedReason class-attribute instance-attribute

degradedReason: DegradedReason | None = None

Why the lookup was cut short: timeout, error, or capacity when it needed more reading than one request is allowed.

status class-attribute instance-attribute

status: str | None = None

Live status at the start of the range; null when unknown.

Bases: NamedTuple

The three dates a backfill needs, in one shape for parks and rides.

A park's coverage document nests these under summary and an entity's carries them at the top level under different names, so without this every caller writes the same branch before they can ask their first question.

retrievable_through is the end date to use. It is what YOUR key may retrieve, not what the archive holds, so a backfill bounded by it stops at the edge of the plan instead of walking into 403s.

final_through property

final_through: date | None

The newest day the archive has recorded that this key may read, or None.

retrievable_through is usually today, and today's row is the day so far. Recent days can still change after that: a run that crosses midnight is reported on the day it started, and the archive records days 2 to 3 behind live data. recorded_to is the newest day the archive holds, so a day on or before it is what the server has recorded, and is the place to stop if you fetch each day once. Ask for anything later again once final_through has moved past it.

Recorded is not immutable: the server can re-record a past day, for example after repairing a park's feed. Fetch a range again if you need to pick that up.

The earlier of the two dates, because a key may be entitled to fewer days than the archive holds. None when either is unknown.

Bases: RateLimitError

The hourly history budget is spent and the wait is longer than allowed.

Carries retry_after from the underlying 429, so a backfill can record where it got to and resume after that long rather than holding a process open waiting for a budget window to roll.