Documentation

What Atlas is

Atlas is a transit analysis platform with a client-side application for comparing scheduled service across agencies and cities.

It turns published transit schedules into map layers, route summaries, stop-level frequency estimates, and network comparisons.

Design principles

• One shared data platform: route, stop, and freshness data are processed into stable outputs for the tools that use them. Additional history and real-time outputs appear only where those features are enabled.
• Honest measurements: when a period does not contain enough sustained service to support a meaningful frequency claim, Atlas flags that limitation instead of tuning the calculation until it produces a plausible-looking number.
• Stable contracts: new information is added alongside existing outputs when possible, so a downstream tool does not silently reinterpret previously published data.

Atlas is more than a map renderer. It is a shared transit-data platform with several layers of work:

• Network exploration: search agencies, routes, stops, and nearby service across a large catalogue.
• Frequency analysis: compare service by day type, time period, route branch, direction, and stop.
• Data quality: expose source dates, stale schedules, review states, corrections, geometry repairs, and known limitations.
• Specialized service: represent on-demand and GTFS-Flex service as zones or virtual stops where a fixed route is the wrong model.
• Additional analysis: support fares and other focused analyses. Research and validation surfaces are documented in the Beta version of this page.
• Reusable data infrastructure: publish stable route, stop, tile, and freshness contracts that other transit tools can consume.

Some surfaces are public, some are in beta, and some remain research or validation tools. The same processed data model supports all of them without making every experimental feature part of the main map.

Atlas keeps several kinds of transit information separate because they answer different questions:

• Schedule data describes what an agency publishes for planned service.
• Processed metrics describe what Atlas derives from that schedule, such as headways, tiers, coverage, and route branches.
• Provenance and quality describe the source, freshness, review state, and corrections attached to a result.

This separation is one of Atlas’s core design principles: a useful number is not automatically a trustworthy number unless its source, meaning, and time period are clear.

Different transit questions need different products. Atlas keeps these surfaces related but does not force them into one overloaded route card:

• Frequency: current scheduled cadence, period filters, route variants, stop-level metrics, and map colouring.
• Fares: base adult fare information derived from GTFS Fares V2 or V1 when available, with a manually entered base fare where a feed has none.
• On-demand service: GTFS-Flex and source-backed service areas represented separately from fixed-route frequency so booking-based service is not misread as a normal route.

Atlas primarily ingests General Transit Feed Specification (GTFS) schedule data published by transit agencies and transit data providers. An official agency feed is preferred; a provider-hosted mirror or fallback may be used when the primary source is unavailable.

1. Feeds are downloaded and checked on a weekly refresh schedule.
2. The pipeline identifies the schedule periods that are active around the refresh date.
3. Routes, stops, calendars, trips, stop times, and shapes are normalized into a shared model.
4. Frequency metrics and quality signals are calculated from the normalized schedule.
5. Static route data, stop indexes, and vector tiles are published to object storage.
6. The browser loads only the data needed for the current map view and selected agency.

Atlas does not require an account or a user database. The deployed frontend and public transit artifacts are separate so data refreshes do not require a frontend release.

Atlas calculates scheduled headways: the time between consecutive departures. It reads departure times from stop_times.txt and expands valid frequency-based trips from frequencies.txt; it does not treat that optional table as a single route-level answer.

Departures are grouped by route, direction, headsign, physical shape, route variant, day, and service period, using each trip’s departure from its first stop. Stop-level cadence is calculated separately. For a group of departures, Atlas sorts the consecutive gaps and uses the median gap as the typical scheduled headway.

The median is intentionally resistant to outliers. One unusually long gap should not make an otherwise regular 10-minute service look like 30-minute service.

Period calculations are kept inside their own time windows. Atlas does not silently borrow an all-day average to fill a period with sparse or missing service.

Atlas keeps separate projections for display cadence, filter cadence, branch cadence, shared-section cadence, and stop-specific cadence. A stop or shared section can have a different value from the whole route because it may combine branches or cover only part of the route.

