API Masa Nyata
API Pengangkutan (GTFS-R)

Endpoint API GTFS Realtime (Masa Sebenar)

GET https://api.data.gov.my/gtfs-realtime/<feed>/<agency>

Apakah fungsi API GTFS Realtime?

GTFS Realtime adalah lanjutan daripada API GTFS Statik yang membolehkan pengendali pengangkutan awam untuk membekalkan masa ketibaan, amaran gangguan perkhidmatan, dan kedudukan kenderaan secara masa sebenar (realtime). Buat masa ini, API GTFS Realtime kami hanya membekalkan kedudukan kenderaan sahaja; amaran gangguan perkhidmatan dan kemaskini masa ketibaan akan disusuli secara berperingkat pada 2024-25. Untuk maklumat lanjut mengenai GTFS Realtime dan kegunaannya secara am, sila rujuk kepada https://gtfs.org/realtime/ (opens in a new tab).

Nota penting: API ini dibangunkan secara iterative

Ini adalah kali pertama Malaysia membekalkan API GTFS yang rasmi dan boleh digunakan secara terbuka dan percuma. Ia adalah hasil kerjasama antara pasukan pembangunan data.gov.my dengan pelbagai pengendali pengangkutan awam. Ia belum lagi lengkap; sememangnya, masih terdapat perkhidmatan yang hanya akan disepadukan dalam bulan dan tahun akan datang. API Realtime secara khususnya memerlukan banyak penambahbaikan; maklumat tentang kekurangan yang sudah dikenalpasti telah diperincikan secara telus dalam dokumentasi di bawah supaya para developer yang menggunakan API ini maklum tentang kekangan sedia ada (dan juga maklum bahawa pihak kami juga sudahpun maklum!).

Walau bagaimanapun, dengan beberapa perkhidmatan utama yang sudah terkandung, pihak kami merasakan sudah tiba masa untuk melancarkannya - supaya sektor swasta dan komuniti pengangkutan awam dapat membina produk atas API ini, dan yang paling penting, memberi kami maklum balas untuk meningkatkan lagi mutunya.

Nota: Ralat pengesahan bagi setiap _endpoint dalam bahagian Kedudukan Kenderaan telah dijana dengan Pengesah GTFS Realtime (opens in a new tab)._

Sumber Data bagi GTFS Realtime

API GTFS Realtime menggabungkan data dari pelbagai agensi pengangkutan di Malaysia. Buat masa ini, agensi-agensi berikut menyumbang data pengangkutan mereka:

Format Permintaan (Query) dan Respon

API GTFS Realtime menepati piawaian format protobuf GTFS Realtime (.proto). Perincian format yang lengkap boleh didapati di rujukan rasmi GTFS Realtime (opens in a new tab), manakala fail protobuf dapat diakses melalui endpoint berikut:

Kedudukan Kenderaan

GET https://api.data.gov.my/gtfs-realtime/vehicle-position/<agency>

Kekerapan Kemaskini Data

  • Semua data kedudukan kenderaan dikemaskini setiap 30 saat.

myBAS Johor Bahru

GET https://api.data.gov.my/gtfs-realtime/vehicle-position/mybas-johor
# .proto file dkembalikan
  • Ralat yang sudah dikenalpasti:
    • E003 (opens in a new tab): GTFS-rt trip_id tidak wujud dalam data GTFS
      • ~50% daripada perjalanan tidak wujud (undefined) dalam GTFS Statik.
    • E004 (opens in a new tab): GTFS-rt route_id tidak wujud dalam data GTFS
      • ~15% daripada laluan tidak wujud (undefined) dalam GTFS Statik.
    • E023 (opens in a new tab) - start_time bagi perjalanan tidak sepadan dengan arrival_time GTFS yang pertama
      • medan start_time tidak sah; ini memerlukan pembetulan yang kecil kepada sistem operasi.
    • E028 (opens in a new tab) - Kedudukan kenderaan di luar kawasan liputan agensi
      • Walaupun ralat ini tidak nyahsahkan data secara sendiri, namun tetap memerlukan penambahbaikan bagi data GTFS Statik untuk menyempurnakan padanan data statik dan realtime

