Schedule

Like the configuration, every city or area need to have a way to define the times of the public transport. While in the past every city needed to come up with its own solution coded in Python, we are currently working in #73 to standardize a way making it possible to use osm2gtfs without having to code anything.

Schedule

To complete the OpenStreetMap data with time information, cities or areas can create a schedule.json which contains all information about trips of their public transport. It is possible to just put the schedule.json in the data directory of osm2gtfs, but for various reasons it is better to publish the file somewhere publicly and define its link in the configuration:

"schedule_source": "https://..." # Link to raw version of schedule.json

One way to publish the schedule is creating a GitHub repository like the one for Estelí, Nicaragua.

In some cities or areas, the timetable is given by frequencies (see an example for Estelí, Nicaragua). There's a simple script that generates the necessary timetable.json for these cases available here.

General information

Before starting with the actual timetable information, the file needs to define some meta information about itself.

start_date

The date (ISO 8601) when the information starts to be valid. Should be preferred over start_date specified in the Configuration (recommended)

"start_date": "2017-10-18"

end_date

The date (ISO 8601) when the information ends to be valid. Should be preferred over end_date specified in the configuration (recommended)

"end_date": "2017-11-18"

updated

The date (ISO 8601) when the information in this file was updated the last time. Should be preferred over updated specified in the configuration (recommended)

"updated": "2017-10-18"

version

The version of the timetable information. Should be preferred over version specified in the configuration (recommended)

"version": "1"

excluded_lines

An array of strings with refs of lines to be excluded from the GTFS generation. Only works without the use of included_lines. (not required)

"excluded_lines": [
    "1",
    "4"
]

included_lines

An array of strings with the refs of all lines to be included in the GTFS generation. When set, excluded_lines will be ignored. (not required)

"included_lines": [
    "2",
    "5"
]

Timetable information

The heart of the file. lines is a object with the line's ref as the key and an array of trips as the value. Each trip is an object with the following information:

from

The first stop of the trip. Has to be equal to the from tag in OSM. (required)

"from": "Hospital"

to

The last stop of the trip. Has to be equal to the to tag in OSM. (required)

"to": "Sandino"

via

An intermediate stop of the trip. Has to be equal to the via tag in OSM. (required if present in OSM)

"via": "Mercado"

services

The service period of the trip. Can be a weekday (two letters abbreviation of it's English name), a range of weekdays, a specific date (ISO 8601) or a range of specific dates (ISO 8601). (required)

"services": [
    "Mo",
    "We-Su",
    "2017-11-18",
    "2017-12-01-2017-12-31"
]

exceptions

Exceptions from the service period of the trip. Can be a weekday (two letters abbreviation of it's English name), a range of weekdays, a specific date (ISO 8601) or a range of specific dates (ISO 8601). (not required)

"exceptions": [
    "Th",
    "Fr-Sa",
    "2017-11-24",
    "2017-12-25-2017-12-26"
]

stations

An array of all stops of the trip. Should be a subset of the stop_positions present in OSM. The first one has to be equal to the from and the last one equal to the to field. (required)

"stations": [
    "Hospital",
    "Mercado",
    "Sandino"
]

times

An array of arrays containing the departure times of every public transport instance at the trip's stops. The length of each array has to be equal to the length of the stations array. (required)

"times": [
    [
        "07:00",
        "07:14",
        "08:00"
    ],
    [
        "08:00",
        "08:14",
        "09:00"
    ]

Here's a complete example of the lines field:

"lines": {
    "3": [
        {
            "from": "Hospital",
            "to": "Sandino",
            "via": "Mercado",
            "exceptions": [
                "Th",
                "Fr-Sa",
                "2017-11-24",
                "2017-12-25-2017-12-26"
            ],
            "services": [
                "Mo",
                "We-Su",
                "2017-11-18",
                "2017-12-01-2017-12-31"
            ],
            "stations": [
                "Hospital",
                "Mercado",
                "Sandino"
            ],
            "times": [
                [
                    "07:00",
                    "07:14",
                    "08:00"
                ],
                [
                    "08:00",
                    "08:14",
                    "09:00"
                ]
            ]
        },
        {
            ...
        }
    ],
    "6": [
        {
            ...
        }
    ]
}