Period output also carries separate longest-gap and sustained-service signals. These diagnostics can mark a median as unrepresentative without changing the stored median or silently filling the gap with an all-day value.

Band qualification and tolerance

This band test decides whether a pattern counts as steady service, as opposed to infrequent or irregular service. Atlas tests the tightest band first and requires enough departures to cover the analyzed span at that band. For a target of T minutes, the minimum trip count is based on ceil(span ÷ T).

A gap at or below T passes directly. A slightly longer internal gap can count as a near miss when it is no more than T + max(5 minutes, 15% of T). The number of allowed near misses is tier-specific and capped at three:

Atlas rounds the percentage down, does not guarantee a minimum exception, and never allows more than three near misses. A first or last gap that is genuinely at the edge of service may receive a separate allowance up to T + 10 minutes. That edge allowance also uses one of the same near-miss slots, and at least four departures must remain after the edge treatment is applied. A gap beyond the relevant limit, or too many near misses, disqualifies the band and Atlas tests the next slower one.

These allowances handle ordinary schedule rounding and small deviations without turning a genuinely uneven route into a frequent one. A large gap is still a failure even if the median looks good, and the final tier is the fastest band that survives the full check. Rail uses the same tolerance logic with 5, 8, 10, 15, 30, and 60-minute bands, and is tested on midday service from 9:30 a.m. to 2:30 p.m.; the 5- and 8-minute bands are not separate options in the main map filter.

Frequency and regularity are separate properties. A route can run every 30 minutes and still be irregular if it only operates for a short burst or has too few repeated departures to establish a sustained pattern.

Regular

Service covers the normal analysis window. It may be frequent or infrequent.

Time-limited

Predictable service operates during part of the day and has enough repeated departures for a meaningful frequency estimate.

Irregular

Exceptional, very short, one-sided, peak-only, or otherwise unsustained service that should not be presented as a normal route cadence.

The default irregular-service filter hides irregular patterns while keeping predictable time-limited service visible. Periods outside a time-limited route’s operation remain empty rather than inheriting an all-day value.

The frontend is a React application using MapLibre for map interaction and rendering. Route geometry is distributed in vector tiles for broad map views, while agency detail and stop indexes are loaded as smaller JSON artifacts when needed.

At a high level, the browser combines three kinds of information:

• agency metadata, coverage, source dates, and quality notices;
• route geometry and serialized frequency properties; and
• stop coordinates and route-specific service metrics.

This separation keeps the initial map responsive and lets Atlas update schedule data independently from the application interface.

Atlas does not treat every source feed as ready for publication. Corrections happen at different layers, and the layer matters:

• Parsing repairs address malformed source structures, such as broken or interleaved route geometry, only when the repair is unambiguous and validated.
• Normalization rules reconcile feed conventions, synthesize usable directions, remove duplicate patterns, and separate branches or short turns that would otherwise distort analysis.
• User-facing corrections remove known non-revenue trips, placeholder destinations, duplicate source service, or other values that do not represent the published service.
• Agency-specific overrides handle a documented feed problem that cannot safely become a global rule. These are scoped to the affected agency, route, shape, or source snapshot.
• Quality annotations preserve problems that should not be silently “fixed,” such as missing shapes, stale feeds, route-frequency mismatches, or unresolved geometry.

Atlas does not overwrite the upstream GTFS ZIP. It parses the source into an internal data model, applies validated transforms there, and publishes new derived artifacts. Those transforms can filter unusable routes or trips, merge equivalent branches, synthesize missing direction metadata, normalize agency-specific conventions, or repair clearly identifiable geometry problems.

Geometry repairs are conservative: when the parser cannot establish an unambiguous repair, it keeps the original geometry and records the anomaly for review rather than inventing a replacement. The source snapshot remains distinguishable from Atlas’s processed output.

