| name | express-bus-booking |
| description | Search and assist Korean 고속버스/KOBUS bookings using official HTTP/API-first flows; use for 고속버스 예매, 시간표, 좌석 조회, 임시 선점, and official checkout-entry handoff. |
| license | MIT |
| metadata | {"category":"travel","locale":"ko-KR","phase":"v1"} |
Express Bus Booking (KOBUS)
Overview
Use this skill for Korean 고속버스 / KOBUS timetable lookup and reservation assistance. The preferred workflow is HTTP/API-first: resolve routes, query timetables, inspect remaining seats and fares, and only use browser automation when endpoint discovery or an official web-only step blocks progress.
This skill is intentionally separate from 시외버스. KOBUS terminal codes, route structures, and checkout pages differ from Tmoney 시외버스. Use intercity-bus-booking for 시외버스/Tmoney flows.
When to Use
- The user asks for
고속버스 예매, 고속버스 시간표, 고속버스 예약, 프리미엄 고속버스, or 우등 고속버스.
- The route is clearly a KOBUS 고속버스 route or the user names KOBUS/코버스/고속버스통합예매.
- The user wants assisted reservation up to seat selection, temporary hold, or a payment-entry link.
Do not use this for:
- 시외버스/Tmoney routes — use
intercity-bus-booking.
- Final card submission or payment without explicit, narrowly scoped confirmation.
- Blind browser automation before trying the official HTTP flow.
Core Principles
- Use official KOBUS surfaces:
https://www.kobus.co.kr.
- Keep a cookie jar and reuse referers. Stateless one-off POSTs are less reliable.
- Prefer desktop User-Agent and HTTP/1.1 during probing if the server behaves differently under HTTP/2.
- Default scope is assisted manual checkout: lookup, candidate presentation, seat-stage readiness, temporary seat hold, and official payment-entry page handoff.
- Do not submit card fields, agree to terms, or complete payment unless the user explicitly confirms that exact action.
Known HTTP Flow
See references/kobus-http-flow.md for session-proven endpoint details and parameter examples.
1. Start a Session
Fetch either the main page or route/search page with cookies enabled:
GET https://www.kobus.co.kr/main.do
GET https://www.kobus.co.kr/mrs/rotinf.do
Use a realistic desktop User-Agent and a cookie jar.
2. Resolve Route / Terminal Candidates
POST /mrs/readRotLinInf.ajax
The response is JSON and can include rotInfList, tfrInfList, len, and codeYn. Prefer code-confirmed routes over display-name matching because terminal names are not always unique.
3. Query Timetable
POST /mrs/alcnSrch.do
Typical fields include:
deprCd=010
arvlCd=700
pathDvs=sngl
pathStep=1
deprDtm=YYYYMMDD
busClsCd=0
rtrpChc=1
timeLinkMin=00
timeLinkMax=23
Parse the returned HTML for schedule rows/cards and fnSatsChc(...) onclick arguments. Respect mrsPsbYn=N or any equivalent booking-disabled marker.
4. Enter Seat / Fare Stage
POST /mrs/satschc.do
Send the original search form fields plus selected values from fnSatsChc(...), commonly including:
deprTime
alcnDeprTime
alcnDeprTrmlNo
alcnArvlTrmlNo
indVBusClsCd
cacmCd
dcDvsCd
prvtBbizEmpAcmtRt
chldSftySatsYn
dsprSatsYn
The response should include form#satsChcFrm and hidden fare/seat values such as adltFee, rmnSatsNum, totSatsNum, and terminal/time fields.
5. Temporary Seat Hold
POST /mrs/setPcpy.ajax
Submit the satsChcFrm hidden fields plus selected seat/count fields. A successful response includes:
MSG_CD=S0000
pcpyNoAll
satsNoAll
ESTM_AMT
DC_AMT
TISSU_AMT
Treat the hold as short-lived. If testing, if the user does not proceed, or if a new seat is chosen, release it explicitly.
6. Release Temporary Hold
POST /mrs/cancPcpy.ajax
Use the same relevant form fields plus the returned pcpyNoAll and satsNoAll. A successful response returns MSG_CD=S0000.
Helper Script
Use the bundled helper for KOBUS lookup and optional temporary holds:
python3 express-bus-booking/scripts/kobus_express_booking.py \
--depart-code 021 \
--arrive-code 500 \
--date 20260520 \
--select-index 1 \
--hold-first-seat \
--output-dir /tmp/kobus-hold
For Seoul to Gwangju, the verified KOBUS route is 센트럴시티(서울) code 021 to 광주(유·스퀘어) code 500. A successful hold returns MSG_CD=S0000, pcpyNoAll, satsNoAll, fare amounts, and saves a local auto-submit helper for the official KOBUS payment-information page. Final card entry and payment remain manual. Cancel abandoned holds with /mrs/cancPcpy.ajax using the saved cancel fields.
Checkout-Entry Link Helper
A plain official checkout URL is not enough because KOBUS expects a POST body containing the selected schedule, seat, fare, and hold identifiers. The practical user-facing pattern is:
- Create the temporary hold server-side via
setPcpy.ajax.
- Generate a short helper page that auto-submits a POST form to the official KOBUS checkout endpoint.
- Send the helper link to the user.
- The user completes card/payment fields manually on the official KOBUS page.
Desktop action:
https://www.kobus.co.kr/mrs/stplcfmpym.do
Mobile-friendly action:
https://www.kobus.co.kr/mrs/stplcfmpym.do?keep=/mrs/pay
The POST body should include the original seat form fields plus returned hold values such as pcpyNoAll, satsNoAll, estmAmt, dcAmt, tissuAmt, and nonMbrsYn=Y when using a non-member checkout flow.
Mobile Redirect Caveat
KOBUS common JavaScript can redirect narrow/mobile screens to /mblIdx.do unless location.href contains a mobile-allowed path fragment such as /mrs/pay. In testing, posting to:
/mrs/stplcfmpym.do?keep=/mrs/pay
preserved the same checkout POST body while making the final browser URL contain /mrs/pay, avoiding the client-side mobile-main redirect condition. Use this variant for Discord/mobile users, but still verify with the user because in-app browsers may add their own quirks.
If mobile still lands on the homepage, recommend opening the helper link in a normal external browser or desktop browser. Do not keep retrying holds indefinitely; cancel stale holds.
Suggested Output Format
Keep candidate lists concise and actionable:
고속버스 서울경부 → 부산 / 2026-05-09
1. 00:30 심야우등 / 천일고속 / 잔여 10석 / 성인 47,600원
2. 13:50 우등 / ...
When a hold/checkout helper is created, state that the next step opens the official KOBUS payment page and that payment remains manual.
For Discord/mobile, provide links as normal text links, not fenced code blocks, so the user can tap them directly.
Common Pitfalls
- Mixing KOBUS and Tmoney codes. KOBUS terminal codes are not Tmoney 시외버스 terminal codes.
- Assuming a cart exists. KOBUS does not expose a shopping-cart style hold list in the tested web flow. The realistic UX is temporary seat hold plus checkout-entry handoff.
- Ignoring hold cleanup. Always cancel test holds or abandoned holds with
cancPcpy.ajax.
- Treating lookup success as payment permission. Lookup, seat-stage entry, and temporary hold are not authorization to submit payment.
- Mobile homepage redirects. Use the
?keep=/mrs/pay helper action for mobile; otherwise KOBUS JS may send the user to /mblIdx.do.
- Browser automation too early. Try direct HTTP first. Use browser tooling only to discover changed endpoints or verify final user-facing behavior.
Verification Checklist