KTMB

GET https://api.data.gov.my/gtfs-realtime/vehicle-position/ktmb
# .proto file dkembalikan

Prasarana

GET https://api.data.gov.my/gtfs-realtime/vehicle-position/prasarana?category=<category>
# .proto file dkembalikan
  • Senarai nilai sah bagi <category> adalah rapid-bus-kl, rapid-bus-mrtfeeder, rapid-bus-kuantan dan rapid-bus-penang.
    • Endpoint rapid-rail-kl yang terkandung dalam API GTFS Statik belum lagi dibekalkan dalam API realtime kerana data operasi realtime belum dapat dibekalkan secara stabil.
  • Ralat yang sudah dikenalpasti bagi rapid-bus-kuantan dan rapid-bus-penang:
    • E003 (opens in a new tab): GTFS-rt trip_id tidak wujud dalam data GTFS
    • E004 (opens in a new tab): GTFS-rt route_id tidak wujud dalam data GTFS
      • Ralat ini disebabkan oleh beberapa isu dengan sistem operasi legasi (antaranya yang sudah dipakai lebih daripada sepuluh tahun) yang tidak dapat menjejaki perjalanan kenderaan dan menjana data laluan dengan sempurna. Pasukan kami giat berusaha untuk mengatasi kekangan ini untuk memastikan data realtime menepati piawaian maka menjadi lebih berguna.
  • Ralat yang sudah dikenalpasti bagi rapid-bus-penang:
    • Developer perlu memadankan ID perjalanan (trip ID) dalam data realtime dengan ID perjalanan sedia ada dalam jadual statik. Ini dapat dilaksanakan dengan membandingkan segmen ID perjalanan selepas awalan ID perkhidmatan.
      • Sebagai contoh, ID perjalanan 30000001_1000000855_053000_02 dalam GTFS Realtime sepadan dengan ID perjalanan statik seperti:
        • weekend_30000001_1000000855_053000_02
        • weekday_30000001_1000000855_053000_02
        • 23102302_30000001_1000000855_053000_02
      • Kami telah mengambil keputusan untuk bergantung kepada developer untuk melaksanakan proses padanan ini kerana sebarang pemprosesan data masa sebenar mungkin akan menjejaskan keberfungsian API. Pihak kami akan susuli pembetulan yang lebih menyeleruh pada amsa depan untuk memastikan API statik dan realtime adalah sepadan tanpa perlu sebarang pemprosesan.

Memahami data GTFS Realtime

Untuk membaca data protobuf dengan betul, sila rujuk kepada ikatan bahasa (language bindings) GTFS Realtime rasmi (opens in a new tab) untuk panduan dalam menyahkod data. Kami juga telah sediakan kod Python di bawah sebagai contoh penggunaan data kedudukan kenderaan masa sebenar daripada API GTFS Realtime:

# pip install gtfs-realtime-bindings pandas requests
from google.transit import gtfs_realtime_pb2
from google.protobuf.json_format import MessageToDict
import pandas as pd
from requests import get
 
# Sample GTFS-R URL from Malaysia's Open API
URL = 'https://api.data.gov.my/gtfs-realtime/vehicle-position/prasarana?category=rapid-bus-kl'
 
# Parse the GTFS Realtime feed
feed = gtfs_realtime_pb2.FeedMessage()
response = get(URL)
feed.ParseFromString(response.content)
 
# Extract and print vehicle position information
vehicle_positions = [MessageToDict(entity.vehicle) for entity in feed.entity]
print(f'Total vehicles: {len(vehicle_positions)}')
df = pd.json_normalize(vehicle_positions)
print(df)