search

dbopendata / db-fahrplan-api

DB Fahrplan API
31 stars 1 forks source link

Provide prices/fares for each leg #11

Open J0ANMM opened 8 years ago

J0ANMM commented 8 years ago

It would be very useful that the API provides the updated price information.

My first thought would be to include it inside Journey Detail, but I'm not sure what would be the best way.

...
"Types":{
...
}
 },

"Prices":{
"Price":{
// some structure representing half matrix as in the picture attached
}
 },

 "Operators":{
...

journey_price_matrix

Does that make sense?

J0ANMM commented 8 years ago

I found some examples of how APIs from other companies are structured when they have to deal with prices/fares:

Google Flights: https://developers.google.com/qpx-express/v1/trips/search They let you play around with it, 50 requests/day: https://qpx-express-demo.itasoftware.com/

DeinBus.de: https://www.deinbus.de/affiliate/dokumentation.php

The one from Google is of course very complete, but probably too much information and therefore it could get too complicated. The one of DeinBus.de I find it very simple but at the same time it gives all relevant information for this purpose.

Data structure proposal:

The simplest structure I can think of, similarly to the one used by DeinBus.de, would be something like:

    "leg": [
        {
            "depStopid": "8000105",
            "depStop": "Frankfurt(Main)Hbf",
            "depTime": "15:02",
            "depDate": "2016-02-22",
            "arrStopid": "8010101",
            "arrStop": "Erfurt Hbf",
            "arrTime": "17:10",
            "arrDate": "2016-05-22",
            "duration": "02:08",
            "stopovers": 0,
            "fares": [
                {
                    "fareName": "Sparangebote",
                    "price": "EUR19.00"
                },{
                    "fareName": "Flexipreis",
                    "price": "EUR99.00"
                }
            ]
        },
        {
            "depStopid": "8000105",
            "depStop": "Frankfurt(Main)Hbf",
            "depTime": "15:02",
            "depDate": "2016-02-22",
            "arrStopid": "8098160",
            "arrStop": "Berlin Hbf (tief)",
            "arrTime": "19:01",
            "arrDate": "2016-05-22",
            "duration": "03:59",
            "stopovers": 0,
            "fares": [
                {
                    "fareName": "Sparangebote",
                    "price": "EUR31.00"
                },{
                    "fareName": "Flexipreis",
                    "price": "EUR123.00"
                }
            ]
        },
        {
        ...
        }
    ]

// merging date and time and following ISO 8601 could be an idea
// "depDatetime": "2016-05-22T09:13:00+02:00"

Where?

The other question would be where to implement this. The two possibilities that come to my mind are:

  1. Include it inside "Journey detail response".
  2. Create a 5th response format.

Include it inside "Journey detail response"

Would it be possible to include it inside "Journey detail response" as follows?

{
"JourneyDetail":
{
    "noNamespaceSchemaLocation":"https://...name=hafasRestJourneyDetail.xsd",
    "Stops":
    {
         "Stop":
         [
             {
             "name":"Frankfurt(Main)Hbf",
             "id":"8000105",
             "lon":"8.663785",
             "lat":"50.107149",
             "routeIdx":"0",
             "depTime":"15:02",
             "depDate":"2016-02-22",
             "track":"13"
             },{
             "name":"Erfurt Hbf",
             "id":"8010101",
             "lon":"11.038501",
             "lat":"50.972549",
             "routeIdx":"1",
             "arrTime":"17:10",
             "arrDate":"2016-02-22",
             "depTime":"17:12",
             "depDate":"2016-02-22",
             "track":"10"
             },{
             "name":"Berlin Hbf (tief)",
             "id":"8098160",
             "lon":"13.369548",
             "lat":"52.525589",
             "routeIdx":"4",
             "arrTime":"19:01",
             "arrDate":"2016-02-22",
             "depTime":"19:04",
             "depDate":"2016-02-22",
             "track":"6"
             },{
             "name":"Berlin Gesundbrunnen",
             "id":"8011102",
             "lon":"13.388515",
             "lat":"52.548961",
             "routeIdx":"5",
             "arrTime":"19:09",
             "arrDate":"2016-02-22",
             "track":"9"
             }
         ]
    },
    "Names":
    {
        "Name":
        {
            "name":"ICE 1631",
            "routeIdxFrom":"0",
            "routeIdxTo":"5"
        }
    },
    "Types":
    {
        "Type":
        {
            "type":"ICE",
            "routeIdxFrom":"0",
            "routeIdxTo":"5"
        }
    },
    "Operators":
    {
        "Operator":
        {
            "name":"DPN",
            "routeIdxFrom":"0",
            "routeIdxTo":"5"
        }
    },
    "Notes":
    {
        "Note":
        {
            "key":"BR",
            "priority":"450",
            "routeIdxFrom":"0",
            "routeIdxTo":"5",
            "$":"Bordrestaurant"
        }
    },
                      // +++NEW+++
    "Legs":
    {
        "Leg":
        {
            //add here structure
        }
    }
}
}

PROs: No need to create a new response format --> easier to implement by DB? CONs: Requests for Journey details are not direct and more complicated (actually, I did not manage to make it work yet). Therefore, this data would also be more complicated to retrieve. How to deal with requests inside "Journey response" if one wants to know all possible legs that go from A to B at one specific day?

Create a 5th response format

Would it be possible to include a 5th response format, together with "Location response", "Departure board response", "Arrival board response" and "Journey detail response"? It could be called "Leg response" / "Trip response" / "Segment response" or any other name that expresses that the information given is from a station A to a station B at a given point of time.

{
    "leg": [
        {
            "legName": "ICE 1631", //additional field needed
            "legType": "ICE", //additional field needed
            "depStopid": "8000105",
            "depStop": "Frankfurt(Main)Hbf",
            "depTime": "15:02",
            "depDate": "2016-02-22",
            "arrStopid": "8098160",
            "arrStop": "Berlin Hbf (tief)",
            "arrTime": "19:01",
            "arrDate": "2016-05-22",
            "duration": "03:59",
            "stopovers": 0,
            "fares": [
                {
                    "fareName": "Sparangebote",
                    "price": "EUR19.00"
                },{
                    "fareName": "Flexipreis",
                    "price": "EUR99.00"
                }
            ]
        },
        {
            "legName": "ICE 1632", //additional field needed
            "legType": "ICE", //additional field needed
            "depStopid": "8000105",
            "depStop": "Frankfurt(Main)Hbf",
            "depTime": "16:02",
            "depDate": "2016-02-22",
            "arrStopid": "8098160",
            "arrStop": "Berlin Hbf (tief)",
            "arrTime": "20:01",
            "arrDate": "2016-05-22",
            "duration": "03:59",
            "stopovers": 0,
            "fares": [
                {
                    "fareName": "Sparangebote",
                    "price": "EUR31.00"
                },{
                    "fareName": "Flexipreis",
                    "price": "EUR134.00"
                }
            ]
        },
        {
        ...
        }
    ]
}

PROs: Independent requests, that could be much easier to perform, similarly to "Departure board response". CONs: New response format would mean probably more workload for DB (?)