Skip to content

codes.md

Latest commit

 

History

History
327 lines (247 loc) · 12.2 KB

codes.md

File metadata and controls

327 lines (247 loc) · 12.2 KB
Raw

Code Tables

한국도로공사 OpenAPI에서 사용하는 코드값 모음. 라이브러리에서는 모두 src/krex/codes.py 파일에 enum 형태로 제공됩니다.

주의 일부 코드(특히 영업소 코드)는 도로 신설/변경에 따라 추가·수정됩니다. 운영 시점의 정확한 값은 client.tollfee.tollgate_list() 또는 client.reference.routes()로 동기화하세요.

목차

차종 (CarType)

통행료 산정과 교통량 집계의 기준 분류.

코드 Enum 한글명 차량 분류 기준
1 CarType.LIGHT 1종 2축 차량 중 윤폭 279.4mm 이하
(승용차, 16인승 이하 승합, 2.5톤 이하 화물)
2 CarType.MEDIUM 2종 2축 차량 중 윤폭 279.4mm 초과
(2.5톤 초과 ~ 7톤 미만, 16인승 초과 32인승 이하 승합)
3 CarType.LARGE_3AXLE 3종 3축 차량
(7톤 이상 화물 + 32인승 초과 버스)
4 CarType.LARGE_4AXLE 4종 4축 차량
(10톤 이상 대형 화물)
5 CarType.LARGE_5AXLE 5종 5축 이상 특수 차량
6 CarType.LIGHT_DISCOUNT 6종 1종 중 경형(1,000cc 미만) — 50% 할인 대상 
from krex.codes import CarType
CarType.LIGHT.value          # "1"
CarType.LIGHT.label          # "1종 (소형)"
CarType.from_label("1종")     # CarType.LIGHT

TCS / 하이패스 (TCSType)

요금 수납 방식 구분.

코드 Enum 설명
1 TCSType.TCS TCS — 영업소 현장 수납 (현금/카드/단말 미장착)
2 TCSType.HIPASS 하이패스 — 무정차 통과
0 TCSType.ALL TCS + 하이패스 합계 (일부 엔드포인트만 지원)

일부 엔드포인트는 tcsType이 필수이며 0을 받지 않습니다. 합계가 필요하면 1과 2를 따로 호출 후 합산하세요.

도로 운영기관 (RoadOperator)

exDivCode 파라미터에 사용. 한국도로공사가 직접 운영하는 노선과 민자 노선을 구분합니다.

코드 Enum 운영기관 대표 노선
00 RoadOperator.KEC 한국도로공사 경부선, 서해안선, 호남선 등 대부분
01 RoadOperator.PRIV_INCHEON_AIRPORT 신공항하이웨이(주) 인천공항고속도로
02 RoadOperator.PRIV_CHEONAN_NONSAN 천안논산고속도로(주) 천안논산고속도로
08 RoadOperator.PRIV_DAEGU_BUSAN 대구부산고속도로(주) 대구부산고속도로
11 RoadOperator.PRIV_SEOUL_CHUNCHEON 서울춘천고속도로(주) 서울춘천고속도로
18 RoadOperator.PRIV_GURIPOCHEON 서울북부고속도로(주) 구리포천고속도로

민자 노선이 추가되거나 운영주체가 변경되면 코드도 추가됩니다. 위 표는 라이브러리 v1.0 기준이며, 알려지지 않은 코드를 만나면 RoadOperator.OTHER (또는 raw 문자열)로 폴백합니다.

진출입 (IOType)

영업소 통과 방향.

코드 Enum 설명
0 IOType.IN 진입 (고속도로로 들어감)
1 IOType.OUT 진출 (고속도로에서 나감)

시간 단위 (TimeUnit)

집계 시간 단위.

코드 Enum 설명
1 TimeUnit.HOUR 1시간
2 TimeUnit.MIN_15 15분

15분 단위 데이터는 양이 4배이고 보존 기간이 짧을 수 있습니다.