Every correction should have a reason, a narrow scope, and a validation check. A general rule is only preferred when it has been tested against unrelated agencies; otherwise Atlas uses a targeted exception rather than risking a larger silent change.

Corrections are tied to the source data that required them. When a new upstream feed arrives, Atlas rechecks whether the correction is still needed instead of treating the old exception as permanent truth.

Where a correction affects interpretation, Atlas can show a public note on the relevant agency or route. The goal is not to make imperfect data look perfect; it is to make the processing decision visible and bounded.

Changes to the pipeline are treated as changes to published data, not only as code changes. The first step is to identify the narrowest affected layer: one agency, a feed family, or shared processing used by every agency.

1. Reproduce the problem against the source feed and identify the first stage where the result diverges.
2. Add a regression test for the reported case and a legitimate case that a broader fix could accidentally change.
3. Prefer an agency-specific override or narrow transform when the evidence does not support a global rule.
4. For a shared pipeline change, run the full test suite, dry-run the affected feed, and compare the output before and after.
5. Check at least six additional trusted agencies, spanning two countries when applicable, and investigate every unexplained output change.
6. Record the agencies, commands, output diff, and validation result with the change before it is committed.

Publishing is a separate step. A refresh or processing command can write directly to the live public data bucket, so it requires explicit maintainer approval. New or materially changed map data also needs the required tile rebuild, upload, and coverage verification; a successful code build alone does not prove that the public artifacts are correct.

When a source feed changes, Atlas rechecks the correction against the new source. A past exception is not treated as permanent truth, and a newer file is not promoted merely because its date is newer if it fails processing or validation.

Atlas checks feeds for structural and service-data problems, including missing or unusual geometry, schedule inconsistencies, stale sources, and route-frequency anomalies. Some known source problems are corrected or annotated before publication.

Feed-specific corrections are kept separate from the general methodology so a fix for one agency does not silently change every agency’s results.

A conservative publication rule

Atlas would rather show no result and clearly indicate that data is missing than show a precise-looking result that may be wrong. This applies to route geometry, frequency metrics, service areas, fares, transfers, and research findings.

When the evidence is incomplete, Atlas can leave a route or field out, mark a result as unavailable or provisional, keep a feed in review, or preserve the last known artifact with a freshness warning. It does not fill gaps with a guessed value merely to make the map look complete.

How Atlas communicates data quality

Quality decisions are not meant to disappear behind a clean-looking map. Atlas surfaces user-relevant changes in the interface:

• Corrected data: agency and route cards can say “We corrected this data,” with an explanation of the known feed problem and technical issue links when available.
• Outdated schedules: route cards identify schedules that may no longer be current, including the schedule end date when known. The detail panel shows the feed’s check history, or the last successful refresh when no check history is available.
• New schedule data: for agencies whose past feeds have repeatedly had problems, a newly published feed is marked “New schedule data is being verified” until Atlas checks it for missing service and quality problems.
• Route-level warnings: a route can carry a separate warning when its displayed geometry needed adjustment or its service data needs interpretation.

Not every internal exclusion becomes a separate banner. Clearly unusable rows can be removed during processing without overwhelming the map with implementation details, while known user-facing corrections, stale schedules, review states, and material quality problems remain labelled where they affect interpretation.

How outdated data is flagged

Atlas determines schedule freshness from the service dates inside the feed, not only from the date the file was downloaded. It compares the latest usable date in feed_info.txt, calendar.txt, and non-removal entries in calendar_dates.txt with the current date.

During each refresh, Atlas records the feed’s expiry or version, the date it was last successfully processed, and the date it was most recently checked. If every available feed has expired, a download fails, or validation fails, Atlas marks the agency as stale and retains the last good published artifact instead of replacing it with broken or empty output.

This also applies when a source publishes a newer GTFS file that is malformed or fails Atlas’s processing checks: the newer file is not promoted simply because it is newer. The active feed identity and last successful refresh remain unchanged; Atlas records the reason for the failure and tries again at the next refresh.

