{"id":2113,"date":"2026-07-05T22:50:37","date_gmt":"2026-07-05T13:50:37","guid":{"rendered":"https:\/\/butsuri-kori.net\/?p=2113"},"modified":"2026-07-06T20:15:50","modified_gmt":"2026-07-06T11:15:50","slug":"keihan_tracker","status":"publish","type":"post","link":"https:\/\/butsuri-kori.net\/en\/tech\/keihan_tracker\/","title":{"rendered":"I Reverse-Engineered Keihan Railway's Live Train Position Page and Built an Unofficial Train-Tracking Library"},"content":{"rendered":"\n
\"\"<\/figure>\n\n\n\n
<\/i><\/div>
Information<\/span><\/div><\/div>
\n

This article was written by Claude (AI).<\/p>\n<\/div><\/div>\n\n\n\n

This article is a rewrite, for public release, of an independent research report I originally wrote for a social studies inquiry course in my third year of junior high school.<\/p>\n\n\n\n

Introduction<\/h2>\n\n\n\n
\n

\u26a0\ufe0f The API discussed in this article is not officially provided or published by Keihan Electric Railway. It's the result of analyzing JSON that is loaded internally by a public web page. The specification can change without notice, and there are restrictions on secondary use (see \"Notes and Disclaimer\" at the end). Please read this purely as a technical investigation record.<\/p>\n<\/blockquote>\n\n\n\n

The starting point was wanting to build digital signage that shows which train is coming when leaving school, since the walk between the nearest station and the school building is about 1.5 km. To do that, I first need to obtain, in a machine-readable form, where trains currently are.<\/p>\n\n\n\n

Keihan Railway has a page called Train Position<\/a> that shows train locations on a route map in real time. Of course, there isn't a documented, publicly available API that tells you \"which train is coming next to station XX.\" So I analyzed, from the browser, how this page fetches its data, and compiled the results into a Python library called keihan_tracker<\/code><\/a> .<\/p>\n\n\n\n

\"\"<\/a>
https:\/\/github.com\/dk-butsuri\/keihan_tracker<\/a><\/figcaption><\/figure>\n\n\n\n

This article covers that investigation process, and especially the \"calculating the next stop\" problem that gave me the most trouble. I hope it's useful to others who want to analyze the internal APIs of public web pages in a similar way.<\/p>\n\n\n\n

Finding the Endpoints<\/h2>\n\n\n\n

The approach is simple: just use Chrome DevTools to find the endpoints the page is hitting behind the scenes.<\/p>\n\n\n\n

    \n
  1. Open the \"Train Position\" page<\/li>\n\n\n\n
  2. F12<\/code> to open DevTools, then go to the Network<\/strong> tab<\/li>\n\n\n\n
  3. Filter to Fetch\/XHR<\/strong> only<\/li>\n\n\n\n
  4. Reload the page<\/li>\n<\/ol>\n\n\n\n

    This shows only the files being fetched via JavaScript's fetch<\/code> . The following JSON files were loaded from Keihan's page.<\/p>\n\n\n\n

    Endpoint<\/th>Role<\/th><\/tr><\/thead>
    select_station.json<\/code><\/td>Station list per line (station numbers, names, multiple languages)<\/td><\/tr>
    startTimeList.json<\/code><\/td>Stop stations and times per train (schedule)<\/td><\/tr>
    transferGuideInfo.json<\/code><\/td>Transfer line info per station<\/td><\/tr>
    trainPositionList.json<\/code><\/td>Position, type, and delay per train in service<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    Of these, only trainPositionList.json<\/a><\/code> has real-time characteristics<\/strong>; the station list and schedule stay close to static data. The library also fetches the station list and schedule only once, and updates only the position data via polling. Here's roughly what it looks like inside:<\/p>\n\n\n\n

    {\n  "delay": "",\n  "delayEn": "",\n  "delayKo": "",\n  "delayZhCn": "",\n  "delayZhTw": "",\n  "locationCol": "4",\n  "locationRow": "64",\n  "trainDirection": "1",\n  "trainIconTypeImageJp": "JP21_0_0_Pre_D.png",\n  "trainInfoObjects": [\n    {\n      "carsOfTrain": "8",\n      "delayMinutes": "",\n      "delayMinutesEn": "",\n      "delayMinutesKo": "",\n      "delayMinutesZhCn": "",\n      "delayMinutesZhTw": "",\n      "destStationCode": "1",\n      "destStationNameEn": "Yodoyabashi",\n      "destStationNameJp": "\u6dc0\u5c4b\u6a4b",\n      "destStationNameKo": "\uc694\ub3c4\uc57c\ubc14\uc2dc",\n      "destStationNameZhCn": "\u6dc0\u5c4b\u6865",\n      "destStationNameZhTw": "\u6dc0\u5c4b\u6a4b",\n      "destStationNumber": "01",\n      "lastPassStation": "21",\n      "trainNumber": "0807",\n      "trainTypeEn": "Limited Exp.",\n      "trainTypeIcon": "JP21_0_0_Pre_D.png",\n      "trainTypeJp": "\u7279\u6025",\n      "trainTypeKo": "\ud2b9\uae09",\n      "trainTypeZhCn": "\u7279\u6025",\n      "trainTypeZhTw": "\u7279\u6025",\n      "wdfBlockNo": "246"\n    }\n  ],\n  "trainTypeVisIconVis": "EN21_0_0_Pre_D.png"\n}, ...<\/code><\/pre><\/div>\n\n\n\n
    Here's roughly what the schedule data, startTimeList.json<\/code>, looks like:<\/p>\n\n\n\n
    {\n  "fileCreatedTime": "20260706190215",\n  "fileVersion": "1.0.0",\n  "TrainInfo": [\n    {\n      "wdfBlockNo": "1",\n      "extTrain": "0",\n      "premiumCar": "0",\n      "trainCar": "13016",\n      "diaStationInfoObjects": [\n        {\n          "stationNumber": "401",\n          "stationDepTime": "-",\n          "stationNameJp": "\u4e09\u6761",\n          "stationNameEn": "Sanjo",\n          "stationNameZhTw": "\u4e09\u689d",\n          "stationNameZhCn": "\u4e09\u6761",\n          "stationNameKo": "\uc0b0\uc870"\n        },\n        {\n          "stationNumber": "392",\n          "stationDepTime": "05:42",\n          "stationNameJp": "\u7947\u5712\u56db\u6761",\n          "stationNameEn": "Gion-shijo",\n          "stationNameZhTw": "\u7947\u5712\u56db\u689d",\n          "stationNameZhCn": "\u7947\u56ed\u56db\u6761",\n          "stationNameKo": "\uae30\uc628\uc2dc\uc870"\n        },\n        {\n          "stationNumber": "372",\n          "stationDepTime": "05:44",\n          "stationNameJp": "\u4e03\u6761",\n          "stationNameEn": "Shichijo",\n          "stationNameZhTw": "\u4e03\u689d",\n          "stationNameZhCn": "\u4e03\u6761",\n          "stationNameKo": "\uc2dc\uce58\uc870"\n        },\n        {\n          "stationNumber": "330",\n          "stationDepTime": "99:99",\n          "stationNameJp": "\u9f8d\u8c37\u5927\u524d\u6df1\u8349",\n          "stationNameEn": "Ryukokudai-mae-fukakusa",\n          "stationNameZhTw": "\u9f8d\u8c37\u5927\u524d\u6df1\u8349",\n          "stationNameZhCn": "\u9f99\u8c37\u5927\u524d\u6df1\u8349",\n          "stationNameKo": "\ub958\ucf54\ucfe0\ub2e4\uc774\ub9c8\uc5d0 \ud6c4\uce74\ucfe0\uc0ac"\n        },\n        {\n          "stationNumber": "301",\n          "stationDepTime": "05:50",\n          "stationNameJp": "\u4e39\u6ce2\u6a4b",\n          "stationNameEn": "Tambabashi",\n          "stationNameZhTw": "\u4e39\u6ce2\u6a4b",\n          "stationNameZhCn": "\u4e39\u6ce2\u6865",\n          "stationNameKo": "\ub2e8\ubc14\ubc14\uc2dc"\n        },...<\/code><\/pre><\/div>\n\n\n\n
    Locking Down the JSON with Types<\/h2>\n\n\n\n
    Treating raw JSON as a plain dict leads to more and more accesses like data[\"locationObjects\"][0][\"trainInfoObjects\"][0][\"delayMinutes\"]<\/code>, and you lose any way to notice a typo'd key name or a structural change on the API's side. So I defined models with Pydantic<\/a> and made sure fetched JSON is always validated before use.<\/p>\n\n\n\n
    For example, here's roughly how a single train's worth of trainPositionList.json<\/code> gets mapped into a model (partial excerpt).<\/p>\n\n\n\n
    from pydantic import BaseModel, model_validator\nclass trainInfoObject(BaseModel):\n    wdfBlockNo:       int   # internal train management number\n    carsOfTrain:      int   # number of cars\n    delayMinutes:     str   # delay (e.g. "About 5 min")\n    destStationCode:  int   # destination station code\n    destStationNameJp: str  # destination (Japanese)\n    lastPassStation:  int   # <- the troublemaker discussed below\n    trainNumber:      str   # train number\n    trainTypeJp:      TrainType  # type (converted to Enum)\n    is_special:       bool  # whether it's a special\/extra train\n<\/code><\/pre><\/div>\n\n\n\n
    Adding types means editor autocomplete works, and if the API returns an unexpected value, a validation error catches it immediately. When handling external data in a dynamically-typed language like Python, I think this \"validate at the entry point\" pattern is close to mandatory.<\/p>\n\n\n\n
    The type field (trainTypeJp<\/code>) is converted into an Enum<\/code> rather than kept as a raw string. Extra\/special trains have \"\u81e8\u6642\" (extra) prepended to the type name per the spec, so inside the validator I set a flag and strip out that extra text.<\/p>\n\n\n\n
        @model_validator(mode="before")\n    @classmethod\n    def check_type_special(cls, d: dict):\n        if "\u81e8\u6642" in d["trainTypeJp"]:\n            d["is_special"] = True\n            d["trainTypeJp"] = d["trainTypeJp"].replace("\u81e8\u6642\u3000\u3000\u3000\u3000", "")\n        else:\n            d["is_special"] = False\n        return d\n<\/code><\/pre><\/div>\n\n\n\n
    For networking, I use httpx<\/code>'s async client. Anticipating that this would eventually be called from the signage backend (FastAPI), I designed it around async<\/code>\/await<\/code> from the start.<\/p>\n\n\n\n
    The Main Challenge: How to Determine the \"Next Stop\"<\/h2>\n\n\n\n
    This is the part that gave me the most trouble.<\/p>\n\n\n\n
    What the signage needs to show when leaving school is \"which train is arriving at the nearest station, and in how many minutes.\" To do that, I need to extract, from all the trains currently running, the ones \"whose next stop is the nearest station<\/strong>.\" In other words, nothing works unless the \"next stop\" is determined for every train.<\/p>\n\n\n\n
    Trap 1: lastPassStation<\/code> Can't Be Trusted<\/h3>\n\n\n\n
    The first thing I focused on was a parameter called lastPassStation<\/code>. Going by the name, it looks like \"the last station passed,\" and if you know that, it seems like you should be able to derive the next station too.<\/p>\n\n\n\n
    Testing it at Korien Station, this value did indeed seem to point to \"the station currently stopped at, or the next station to stop at.\" But when I tried to get \"the next train to stop at this station\" for a different station, trains that should have appeared didn't show up at all.<\/p>\n\n\n\n
    Reading through the JavaScript on the \"Train Position\" page, also with help from Google AI Studio, revealed the cause. This parameter is an internal value used as the basis for deciding which station a train's detail view starts displaying stop times from<\/strong>, and it isn't strictly managed as \"the last station passed.\" It just happened to behave as expected at Korien; at least on the local-stop segment between Kyobashi and Kayashima, it returns the value of whatever major station precedes it \u2014 Kayashima, Kyobashi, Moriguchi-shi, and so on.<\/p>\n\n\n\n
    \"\"
    The \"train detail\" screen for a local train running between \u014cwada (KH15) and Furukawabashi (KH14)<\/figcaption><\/figure>\n\n\n\n
    This screenshot is of a local train running between \u014cwada (KH15) and Furukawabashi (KH14); because lastPassStation<\/code> is 16 (Kayashima Station), the display starts from the estimated arrival time at \u014cwada \u2014 a station the train should have already passed.<\/p>\n\n\n\n
    For the project's purposes, it would have been fine to leave this alone as long as it worked at Korien or Neyagawa-shi, but considering that a future spec change could break it at Korien too, I decided to calculate it with separate logic instead. The library still keeps the lastpass_station<\/code> property, but explicitly marks it as deprecated.<\/p>\n\n\n\n
    Trap 2: Deriving the Station from Coordinates<\/h3>\n\n\n\n
    The next thing I used was the locationCol<\/code> \/ locationRow<\/code> parameters. These are coordinates for rendering the route map as a grid, and they're really meant for determining display position. Still, they were effectively the only thing usable as position data.<\/p>\n\n\n\n
    Keihan's route map is a vertical grid, and the range of the row<\/code> value roughly determines the line and station. For example, on the regular sections of the Main Line and \u014ct\u014d Line, three rows correspond to one station block, and the position within the block (top\/middle\/bottom) determines whether the train is \"stopped\" or \"moving toward the next station.\" I built the coordinate-to-station-segment conversion logic through what's often called \"vibe coding.\" Roughly, it's structured like this.<\/p>\n\n\n\n
    def calc_position(col: int, row: int):\n    """Given coordinates, return the stopped station number, or the two stations for a train in transit"""\n    # 1. Determine the line from the row range\n    if 1 <= row <= 131:\n        line = "\u4eac\u962a\u672c\u7dda\u30fb\u9d28\u6771\u7dda"  # (the Nakanoshima Line branch is handled separately)\n    elif 132 <= row <= 153:\n        line = "\u5b87\u6cbb\u7dda"\n    elif 154 <= row <= 175:\n        line = "\u4ea4\u91ce\u7dda"\n\n    # 2. On regular Main Line sections, 3 rows = 1 station block\n    if row <= 117:\n        block_index = (row - 1) \/\/ 3\n        current_station = 42 - block_index      # counting backwards from KH42 Demachiyanagi\n        pos_in_block = (row - 1) % 3            # 0: stopped, otherwise: moving\n        if pos_in_block == 0:\n            return (line, current_station, None)        # stopped\n        else:\n            return (line, current_station, current_station - 1)  # moving\n    ...\n<\/code><\/pre><\/div>\n\n\n\n
    However, the underground section (Tenmabashi\u2013Yodoyabashi, and the Nakanoshima Line) is packed tight with no gaps on the route map, so the normal block calculation doesn't work there; I handled it by hardcoding individual stations to specific row<\/code> ranges. This part depends entirely on how Keihan happens to draw its route map, so there was no way around doing it the ugly way.<\/p>\n\n\n\n
    Trap 3: You Can't Reach the Next Station by +1\/-1 on the Station Number<\/h3>\n\n\n\n
    Once you know the segment a train is in, you can get the next stop by searching, in the direction of travel, for \"the first station that appears in the stop-station list.\" At first I simply tried searching by incrementing\/decrementing the station number by +1 \/ -1.<\/p>\n\n\n\n
    This works fine on the Main Line's continuous stretches, but it breaks down at junctions where the station number jumps<\/strong>. Keihan's station numbering is assigned per line, so:<\/p>\n\n\n\n