list of transport APIs

This is a machine-readable list of (public) transport API endpoints, with details about who operates them, the protocol used & authentication details.

Format

Overall Structure

There is a single JSON file per API endpoint. It must contain the following properties:

name: endpoint name
type: endpoint protocol description (see below)
supportedLanguages: list of supported languages (see below)
coverage: the geographic area this endpoint provides results for (see below)
options: protocol-specific options (not specified here)

Endpoint Protocol

{
    "type": {
        "hafasMgate": true
    }
}

Known protocols:

efa
hafasMgate
hafasQuery
navitia
otpGraphQl
otpRest
trias
motis

Supported Languages

{
    "supportedLanguages": [
        "en",
        "de",
        "fr",
        "es"
    ]
}

A list of ISO-639-1 language codes describing the languages supported by the endpoint.

Timezone Information

{
    "timezone": "Europe/Berlin"
}

For endpoints that assume times in requests to be in a specific local timezone, the timezone field should contain the IANA timezone identifier of the expected timezone. This timezone can also be applied by clients to times in results returned by the endpoint, particularly when the results are lacking explicit timezone (offset) information.

Coverage Information

Describes the geographic area this endpoint provides results for.

{
    "coverage": {
        "realtimeCoverage": { /* ... */ },
        "regularCoverage": { /* ... */ },
        "anyCoverage": { /* ... */ }
    }
}

There's three coverage categories:

realtimeCoverage: In this area the endpoint provides accurate and highly detailed information. This is typically where the operator can rely on live data about their own vehicles.
regularCoverage: In this area reasonably complete data is available, but e.g. realtime data from other operators is missing or inaccurate quite often.
anyCoverage: In this area only incomplete and/or shallow data is available. This is commonly the case in areas outside the operating area, e.g. long-distance trains & buses but not local modes of transport, or planned data but not realtime data. You could say that this is the extent to which, in a region, the API provides any data.

At least one coverage category must be provided.

{
    "area": { /* GeoJSON polygon or MultiPolygon */ },
    "region": [ /* ISO-3166-1/2 codes */ ]
}

The following properties are defined for each coverage category:

area: a GeoJSON Polygon or MultiPolygon defining the geographic area. This can be reasonably coarse; meter-precision is neither necessary nor practically meaningful.
region: an array of ISO-3166-1 alpha 2 country codes, or ISO-3166-2 region codes covered.

Both fields should be provided.

Attribution Information

The attribution property specifies licensing information for an endpoint.

Open Data

If an endpoint provides results under an Open Data license, attribution generally follows the Data Packages format:

{
    "attribution": {
        "name": "© Helsinki Region Transport",
        "license": "CC-BY-4.0",
        "homepage": "https://www.hsl.fi/"
    }
}

Properties:

license: An Open Definition license ID or an SPDX license id.
name and homepage: The entity to attribute for licenses requiring this.

name and license are mandatory, homepage is optional.

For endpoints aggregating data under various Open Data licenses, the situation can be more complex than this though, making it impossible to specify a single license. This can be expressed using the mixedLicenses property:

{
    "attribution": {
        "name": "© navitia.io",
        "homepage": "https://www.navitia.io/",
        "mixedLicenses": true
    }
}

If mixedLicenses is set to true, the license details are provided in some other form. This can be for example via the homepage property, or as part of the endpoint responses themselves.

Proprietary

If an endpoint is known to be proprietary, attribution can be used to specify this as well:

{
    "attribution": {
        "isProprietary": true
    }
}