방향 (Direction)

노선 방향 표시.

코드 Enum 설명
0 Direction.UP 상행 (서울/북쪽 방향)
1 Direction.DOWN 하행 (지방/남쪽 방향)
E Direction.EAST 동쪽
W Direction.WEST 서쪽
S Direction.SOUTH 남쪽
N Direction.NORTH 북쪽

노선에 따라 상하/동서남북 표기가 혼재합니다. 예: 경부선은 상/하행, 영동선은 동/서.

실시간 소통 방향 (FlowDirection)

0405 traffic.flow()는 별도 FlowDirection을 사용한다. FlowDirection.START="S"는 기점 방향, FlowDirection.END="E"는 종점 방향이다. 이 코드들을 기존 Direction.SOUTH/EAST나 UP/DOWN으로 해석하면 안 된다. 과거 응답의 dirType은 기존 Direction으로 파싱하는 호환성을 유지한다.

혼잡도 (CongestionLevel)

0405의 원본 grade는 0=판정불가, 1=원활(80km/h 이상), 2=서행(40 이상 80 미만), 3=정체(0 이상 40 미만)다. 각각 None, SMOOTH, SLOW, STOP으로 정규화한다. 아래 공통 enum의 기존 값은 보존하므로 STOP.value="4"와 원본 grade="3"을 혼동하지 않는다.

실시간 소통 정보의 혼잡 수준.

코드 Enum 색상 통행속도 기준 (대략)
1 CongestionLevel.SMOOTH 🟢 녹색 ≥ 80 km/h
2 CongestionLevel.SLOW 🟡 황색 40 ~ 80 km/h
3 CongestionLevel.DELAY 🟠 주황 20 ~ 40 km/h
4 CongestionLevel.STOP 🔴 적색 < 20 km/h

기준 속도는 노선마다 다르며, reference.routes()의 freeFlowSpeed / congestionSpeed로 확인할 수 있습니다.

할인 유형 (DiscountType)

통행료 할인 제도.

코드 Enum 설명
0 DiscountType.NONE 정상 요금
1 DiscountType.NIGHT 심야 할인 (21:00 ~ 06:00, 50%)
2 DiscountType.RUSH_DISCOUNT 출퇴근 시간 할인
3 DiscountType.LIGHT_CAR 경차 할인 (50%)
4 DiscountType.HYBRID 친환경차 할인
5 DiscountType.DISABLED 장애인 할인 (50%)

노선 코드

API에서는 4자리 숫자 형태(0010, 0150 등)로 사용. 마지막 0은 일반적으로 본선, 끝자리에 다른 숫자가 붙으면 지선·우회선을 의미합니다.

주요 본선 노선

코드 노선명 단축명 시점 → 종점 비고
0010 경부고속도로 경부선 부산 → 서울 1번. 상징성 유지
0050 영동고속도로 영동선 인천 → 강릉
0100 남해고속도로 남해선 영암 → 부산
0150 서해안고속도로 서해안선 무안 → 금천
0200 평택제천고속도로 평택제천선 평택 → 제천
0250 호남고속도로 호남선 논산 → 순천
0270 익산포항고속도로 익산포항선 익산 → 포항
0300 대전통영고속도로 통영대전선 대전 → 통영
0350 중부내륙고속도로 중부내륙선 마산 → 양평
0370 중부고속도로 중부선 청주 → 하남
0400 평택파주고속도로 평택파주선 평택 → 파주
0450 중앙고속도로 중앙선 부산 → 춘천
0500 동해고속도로 동해선 부산 → 속초 (단절)
0550 순천완주고속도로 순천완주선 순천 → 완주
0600 서울양양고속도로 서울양양선 서울 → 양양
0650 당진영덕고속도로 당진영덕선 당진 → 영덕
0700 광주원주고속도로 광주원주선 광주(경기) → 원주

주요 지선·순환선

