TSJL - GTFS - Query URLs

URL-scheme with REST links

All links are versioned. Current version is v0 and it's specification might change. Once specification has proven to be usable, it will be locked and declared as version v1.
Base URL for links is http://data.foli.fi/gtfs
You can refer to either newest version or to specific version. For example stops.txt is avalailable both as newest API version or from specific API version with URLs like :

Most of time database contains both current and older versions of complete GTFS datasets. Links above are actually redirections (HTTP-302) into dataset specific urls containing the real content.

Technically redirections are cacheable redirections with shorter TTL pointing to real content with very long TTL. Once new GTFS-package is published, redirections start to direct into new final urls while leaving older datasets available from previous urls.
Browsers follow redirects automatically. Client frameworks might need extra option to be enabled to activate automatic HTTP-302 following.

You should use unversioned links. Version v1 will be the last one from v0 series.

Redirections

Server tries to provide all data with longest possible TTL-validity. Because of this, short links (like http://data.foli.fi/gtfs/agency) does not contain any actual data but instead information about from where the latest actual data is to be found.

When client fetches short baselink, it receives HTTP 302 Redirect reply ALSO containing JSON-formatted object about available datasets and actual location of requested data. Browsers follow this redirect automatically, if some client framework doesn't, it can pick further location to go from that JSON-content.

What happens in wire is :

pri:~$ telnet data.foli.fi 80
Trying 192.103.106.131...
Connected to siri.foli.fi.
Escape character is '^]'.
GET /gtfs/stops HTTP/1.0
Host: data.foli.fi

HTTP/1.1 302 Moved Temporarily
Server: nginx
Date: Sat, 23 May 2015 16:05:14 GMT
Content-Type: text/json;charset=utf-8
Connection: close
Location: http://data.foli.fi/gtfs/v0/20150523-123805/stops
X-Cache-Gate: EXPIRED

{
    "host": "data.foli.fi",
    "gtfspath": "\/gtfs\/v0",
    "datasets": [
        "20150523-123805"
    ],
    "latest": "20150523-123805",
    "go": "http:\/\/data.foli.fi\/gtfs\/v0\/20150523-123805\/stops"
}

In case there is not auto-follow available, you can pick actual location of data from reply :

pri:~$ .... | php -r 'print_r(json_decode(file_get_contents("php://stdin")));'
stdClass 
(
    [host] => data.foli.fi
    [gtfspath] => /gtfs/v0
    [datasets] => Array
        (
            [0] => 20150523-123805
        )

    [latest] => 20150523-123805
    [go] => http://data.foli.fi/gtfs/v0/20150523-123805/stops
)

The practice if there is need to point to coherent data

(With absolute bad luck someone uploads new dataset just in between of your queries...)

Aquire listing of available datasets

http://data.foli.fi/gtfs

{
    "host": "data.foli.fi",
    "gtfspath": "\/gtfs\/v0",
    "datasets": [
        "20150431-091102",
        "20150523-123805"
    ],
    "latest": "20150523-123805",
    "success": false,
    "subpaths": [
        "agency",
        "stops",
        "routes",
        "trips",
        "stop_times",
        "calendar",
        "calendar_dates",
        "shapes"
    ]
}

Point your further queries directly to dataset skipping short link redirections.

http://data.foli.fi/gtfs/v0/20150523-123805/agency
http://data.foli.fi/gtfs/v0/20150523-123805/stops