The interface then identifies that schedule as potentially outdated and shows the known end date, last successful refresh, and subsequent check history when available. For agencies whose past feeds have repeatedly had problems, a newer feed is marked as under review while it is checked for missing service and other quality problems. A feed can therefore be visible, stale, under review, degraded, or unusable as separate states rather than being silently treated as current.

Atlas is schedule analysis, not real-time observation. It does not know whether a vehicle is delayed, cancelled, short-turned, crowded, or accessible unless an explicitly labelled feature provides that information.

Source feeds can be delayed, incomplete, discontinued, or incorrect. For live alerts, accessibility information, trip planning, and emergency instructions, use the relevant transit agency’s official resources.

Validation is the internal evidence chain behind those user-visible states. Atlas does not treat a feed as trustworthy merely because it parsed successfully: valid GTFS can still produce a misleading map, an implausible frequency, or a service area that should not be treated like a fixed route.

How broadly changes are tested

When Atlas changes a shared calculation, the candidate rule is compared across the full set of eligible route-period observations in the local data. This is broader than checking one example route: the same route may be evaluated multiple times because its directions, weekdays, branches, or time periods are separate observations with different schedules.

Changes that survive that broad comparison are then run through the processing pipeline on affected feeds and checked for downstream effects in route geometry, stops, corridors, metadata, and the map outputs. Atlas also reviews representative and surprising cases manually. This layered process gives the methodology broad coverage while keeping the results understandable: a count usually refers to a route-period observation, not necessarily a unique route.

1. Source and freshness checks

Before processing, Atlas records where a feed came from, when it was published or retrieved, and which schedule period it represents. Active-feed audits identify expired URLs, stale schedules, duplicate agency submissions, and sources that have changed shape or availability. Official agency sources are preferred, while provider mirrors are treated as fallbacks rather than equivalent evidence.

The refresh process also inspects feed_info.txt, calendar end dates, and calendar exceptions before deciding what “current” means. A feed containing a future timetable and an expired timetable is not allowed to choose one simply because it appears first in the ZIP file.

2. Structural feed checks

The validator checks required GTFS tables and relationships: routes must connect to trips, trips must connect to calendars and stop times, stop times must reference usable stops or supported Flex locations, and shapes must be readable when geometry is expected. It also checks required fields, duplicate IDs, invalid route types, missing times, orphaned records, routes with no trips, and coordinates outside the valid geographic range.

Checks have different severities. An error blocks or skips unsafe processing; a warning records a problem that may be safely excluded or handled; and an informational result describes something unusual without claiming it is wrong. For example, a missing shapes.txt is not treated the same way as a missing route identifier.

3. Processing and plausibility checks

After normalization, Atlas checks route counts, direction assignment, branch and shape selection, stop coverage, trip durations, headways, service windows, and frequency tiers. It looks for signals such as implausibly short headways, missing geometry, a route disappearing between stages, or a time period claiming service outside its actual operating window.

This is also where Atlas separates things that are easy to accidentally combine: a route’s display geometry is not automatically its analysis geometry; a median headway is not automatically a sustained frequency tier; and a route that runs only at night is not automatically an invalid route. Coverage, regularity, and cadence are checked as separate properties before they are presented together.

4. Corrections and exception audits

Known feed problems are corrected only with a narrow, documented rule. Separate audits review agency-specific overrides, hidden routes, geometry repairs, removed non-revenue patterns, placeholder destinations, and other exceptions so a local fix does not become an undocumented global assumption.

Overrides are rechecked when the upstream feed changes. If a new feed no longer contains a route that was excluded, Atlas flags that exclusion as potentially resolved, and correction notes tied to the old feed are cleared. If the issue remains, the maintainer must re-verify it against the new source rather than assuming that yesterday’s correction still applies.

5. GTFS-Flex and on-demand checks

Flex service is validated separately because its data model is different from fixed-route service. Atlas checks the required Flex files, location groups, group-to-stop links, service areas, virtual stops, booking rules, and Flex stop-time rows. An unlinked location group or a feed with no usable Flex trips fails review rather than becoming an empty-looking service zone.