코드 노선명 비고
0020 남해고속도로제1지선
0021 남해고속도로제2지선
0102 호남고속도로지선
0153 평택시흥고속도로 서해안선 지선
0171 오산화성고속도로
0251 고창담양고속도로
0551 서천공주고속도로
1000 수도권제1순환선 옛 서울외곽순환
4000 수도권제2순환선

전체 노선은 약 50종. client.reference.routes()로 최신 마스터 조회 가능. 위 코드값들은 일반적인 4자리 표기 규칙을 따른 것이며, 일부 엔드포인트는 다른 표기(2-3자리)를 요구할 수 있으니 응답 페이로드를 우선 신뢰하세요.

본부·지사

영업소가 소속된 한국도로공사 지역 조직.

지역본부

코드 본부명 관할 지역
01 수도권본부 서울·경기 일부
02 서울경기본부 서울·경기 일부
03 강원본부 강원도
04 충북본부 충청북도
05 대전충남본부 대전·충청남도
06 전북본부 전라북도
07 광주전남본부 광주·전라남도
08 대구경북본부 대구·경상북도
09 부산경남본부 부산·울산·경상남도

본부 코드는 응답 필드 headOfficeCode (일부 엔드포인트는 tcsHeadCode)에 등장합니다. 위 코드 매핑은 추정값이며 실제 코드는 tollgate_list() 응답에서 확인하세요.

주요 영업소 샘플

전국 영업소는 약 350개입니다. 아래는 자주 사용되는 일부 샘플로, 라이브러리 코드값은 권위 있는 출처가 아닙니다 — 운영 시점에는 반드시 client.tollfee.tollgate_list()로 최신 코드를 확인하세요.

경부선 주요 영업소

영업소명 노선 본부 비고
서울 경부선 수도권 경부고속도로 시점
판교 경부선 수도권
신갈 경부선 수도권 영동선 분기
오산 경부선 수도권
안성 경부선 수도권
천안 경부선 대전충남
청주 경부선 충북
대전 경부선 대전충남
김천 경부선 대구경북 본사 소재지
동대구 경부선 대구경북
경주 경부선 대구경북
부산 경부선 부산경남 종점 (구서IC)

서해안선 주요 영업소

영업소명 비고
금천 서해안선 시점
안산
평택
당진
서산
군산
영광
무안
목포 서해안선 종점

코드 검색

영업소 목록은 tollfee.tollgate_list()로 조회해 이름이나 코드를 명시적으로 필터링한다. 로컬 노선 목록은 네트워크 없이 reference.routes()로 얻는다. 영업소/노선 코드는 문자열이며 선행 0을 보존한다.

import asyncio
from krex import KrexClient


async def main() -> None:
    async with KrexClient.from_env() as client:
        page = await client.tollfee.tollgate_list(num_of_rows=1000)
        matches = [item for item in page.items if "부산" in item.unit_name]
        by_code = [item for item in page.items if item.unit_code == "101"]
        print(matches, by_code)
        for route in client.reference.routes():
            print(route.route_no, route.route_name)


asyncio.run(main())

코드값을 안전하게 다루는 패턴

공개 enum이나 해당 문자열 값을 전달한다. 알 수 없는 요청 코드는 KrexInvalidParameterError로 실패한다. UnknownCode나 raw_value 별칭은 제공하지 않는다. 공급자 원문은 반환 모델의 raw로 확인한다.

import asyncio
from krex import CarType, IOType, KrexClient, RoadOperator, TCSType, TimeUnit


async def main() -> None:
    async with KrexClient.from_env() as client:
        page = await client.traffic.by_ic(
            ex_div_code=RoadOperator.KEC,
            unit_code="101",
            in_out=IOType.IN,
            time_unit=TimeUnit.HOUR,
            tcs_type=TCSType.HIPASS,
            car_type=CarType.LIGHT,
            num_of_rows=1,
        )
        for item in page.items:
            print(item.unit_code, item.car_type, item.raw)


asyncio.run(main())