COMP3322 Modern Technologies on World Wide Web
Assignment Two
Total 16 points
Deadline: March 31, 2025 23:59
Overview
You are going to design and develop a Web app that allows users to locate nearby KMB (Kowloon
Motor Bus) bus stops and the estimated time of arrival of bus routes at those nearby bus stops. This
Web app uses the Open Data provided by KMB through the HKSAR Transport Department. The Web
app should be nicely rendered on any desktop computer and smartphone.
Objectives
1. A learning activity to support ILO 1 and ILO 2.
2. To learn how to make use of Open Data.
3. To practice using JavaScript to (1) create dynamic content, (2) carry out AJAX communication to
retrieve Open Data, (3) use SessionStorage to cache data, and (4) display map information.
4. To practice using CSS styling to design a responsive Web application.
Real-time Arrival Data of Kowloon Motor Bus and Long Win Bus Services
We are using the data provided by the REST API of the Transport Department to build this Web App.
Website: https://data.gov.hk/en-data/dataset/hk-td-tis_21-etakmb
You can download the documents related to the data dictionary and the API Specification from here.
https://data.etabus.gov.hk/datagovhk/kmb_eta_data_dictionary.pdf
https://data.etabus.gov.hk/datagovhk/kmb_eta_api_specification.pdf
The site provides nine datasets, but we only use two sets to build our application. They are the Stop
List API and the Stop ETA API. The Stop List API provides information on all bus stops owned by KMB.
The Stop ETA API provides the “Estimated Time of Arrival” (ETA) information of all bus routes at a
specific bus stop, which is the input parameter of this API.
STOP LIST API
The data provided by this API is only updated daily at 05:00. This is the URL for the API.
https://data.etabus.gov.hk/v1/transport/kmb/stop
This API returns a JSON file that contains roughly 66xx bus stop information. Please refer to Figure 1
for the structure of the returned JSON file.
Inside the data[] field, you can find more than 6 thousand bus stop information; each stop contains
the names, a unique stop ID, and the geolocation coordinates.
As the dataset only updated once in the early morning, the system does not allow frequent access to
this API. If it is accessed too frequently (e.g., every second), the system returns status code 403 “The
request is blocked” response.
For the assignment, we mainly use the “stop”, “name_en”, “lat” and “long” fields. Here are the
meanings of these fields:
• stop – the ID of a bus stop
• name_en – the English name of a bus stop
• lat – the latitude of a bus stop location
• long – the longitude of a bus stop location
STOP ETA API
The ETA data provided by this API is updated every one minute. The URL of this API is
https://data.etabus.gov.hk/v1/transport/kmb/stop-eta/{stop_id}
Given a unique stop ID as part of the path, the system returns a JSON file that contains the ETA
information of all bus routes at that stop. Please refer to Figure 2 for the structure of the returned
JSON file.
Inside the data[] field, you can find the list of routes stopping at that bus stop. Please note that for
the same bus route, you may find more than one information block. For example, in Figure 2 the bus
route no. ‘1’ has two information blocks, which give the next two ETAs of route ‘1’.
For the assignment, we mainly use the “route”, “dir”, “service_type”, “dest_en”, “eta_seq”, and
“eta” fields. Here are the meanings of these fields:
{
"type": "StopList",
"version": "1.0",
"generated_timestamp": "2025-02-07T11:28:26+08:00",
"data": [
{
"stop": "18492910339410B1",
"name_en": "CHUK YUEN ESTATE BUS TERMINUS",
"name_tc": "竹園邨總站",
"name_sc": "竹园邨总站",
"lat": "22.345415",
"long": "114.192640"
},
{
"stop": "9ED7E93749ABAE67",
"name_en": "RAINBOW PRIMARY SCHOOL",
"name_tc": "天虹小學",
"name_sc": "天虹小学",
"lat": "22.345076",
"long": "114.190023"
},
:
:
]
}
Figure 1 The sample JSON file returned by the Stop List API
• route – the bus route number
• dir – the direction of the bus route
• service_type – the service type of the bus route
• dest_en – the destination of a bus route in English
• eta_seq – the sequence number of ETA
• eta – the timestamp of the next ETA in ISO 8601 format
Requirements
For this assignment, you are going to implement three program files - index.html, main.js, and
style.css.
{
"type": "StopETA",
"version": "1.0",
"generated_timestamp": "2025-02-07T11:53:22+08:00",
"data": [
{
"co": "KMB",
"route": "1",
"dir": "O",
"service_type": 1,
"seq": 16,
"dest_tc": "尖沙咀碼頭",
"dest_sc": "尖沙咀码头",
"dest_en": "STAR FERRY",
"eta_seq": 1,
"eta": "2025-02-07T11:57:50+08:00",
"rmk_tc": "",
"rmk_sc": "",
"rmk_en": "",
"data_timestamp": "2025-02-07T11:53:17+08:00"
},
{
"co": "KMB",
"route": "1",
"dir": "O",
"service_type": 1,
"seq": 16,
"dest_tc": "尖沙咀碼頭",
"dest_sc": "尖沙咀码头",
"dest_en": "STAR FERRY",
"eta_seq": 2,
"eta": "2025-02-07T12:13:33+08:00",
"rmk_tc": "",
"rmk_sc": "",
"rmk_en": "",
"data_timestamp": "2025-02-07T11:53:17+08:00"
},
:
:
]
}
Figure 2 The sample JSON file returned by the Stop ETA API
FEATURES AND FUNCTIONALITY
Figure 3 The App shows all bus stops within 200m
• Upon loading the App, the program collects the current geolocation data of the device.
• The program uses AJAX (fetch API or XHR object) to download the JSON data from the Stop
List API.
o To avoid frequently accessing the API, which results in receiving a 403 status code,
the program should use local SessionStorage to keep a copy of the Stop List JSON
data. Upon reloading the App, the program should check whether a copy of the
JSON data exists in the SessionStorage before issuing the AJAX request.
o Data in the SessionStorage will be cleared after closing the tab/window, thus
running the program on a new tab/window should trigger the download of the JSON
data again.
• The App utilizes the device's position data and a searching radius (default is 200m) to
identify all KMB bus stops within the specified radius from the device's location, using the
Stop List dataset.
o We use the ‘haversine’ formula to calculate the approximate distance between two
locations.
o You can find more information on using geolocation coordinates to estimate
distance at https://www.movable-type.co.uk/scripts/latlong.html#distance. Here is
the JavaScript code snippet excerpted from this Web site.
• Based on search results, the program displays a list of bus stops ordered by the distance
from the device’s location as shown in [Figure 3]. For each bus stop, it displays the distance
and the English name of the bus stop.
o If the program cannot find any bus stops within this search radius, the message –
“Cannot locate nearby bus stops” should be displayed instead.
• Here are some requirements for the presentation:
o Center the page heading.
o Place the label “Find Nearby Bus Stops Within” and the select element on the same
line.
o The select element has 5 options, ranging from 100m to 500m; the default is 200m.
o Align the Distance and Stop field vertically.
o Apply suitable styling to make them look nice.
• To help users find out the bus routes and their ETAs at a bus stop, you must implement a
mechanism to allow users to click on the name of the bus stop to show the list of routes
and their ETAs as well as a map that shows the locations of the bus stop and the user’s
device.
• We need the Stop ETA JSON data of the selected bus stop for implementing this feature.
Using the Stop List dataset, we know the unique stop ID and its coordinates. When the user
clicks on a stop’s name, the program sends an AJAX request with the corresponding stop ID
to the Stop ETA API. The response should carry the list of bus routes and their ETAs.
• Whenever a bus route has ETA information, the program shows the route number, the
destination, and the sequence of ETAs.
o In the returned ETA dataset, not all bus routes have valid ETA information. The
program should drop (i.e., not show) all routes that have a NULL value in the ETA
field.
o Although it is rare, buses with the same route number traveling in both inbound and
outbound directions can sometimes stop at the same bus stop. Therefore, to
uniquely identify a bus route, you should use both the route number and the
direction.
o In the Stop ETA dataset, it is possible to have records of the same bus route with
more than one service type. Unfortunately, we do not find any information on the
use of service type. We observed that the ETAs of the same route with different
service types are mostly duplicated. Therefore, for our implementation, you can
const R = 6371e3;
// earth's radius in meters
const φ1 = lat1 * Math.PI/180;
// φ, λ in radians
const φ2 = lat2 * Math.PI/180;
const Δφ = (lat2-lat1) * Math.PI/180;
const Δλ = (lon2-lon1) * Math.PI/180;
const a = Math.sin(Δφ/2) * Math.sin(Δφ/2) +
Math.cos(φ1) * Math.cos(φ2) *
Math.sin(Δλ/2) * Math.sin(Δλ/2);
const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
const d = R * c;
// in meters
/* where φ is latitude, λ is longitude, and R is earth’s radius
we must convert the latitude and longitude coordinates to
radians before passing them to the trig functions.
*/
simply use and display the ETAs of a route with the first service type appearing in
the dataset for that route, i.e., most likely it is of type 1.
o A route may have just one ETA or at most three ETAs for a specific service type; your
program should show all available ETAs of that route without duplication.
Figure 4 User can selectively display the ETAs of a bus stop
• Here are some of the requirements:
o Display the list of bus routes alongside the map, i.e., the list is on the left and the
map is on the right.
o Highlight the line to indicate the currently selected bus stop; adopt a suitable style
setting.
o When a user clicks on the name of a bus stop, ensure that the browser displays the
information of the selected bus stop within the browser window as much as
possible.
▪ Hint: Use the scrollIntoView() JavaScript function.
o Present the time in the format of h:mm PM or AM and apply color scheme & spacing
to make them stand out.
o If no valid bus route ETA information, e.g., all ETAs have the NULL value or the
returned ETA dataset is empty, the program shows the “No bus route information”
message on screen.
• Here are the presentation requirements of the map:
o Set the width to 50% of the screen width or at least 400px, and the height to 400px.
o Add two markers to the map. One represents the current geolocation of the device,
and the other represents the geolocation of the selected bus stop.
▪ Two image files will be provided to you – bus-icon.ico and map-marker.ico.
Note: You can choose your icon files.
o Find the midpoint between the two geolocation coordinates and use it as the centre
of the map.
o Apply an appropriate zoom factor to ensure users can see the two markers. Hint:
You should use different zoom factors for different radius ranges.
• How to add a marker to the map? Here is a quick guideline.
o For displaying a marker, we create a new ol.Feature object for the marker with the
geolocation coordinates of the targeted location and create a new ol.style.Style
object that uses the corresponding marker icon. Then, set the ol.style.Style object to
the ol.Feature object using the setStyle() method.
o After creating the two ol.Feature objects, create a new ol.layer.Vector object with
the two ol.Feature objects added to its features list. Then use addLayer() method to
add the Vector object to the existing map.
o Here are three examples:
▪ https://i.cs.hku.hk/~atctam/c3322/HTML5/location-M.html
▪ https://codesandbox.io/p/sandbox/openlayers-add-marker- tkdus?file=%2Findex.js
▪ https://openlayers.org/en/latest/examples/icon.html
• When the user clicks the name of another bus stop (or even the same bus stop), the
program should clear any existing map and bus routes, download the latest ETA
information of the on-clicked bus stop, and render a new bus route list and a map.
• Users can extend the search by adjusting the radius to locate more nearby bus stops. Once
the program detects the change, a new set of bus stops should be displayed.
• When the user reloads the page, the program should retrieve the geolocation coordinates
again, search the cached Stop List dataset (with radius=200m) for nearby bus stops, and
display the set of bus stops. This supports a mobile user looking for the bus information after
moving to a new location.
Figure 5 Mobile layout
• Support responsive design – Users should be able to run the App on smartphones with
screen widths ranging from 350px to 500px. Modify the style settings accordingly.
Resources
You can download the two icon files (bus-icon.ico and map-marker.ico) from the course’s Moodle
page.
Testing platform
We shall place all your submitted files in the c3322-www container and use Chrome and Firefox to
test the web page with two screen widths: 350px vw 500px and 800px vw 1500px.
We can make use of the Sensors panel of Chrome’s Developer Tools to override geolocation. This
allows us to emulate different geolocations. For more information, please visit this link:
https://developer.chrome.com/docs/devtools/sensors#geolocation
Submission
Please finish this assignment before March 31, Monday 23:59. Submit the following files:
1. index.html
2. styles.css
3. main.js
4. GenAI usage report (if applicable)
Grading Policy
Points Criteria
6.0 Locate and display the list of nearby bus stops
▪ 0.5 - Get current geolocation coordinates
▪ 1.0 - Download Stop List dataset
▪ 0.5 - Use SessionStorage to cache the Stop List dataset
▪ 1.5 - Search dataset for nearby bus stops
▪ 1.0 - Allow users to select the search radius
▪ 0.5 - Display the list of bus stops
▪ 0.5 - After reloading, obtain new geolocation coordinates and render a new list of
bus stops
▪ 0.5 - Apply appropriate setting and styling to satisfy the requirements
9.0 Show the ETAs of the bus routes and the map
▪ 1.0 - Implement a mechanism for each bus stop to show the ETA information
▪ 1.0 - Retrieve the Stop ETA dataset for the selected bus stop
▪ 2.5 - Display the ETAs of the routes stopped at the selected bus stop; present all
the information correctly
▪ 1.5 - Display the map with the two markers and the appropriate zoom factor
▪ 1.0 - Always show the bus stop name, its ETA info, and the map in the visible area
of the browser window
▪ 1.0 - Enable switching to display the ETA information and map of a different bus
stop
▪ 1.0 - Apply appropriate setting and styling to satisfy the requirements
1.0 Responsive Design
-1.0 Not using index.html as the Web app main page
-5.0 Use external JavaScript/CSS libraries
Plagiarism
Plagiarism is a very serious academic offence. Students should understand what constitutes
plagiarism, the consequences of committing an offence of plagiarism, and how to avoid it. Please
note that we may request you to explain to us how your program is functioning as well as we may
also make use of software tools to detect software plagiarism.
Using GenAI
You are allowed to use Generative AI to explore various coding techniques and examples to
complete your assignment. Feel free to divide the work into subtasks and employ GenAI to generate
code snippets for better understanding. If you are using GenAI, you SHOULD include a report to
clearly state the use of GenAI, including:
• The GenAI models you used.
• The prompts/questions you had with the GenAI and the responses. If you have adopted
those code snippets, you SHOULD clearly indicate to us.
Should we suspect plagiarism in your submission, it would be unacceptable to justify this by stating
you used GenAI for coding guidance and its output merely mirrors that of other students. While
GenAI can be a valuable tool for exploring different techniques, we often need to apply adjustments
to the provided code snippet to tailor it to our specific tasks.
51作业君版权所有
