Skip to content

discuss & define data format #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vkrause merged 9 commits into from
Dec 23, 2020
Merged

discuss & define data format #1

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
a7a35f6
WIP: Deutsche Bahn (de)
derhuerst Dec 12, 2020
1750c04
add definitions for db-hafas-{mgate,query} and vrr-efa
derf Dec 14, 2020
33b79fa
switch from endpoint type as string/enum to a dictionary
derf Dec 16, 2020
1a915c1
db-hafas-query: remove trainsearch.exe from endpoint
derf Dec 16, 2020
09d4938
Document type property, add proposal for a coverage property
vkrause Dec 19, 2020
9522945
fix some typos and clarify coverage category / area description
derf Dec 19, 2020
b0c90bd
move metdata format specification to root readme file
derf Dec 20, 2020
fbfff85
readme: add required properties; specify supportedLanguages
derf Dec 20, 2020
43a0b81
readme: use JS syntax highlighter to allow for comments
derf Dec 21, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions data/de/db-hafas-mgate.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
{
"name": "Deutsche Bahn (DB)",
"type": "hafas_mgate_deutschebahn",
Copy link
Member Author

@derhuerst derhuerst Dec 16, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I said before, I don't think an "enum of types of APIs" will scale. I'd rather prefer something like "hafasMgate": true, because it can be combined with other flags describing the endpoint.

Copy link
Member

@vkrause vkrause Dec 16, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah, I see what you meant there now. That would work for us too. Making type an array could be an alternative?

Copy link
Contributor

@derf derf Dec 16, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough. I prefer boolean flags (e.g. "hafasMgate": true) over a "type":["hafas_mgate", ...] array – checking whether a dict key exists is more straightforward than iterating over an array.

Copy link
Member Author

@derhuerst derhuerst Dec 20, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't care if its several boolean flags, or an array of flags. Both are a lot more future-proof than a single type enum.

"supportedLanguages": [
"en",
"de",
"fr",
"es"
],
"options": {
"auth": {
"aid": "n91dB8Z77MLdoR0K"
},
"checksumSalt": "6264493855566A34304B356676787766",
"client": {
"id": "DB",
"name": "DB Navigator",
"type": "AND",
"v": 19040000
},
"endpoint": "https://reiseauskunft.bahn.de/bin/mgate.exe",
"ext": "DB.R19.12.a",
"lineModeMap": {
"1": "Long-distance train (ICE)",
"128": "Metro",
"16": "Rapid Transit (S)",
"2": "Long-Distance Train (IC/EC)",
"256": "Tram",
"32": "Bus",
"4": "Local Train (D)",
"512": "Taxi",
"64": "Ferry",
"8": "Local Train (RE/RB)"
},
"locationIdentifierType": "db",
Copy link
Member Author

@derhuerst derhuerst Dec 16, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the idea behind this? @vkrause That the IDs returned by the endpoint are DB-style IBNRs?

Copy link
Member

@vkrause vkrause Dec 16, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

KPublictTransport has multiple id "namespaces" per location. This can be endpoint-specific ones that have no meaning outside (the default), proprietary ones that are shared between two or more endpoints (BVG/VBB are such an example), or standard ones (IBNR, UIC, IFOPT, etc). This is useful for merging data from different sources (different backends, OSM, Wikidata, etc).

To support this we have the following settings:

  • locationIdentifierType defines the id namespace. This is optional for proprietary id spaces not used anywhere else.
  • For many Hafas-based endpoints there is the problem that they use an IBNR or UIC code for stations having one of those, but a proprietary numeric scheme for everything else. The standardLocationIdentifierType and standardLocationIdentifierCountries options address this, the list of covered UIC country codes is needed to reliably distinguish IBNR/UIC codes from other numeric values.

This is obviously very specific to what KPublicTransport does, not particularly elegant or generic, and for most existing users probably irrelevant. I could imagine something like this to be relevant for your merging work though?

Copy link
Member Author

@derhuerst derhuerst Dec 20, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is obviously very specific to what KPublicTransport does, not particularly elegant or generic, and for most existing users probably irrelevant. I could imagine something like this to be relevant for your merging work though?

Yes, highly relevant for my merging work! In fact, there are several projects (in the European community) that try to cross-reference public transport "things" in some way.

"standardLocationIdentifierCountries": [
51,
53,
54,
55,
56,
70,
71,
74,
76,
80,
81,
82,
83,
84,
85,
86,
87,
88
],
"standardLocationIdentifierType": "ibnr",
"version": "1.18"
}
}
47 changes: 47 additions & 0 deletions data/de/db-hafas-query.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
{
"name": "Deutsche Bahn (DB)",
"type": "hafas_query",
"supportedLanguages": [
"en",
"de",
"fr",
"es"
],
"options": {
"endpoint": "https://reiseauskunft.bahn.de/bin/trainsearch.exe/",
"lineModeMap": {
"1": "Long-distance train (ICE)",
"128": "Metro",
"16": "Rapid Transit (S)",
"2": "Long-Distance Train (IC/EC)",
"256": "Tram",
"32": "Bus",
"4": "Local Train (D)",
"512": "Taxi",
"64": "Ferry",
"8": "Local Train (RE/RB)"
},
"locationIdentifierType": "db",
"standardLocationIdentifierCountries": [
51,
53,
54,
55,
56,
70,
71,
74,
76,
80,
81,
82,
83,
84,
85,
86,
87,
88
],
"standardLocationIdentifierType": "ibnr"
}
}
11 changes: 11 additions & 0 deletions data/de/vrr-efa.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"name": "Verkehrsverbund Rhein-Ruhr (VRR)",
"type": "efa",
"supportedLanguages": [
"en",
"de"
],
"options": {
"endpoint": "https://efa.vrr.de/standard/"
}
}