Skip to content
gapline
GitHub

Quickstart

This walkthrough takes a real feed, validates it, exports a JSON report, and runs a first query against the stops. Before you start, make sure gapline --version prints a version. If not, see Installation.

1. Get a public feed

Section titled “1. Get a public feed”

We will use the Société de transport de Montréal (STM) feed for this example. Any GTFS archive works — swap in your own if you prefer.

Terminal window
curl -L -o stm.zip https://www.stm.info/sites/default/files/gtfs/gtfs_stm.zip

2. Run your first validation

Section titled “2. Run your first validation”
Terminal window
gapline validate -f stm.zip -o output.txt

The console streams per-group progress bars while the run is in flight. When validation ends, a summary block closes with a PASS or FAIL status and the exit code is non-zero as soon as any ERROR is present.

Terminal window 
$ gapline validate -f stm.zip -o output.txtFile Structure              [██████████████████████████████] 0/14CSV Formatting              [██████████████████████████████] 0/2→ Feed loaded: 847,392 rows in 14 filesThird-Party Validators      [██████████████████████████████] 0/6Field Validation            [██████████████████████████████] 0/13Key & Reference Validation  [██████████████████████████████] 0/24Semantic & Logic            [██████████████████████████████] 0/24Best Practices              [██████████████████████████████] 0/9 ===================================Summary===================================45 Errors — 94912 Warnings — 177074 InfosStatus: FAILDetails written to output.txt (every error, warning, and info, with file and line).

Every finding is written to output.txt in the same order. Each line looks like:

[ERROR]    fk_violation — stop_id "BAD_STOP" not found in stops.txt — stop_times.txt:14203 — stop_id = BAD_STOP

Severities decoded:

  • ERROR — the feed is not compliant. A consumer like Google Maps or Apple Maps will reject it.
  • WARNING — the feed is compliant, but something is suspicious. Worth fixing.
  • INFO — best-practice suggestion. Safe to ignore in a first pass.

Drop -o and the findings stream inline above the summary instead of going to a file.

3. Export a machine-readable report

Section titled “3. Export a machine-readable report”

In a pipeline, you want the findings as structured data, not colored text.

Terminal window
gapline validate -f stm.zip --format json -o report.json

report.json wraps the findings in an errors array with a summary object. Each finding carries the rule ID, section, severity, message, and — when the rule points at a specific location — file, line, field, and value.

{
  "errors": [
    {
      "rule_id": "fk_violation",
      "section": "foreign_key",
      "severity": "Error",
      "message": "stop_id \"BAD_STOP\" not found in stops.txt",
      "file_name": "stop_times.txt",
      "line_number": 14203,
      "field_name": "stop_id",
      "value": "BAD_STOP"
    }
  ],
  "summary": {
    "error_count": 45,
    "warning_count": 94912,
    "info_count": 177074,
    "passed": false
  }
}

4. Query the data

Section titled “4. Query the data”

  1. List every stop whose name starts with Gare:

    Terminal window
    gapline read stops -f stm.zip --where "stop_name LIKE Gare%"

  2. Pull a single stop by ID:

    Terminal window
    gapline read stops -f stm.zip --where "stop_id=STM_10001"

  3. Export the same results as CSV for further processing:

    Terminal window
    gapline read stops -f stm.zip --where "stop_name LIKE Gare%" --format csv -o gares.csv

The --where clause supports =, !=, <, <=, >, >=, LIKE, plus AND and OR. See the query language reference for the full grammar.

Next steps

Section titled “Next steps”