Planning a Trip¶
The main attraction: planning trips for an end-user. Usually the flow exists out of:
- Asking the user what its desired departure-location is;
- Asking the user what its desired arrival-location is;
- Asking for departure-datetime or arrival-datetime;
- Requesting the actual trip at
Go About.
Note
these examples all assume you’ve read Logging in and know how to get a Bearer Token.
Note
these examples show a fictional Bearer Token which cannot be used in the real world. Sorry for that!
Getting Locations¶
The user probably doesn’t know what Location (r:location) corresponds to the desired departure or arrival location. To this end, we’ve hooked you up with the Geocoder (r:geocoder). You can use the Geocoder (r:geocoder) to autocomplete your UI, and finally use it to pinpoint the actual Location (r:location) the user wants to depart from / arrive at.
The departure¶
For example, a user might want to depart from somewhere in Amsterdam:
$ curl -H'Authorization: Bearer UArtDY9Bpo9Whga2mfd7nIK6vENxp2twtnH7RvPC6xj0jy6' 'https://api.goabout.com/geocoder/encode?query=Amsterdam'
{
"locationHrefs" : [ "https://api.goabout.com/location/station/asd", "https://api.goabout.com/location/station/shl", "https://api.goabout.com/location/city/9570", "https://api.goabout.com/location/city/9800", "https://api.goabout.com/location/street/09a6fee0", "https://api.goabout.com/location/street/e0f8ff4d" ],
"_links" : {
"self" : {
"href" : "https://api.goabout.com/geocoder/encode?query=Amsterdam"
}
},
"_embedded" : {
"http://rels.goabout.com/location" : [ {
"type" : "station",
"label" : "Station Amsterdam Centraal",
"coordinates" : {
"latitude" : 52.378887,
"longitude" : 4.9002776
},
"code" : "asd",
"name" : "Amsterdam Centraal",
"_links" : {
"self" : {
"href" : "https://api.goabout.com/location/station/asd"
}
}
}, {
"type" : "station",
"label" : "Station Schiphol",
"coordinates" : {
"latitude" : 52.309444,
"longitude" : 4.7619443
},
"code" : "shl",
"name" : "Schiphol",
"_links" : {
"self" : {
"href" : "https://api.goabout.com/location/station/shl"
}
}
}, {
"type" : "city",
"label" : "Amsterdam",
"coordinates" : {
"latitude" : 52.37416215159466,
"longitude" : 4.896999951113575
},
"name" : "Amsterdam",
"province" : "Noord-Holland",
"_links" : {
"self" : {
"href" : "https://api.goabout.com/location/city/9570"
}
}
}, {
"type" : "city",
"label" : "Amsterdam-Zuidoost",
"coordinates" : {
"latitude" : 52.30800952326094,
"longitude" : 4.971396840076137
},
"name" : "Amsterdam-Zuidoost",
"province" : "Noord-Holland",
"_links" : {
"self" : {
"href" : "https://api.goabout.com/location/city/9800"
}
}
}, {
"type" : "street",
"label" : "Amsterdam-Bataviaweg, Schiphol",
"coordinates" : {
"latitude" : 52.29809944873431,
"longitude" : 4.792833030221746
},
"street" : "Amsterdam-Bataviaweg",
"city" : "Schiphol",
"_links" : {
"self" : {
"href" : "https://api.goabout.com/location/street/09a6fee0"
}
}
}, {
"type" : "street",
"label" : "Klein Amsterdam, Maarn",
"coordinates" : {
"latitude" : 52.062983328667464,
"longitude" : 5.379336236967487
},
"street" : "Klein Amsterdam",
"city" : "Maarn",
"_links" : {
"self" : {
"href" : "https://api.goabout.com/location/street/e0f8ff4d"
}
}
} ]
}
}
Now you can use this data to present the user for a choice, pick one from the list, or be more specific. Let’s assume the user wants to depart from Station Amsterdam Centraal, please note the self-href.
https://api.goabout.com/location/station/asd
The arrival¶
Now for the arrival location, the user wants to go to Prinsengracht 233 in Amsterdam.
$ curl -H'Authorization: Bearer UArtDY9Bpo9Whga2mfd7nIK6vENxp2twtnH7RvPC6xj0jy6' 'https://api.goabout.com/geocoder/encode?query=Prinsengracht+103+Amsterdam'
{
"locationHrefs" : [ "https://api.goabout.com/location/address/2b0392ab", "https://api.goabout.com/location/address/f24e7612" ],
"_links" : {
"self" : {
"href" : "https://api.goabout.com/geocoder/encode?query=Prinsengracht%20103%20Amsterdam"
}
},
"_embedded" : {
"http://rels.goabout.com/location" : [ {
"type" : "address",
"label" : "Prinsengracht 103, Amsterdam",
"coordinates" : {
"latitude" : 52.3786338037223,
"longitude" : 4.887389668706091
},
"street" : "Prinsengracht",
"housenumber" : "103",
"postalCode" : "1015 DN",
"city" : "Amsterdam",
"_links" : {
"self" : {
"href" : "https://api.goabout.com/location/address/2b0392ab"
}
}
}, {
"type" : "address",
"label" : "Korte Prinsengracht 103, Amsterdam",
"coordinates" : {
"latitude" : 52.380662747742555,
"longitude" : 4.88898238090865
},
"street" : "Korte Prinsengracht",
"housenumber" : "103",
"postalCode" : "1013 GR",
"city" : "Amsterdam",
"_links" : {
"self" : {
"href" : "https://api.goabout.com/location/address/f24e7612"
}
}
} ]
}
}
You see that even now the requested location is ambiguous. Let the user choose and note the self-href.
https://api.goabout.com/location/address/2b0392ab
Date & Time¶
Now it’s up to you to find out at what date & time the user wants to depart or arrive at.
Note
All date-time values are in ISO 8601 format. If no timezone information is included (or is ‘Z’), they are in UTC.
Planning¶
Now that you’ve got the departure & arrival location and the datetime for departure or arrival, you can make the actual request.
To create a set of possible Trip (r:trip), you’ll have to post the following data to the Trip planner (r:plan).
{
"fromHref": "https://api.goabout.com/location/station/asd",
"toHref": "https://api.goabout.com/location/address/2b0392ab",
"departure": "2013-08-13T13:30:00Z"
}
You may, of course, use a different timezone if you like. The post results in a
$ curl -X POST -H'Content-Type: application/json' -H'Authorization: Bearer UArtDY9Bpo9Whga2mfd7nIK6vENxp2twtnH7RvPC6xj0jy6' -d'{"toHref": "https://api.goabout.com/location/address/2b0392ab", "departure": "2013-08-13T13:30:00Z", "fromHref": "https://api.goabout.com/location/station/asd"}' 'https://api.goabout.com/plan'
{
"tripHrefs" : [ "https://api.goabout.com/trip/31926" ],
"planRequest" : {
"fromHref" : "https://api.goabout.com/location/station/asd",
"toHref" : "https://api.goabout.com/location/address/2b0392ab",
"departure" : "2013-08-13T13:30:00.000Z"
},
"_links" : {
"self" : {
"href" : "https://api.goabout.com/trip-alternatives/6753"
}
},
"_embedded" : {
"http://rels.goabout.com/trip-selection" : {
"_links" : {
"self" : {
"href" : "https://api.goabout.com/trip-alternatives/6753/trip-selection"
},
"http://rels.goabout.com/trip-alternatives" : {
"href" : "https://api.goabout.com/trip-alternatives/6753"
}
}
},
"http://rels.goabout.com/trip" : {
"delay" : 0,
"departure" : "2013-08-13T13:30:00.000Z",
"arrival" : "2013-08-13T13:46:29.000Z",
"duration" : 989,
"distance" : 1258.0456079423718,
"transfers" : 0,
"from" : {
"latitude" : 52.378887,
"longitude" : 4.9002776
},
"to" : {
"latitude" : 52.3786338037223,
"longitude" : 4.887389668706091
},
"tripLegs" : [ {
"departure" : "2013-08-13T13:30:00.000Z",
"arrival" : "2013-08-13T13:46:29.000Z",
"departureLocation" : {
"type" : "generic",
"name" : "Station Amsterdam Centraal",
"coordinates" : {
"latitude" : 52.378887,
"longitude" : 4.9002776
}
},
"arrivalLocation" : {
"type" : "generic",
"name" : "Prinsengracht 103, Amsterdam",
"coordinates" : {
"latitude" : 52.3786338037223,
"longitude" : 4.887389668706091
}
},
"mode" : {
"modeType" : "walk",
"name" : "",
"lineNumber" : ""
},
"distance" : 1258.0456079423718,
"intermediateStops" : [ ]
} ],
"notifications" : [ ],
"emission" : 0.0,
"cost" : 0.0,
"_links" : {
"self" : {
"href" : "https://api.goabout.com/trip/31926"
}
}
}
}
}