Atlas keeps the result in a separate on-demand view rather than calculating ordinary route frequency from it. Where a feed is incomplete or unavailable, Atlas uses an official geometry source only when the relationship is documented and visible. A missing polygon is not silently replaced with an invented boundary.

6. Independent source review

Some facts cannot be established from GTFS alone. Atlas separately reviews official agency pages, fare documents, transfer policies, service-area maps, system maps, and agency guides. Each review records what source was checked, what claim it supports, and whether the source is current enough to use.

This is especially important for fares, transfers, system maps, and on-demand coverage. A feed can prove that a route exists, but it may not prove the current adult fare, whether a transfer is free, whether a service area is still active, or whether a map is an official current map. Those claims stay provisional or are excluded when the evidence is not strong enough.

7. Artifact and interface checks

Finally, Atlas checks the published output: route artifacts, stop indexes, vector tiles, metadata, map filters, route cards, links, and deployment modes. The goal is to catch disagreements between the processed data and what a person can actually see or select in the application.

Published artifacts are checked for coverage and shape integrity, not just whether they uploaded successfully. The browser is checked against those artifacts because a correct pipeline result can still be presented incorrectly by a stale index, a missing tile, a mismatched route key, or a filter that uses a different definition than the route card.

8. Manual review and feedback

Automated checks are supplemented by manual spot checks. When someone familiar with a city’s network notices a route, branch, shape, schedule, or frequency that looks wrong, Atlas compares the result against the source feed and the agency’s published information rather than assuming the automated output is correct.

Atlas also includes a Feedback link and a “Report a problem” form on route, stop, and agency cards, which opens a pre-filled email. Reports can identify problems with routes, branches, names, frequencies, schedules, shapes, stops, filters, live information, or stale data, and the route report can include the loaded metric context needed to reproduce the result.

A report is evidence for review, not an automatic correction. The issue is reproduced against the relevant feed and processing stage, then the response may be a code fix, a feed-specific transform, a quality notice, a source update, or a decision to leave the result unchanged when the source supports it.

What happens when a check fails

Atlas does not use one automatic response for every problem:

• Reject: stop processing when the feed cannot be interpreted safely, such as when required relationships are missing or coordinates are invalid.
• Exclude: leave a specific row, trip, route, shape, or Flex record out when it is clearly unusable but the rest of the feed remains valid.
• Correct: apply a narrow rule when the intended interpretation is supported and the change can be tested.
• Annotate: publish a quality note when the source problem is real but removing it would hide information Atlas users may need to interpret the result.
• Hold for review: keep a feature in beta, research, or an audit queue when the evidence is not strong enough for the public map.

These checks do not make the underlying agency data perfect. They make the limits visible, prevent known errors from being amplified, and give each correction or research claim a traceable reason for existing.

GTFS: A standard set of files describing transit routes, stops, trips, calendars, and shapes.

GTFS-Flex: GTFS extensions for demand-responsive service, including service areas, location groups, virtual stops, and booking rules.

Headway: The time between consecutive scheduled departures.

Service period: A named time window: AM Peak (6 to 9 a.m.), Midday (9 a.m. to 3 p.m.), PM Peak (3 to 7 p.m.), Evening (7 to 11 p.m.), Late (11 p.m. to 2 a.m.), or Overnight (2 to 6 a.m.).

Frequency tier: A broad band, such as every 10, 15, 20, 30, or 60 minutes or less, used to colour and filter service on the map.

Service class: The operating pattern assigned to a route or pattern: regular, time-limited, or irregular.

Sustained service: Service whose departure gaps remain within the qualification tolerance across the analysed window, rather than only appearing frequent in a short burst.

Provenance: The source, schedule period, freshness state, review status, and correction history attached to an Atlas result.

PMTiles: A single archive format that lets the map request only the vector-tile regions it needs.