엔드포인트별 파라미터, 응답 스키마, 호출 예시 모음. 라이브러리 메서드와 원본 OpenAPI 사이의 1:1 매핑을 담고 있습니다.
표기 규약
- R = Required (필수), O = Optional (선택)
- 데이터 타입:
str(문자열),int(정수),code(코드값, codes.md 참조)- 모든 엔드포인트는 HTTP GET
| 파라미터 | 필수 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
key |
R | str |
— | 인증키 (포털에서 발급. URL 인코딩 X) |
type |
O | str |
xml |
응답 형식: xml / json |
numOfRows |
O | int |
10 |
페이지당 건수 (대부분 최대 1,000) |
pageNo |
O | int |
1 |
페이지 번호 (1-based) |
| 파라미터 | 필수 | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
serviceKey |
R | str |
— | 인증키 (디코딩된 형태로 전달) |
_type |
O | str |
xml |
응답 형식: xml / json (언더스코어 주의) |
numOfRows |
O | int |
10 |
페이지당 건수 |
pageNo |
O | int |
1 |
페이지 번호 |
신규 "표준데이터" 계열은
perPage/page사용. 라이브러리가 자동 변환.
특정 영업소의 진입/진출 교통량을 시간단위 또는 15분단위로 조회합니다.
- 포털:
data.ex.co.kr - 경로:
/openapi/trafficapi/trafficIc - 메서드:
client.traffic.by_ic()
파라미터
| 이름 | 필수 | 타입 | 설명 |
|---|---|---|---|
exDivCode |
R | code |
도로 운영기관 (00=KEC, codes.md 참조) |
unitCode |
R | str |
영업소 코드 (3자리 숫자) |
inOutType |
R | code |
진출입 (0=진입, 1=진출) |
tmType |
R | code |
시간 단위 (1=1시간, 2=15분) |
tcsType |
R | code |
TCS/하이패스 (1=TCS, 2=Hi-Pass) |
carType |
R | code |
차종 (1~6) |
numOfRows |
O | int |
페이지당 건수 |
pageNo |
O | int |
페이지 번호 |
응답 필드
| 필드 (API) | 라이브러리 필드 | 타입 | 설명 |
|---|---|---|---|
stdDate / sumDate |
collected_date |
date |
집계 일자 (YYYYMMDD) |
stdTime / sumTm |
collected_time |
str |
집계 시각 (HH 또는 HHMM) |
unitCode |
unit_code |
str |
영업소 코드. 실제 응답에서 공백 suffix가 올 수 있어 strip 처리 |
unitName |
unit_name |
str |
영업소명 |
inOutType / inoutType |
in_out |
IOType |
진출입 |
tcsType |
tcs_type |
TCSType |
TCS/하이패스 |
carType |
car_type |
CarType |
차종 |
trafficVol / trafficAmout |
traffic_volume |
int |
교통량 (대). 실제 응답 typo trafficAmout 확인 |
실서버 확인 메모
- 확인일: 2026-05-01
data.ex.co.kr실제 JSON은list가 아니라trafficIctop-level 배열에 레코드를 담아 반환할 수 있습니다.trafficIc는inOutType=0으로 요청해도inoutType=0/1레코드를 함께 반환하는 사례가 확인되었습니다. 호출자는 반환값의in_out을 기준으로 다시 필터링할 수 있습니다.
예시
from krex import CarType, IOType, KrexClient, TCSType, TimeUnit
import asyncio
async def main() -> None:
async with KrexClient.from_env() as client:
res = (await client.traffic.by_ic(
ex_div_code="00",
unit_code="101", # 서울TG (예시값)
in_out=IOType.IN,
time_unit=TimeUnit.HOUR,
tcs_type=TCSType.HIPASS,
car_type=CarType.LIGHT,
num_of_rows=24, # 24시간치
page_no=1,
))
print(res.items[0].traffic_volume)
asyncio.run(main())노선(고속도로) 단위 교통량 통계.
- 포털:
data.ex.co.kr - 경로:
/openapi/trafficapi/trafficRoute - 메서드:
client.traffic.by_route()
실서버 확인(2026-05-01): 유효한 키와 파라미터에서
{"code":"SUCCESS","count":0,"list":[]}형태가 반환될 수 있습니다. 라이브러리는total_count=0으로 보존합니다.
파라미터
| 이름 | 필수 | 타입 | 설명 |
|---|---|---|---|
routeNo |
R | code |
노선번호 (4자리, codes.md 참조) |
tmType |
R | code |
시간 단위 |
dirType |
O | code |
방향 (0=상행, 1=하행) |
carType |
O | code |
차종 |
stdDate |
O | str |
조회일 (YYYYMMDD) |
VDS별 통행속도와 콘존 정보(apiId 0405). 같은 콘존에 여러 VDS 관측 행이 있으며
라이브러리는 이들을 집계하거나 중복 제거하지 않는다.
- 포털:
data.ex.co.kr - 경로:
/openapi/odtraffic/trafficAmountByRealtime - 공식 명세: 실시간 소통 데이터
- 메서드:
client.traffic.flow(),client.traffic.flow_all()
전체 수집은 인자 없는 page = await client.traffic.flow_all()을 사용한다.
한 번의 논리적 조회에서 받은 전체 응답을 검증하고 모든 행을 Page[TrafficFlow]로
반환한다. 필터·페이지 분할·건수 상한·중복 제거는 없으며 len(page.items)와
page.total_count는 일치한다. page_no와 num_of_rows는 None, raw는
원본 전체 응답이다. 공통 HTTP 재시도 정책은 유지한다.
이는 여러 응답을 페이지별로 합치지 않는다는 보장이며, 공급자가 모든 VDS의
수집시각을 같게 보장한다는 뜻은 아니다.
파라미터
| 이름 | 필수 | 타입 | 설명 |
|---|---|---|---|
key |
필수 | str |
인증키, 클라이언트가 자동 제공 |
type |
필수 | str |
json, 클라이언트가 자동 제공 |
2026-09-19 공식 동적 메타데이터(openApiInfoDetail, openApiInfoPop)에는
필터·페이지 입력이 없다. 실제 routeNo=0010, numOfRows=2, pageNo=2 요청도
69개 노선 8,370행 전체를 반환했다. 따라서 이 인자들을 서버로 보내지 않는다.
기존 Python 인자 중 route_no, conzone_id, num_of_rows=1000, page_no=1을
유지하며 flow_all()로 전체 응답 검증 → 로컬 필터 → 로컬 페이지 분할 순으로 적용한다.
direction은 FlowDirection.START/END 또는 "S"/"E"만 받는다.
의미가 다른 Direction 인스턴스와 "0"/"1"은 요청 전에 거부한다.
Page.total_count는 필터 후 건수, Page.raw["count"]는 서버 전체 건수다.
페이지 크기·번호는 양의 정수여야 한다. 필터 결과가 없거나 마지막 페이지를 넘으면 빈 페이지다.
각 호출은 전체 응답을 다시 가져오므로 다른 페이지 호출 사이에 수집 시각이 바뀔 수 있다.
전체 자료가 필요하면 flow_all()을 한 번 호출한다. 자동 반복 호출은 하지 않는다.
응답 필드
| 필드 | 설명 |
|---|---|
conzoneId / conzoneName |
구간 식별자/명 → conzone_id / conzone_name |
routeNo / routeName |
노선 번호/명. 선행 0 보존 |
vdsId |
VDS 식별자 → vds_id: str | None = None. 선행 0과 원문 raw 보존. 실제 표본은 0010VDE00100, 0010VDS00100. 과거 응답의 필드 누락은 None |
stdDate / stdHour |
수집일자 YYYYMMDD / 수집시각 HHMM → updated_at=YYYYMMDDHHMM 문자열. 한국 현지 시각(KST)으로 취급 |
updownTypeCode |
S=기점 방향 → FlowDirection.START, E=종점 방향 → FlowDirection.END. 동서남북 또는 상하행으로 추정하지 않음 |
speed |
속도(km/h) → speed. 실제 음수 결측값은 None, 0은 정지 속도로 보존 |
grade |
0=판정불가 → None, 1=원활(80 이상) → SMOOTH, 2=서행(40 이상 80 미만) → SLOW, 3=정체(0 이상 40 미만) → STOP |
timeAvg |
통행시간, raw에 보존. 공식 메타데이터에 단위 없음. 자유속도로 사용하지 않음 |
trafficAmout / shareRatio |
교통량(대) / 점유율, raw에 보존 |
TrafficFlow의 기존 필드명과 updTime, avgSpeed, dirType 등 과거 응답 별칭은
유지한다. 현행 응답은 자유속도를 주지 않으므로 free_flow_speed=None이다.
기존 공통 CongestionLevel.STOP의 값은 "4"이며, 0405 원본 grade="3"과 다르다.
원본 등급·방향·음수 속도는 항상 raw에서 확인할 수 있다.
두 메서드 모두 응답에 list와 정확한 전체 count가 있어야 한다. 누락·잘못된 타입·건수 불일치·
일부 행 파싱 실패는 KrexParseError다. 명시적인 count=0, list=[]는 정상 빈 응답이다.
NO_DATA 오류는 기존 strict_no_data 설정을 따르지만, 잘못된 응답은 이 설정과
무관하게 거부한다. 검증을 통과한 단일 객체 list도 1행으로 정규화한다.
근거는 공식 JavaScript가 호출하는
POST /openapi/basicinfo/openApiInfo, openApiInfoDetail, openApiInfoPop
(apiId=0405)와 실제 응답이다. 명세에는 시간대·갱신 주기·통행시간 단위가 명시되지
않았다. KST 해석은 한국 현지 수집시각과 검증 시각이 일치한 관측에 근거하며,
갱신 주기를 5분으로 단정하지 않는다.
고속도로 사고, 공사, 통제 등 돌발 상황의 실시간 문자정보 (apiId 0611).
구 경로
/openapi/trafficapi/incident는 포털에서 제거되어 항상 HTTP 404를 반환한다 (2026-06-11 확인). 현행 경로는 아래와 같다.
- 포털:
data.ex.co.kr - 경로:
/openapi/burstInfo/realTimeSms - 메서드:
client.traffic.incident() - snapshot 검증: 정상 응답의
realTimeSMSList와 0 이상인count가 모두 있어야 한다. 둘 중 하나가 없는 HTTP 200 오류 본문은 빈 목록이 아니라KrexParseError로 처리하며,count=0+realTimeSMSList=[]만 명시적 빈 snapshot으로 인정한다.
파라미터
| 이름 | 필수 | 타입 | 설명 |
|---|---|---|---|
accTypeCode |
O | code |
돌발 유형 코드 (미지정 시 전체) |
numOfRows |
O | int |
페이지당 건수 |
pageNo |
O | int |
페이지 번호 |
응답 필드 (목록 키: realTimeSMSList, 전체 건수 키: count)
| 키 | 모델 필드 | 설명 |
|---|---|---|
accDate / accHour |
occurred_date / occurred_time |
발생일 (2023.09.27) / 발생시각 (09:11:24) |
accType / accTypeCode |
incident_type / incident_type_code |
돌발 유형명 / 코드 |
startEndTypeCode |
direction |
방향 텍스트 (예: 대구방향) |
smsText |
message |
문자정보 본문 |
accPointNM |
point_name |
발생 지점명 (공백뿐이면 None) |
nosunNM / roadNM |
route_no / route_name |
노선번호 (0552) / 도로명 (대구부산선) |
accProcessNM / accProcessCode |
process_status / process_status_code |
처리 상태명 / 코드 |
latitude |
latitude |
돌발시작이정위도 |
altitude |
longitude |
돌발시작이정경도 — 포털이 경도를 altitude 키로 내려준다 |
lateLength |
congestion_length |
정체길이 |
seriesNM |
series_no |
일련번호 |
차량검지기(VDS, Vehicle Detection System) 원시 데이터. 5분 단위.
- 포털:
data.ex.co.kr - 경로:
/openapi/trafficapi/vdsRaw - 메서드:
client.traffic.vds_raw()
주의: 데이터 양이 매우 많으므로 시간 범위를 좁혀 조회. 전국 1일치는 수십만 건.
자동차량분류장치(AVC) 원시자료. 차종별·차로별 통과 기록.
- 포털:
data.ex.co.kr/data.go.kr(ID15066742) - 경로:
/openapi/trafficapi/avcRaw - 메서드:
client.traffic.avc_raw()
파라미터
| 이름 | 필수 | 타입 | 설명 |
|---|---|---|---|
vdsId |
R | str |
VDS 식별자 |
stdDate |
R | str |
조회일 (YYYYMMDD) |
출발지·도착지 영업소 간 통행료, 거리, 소요시간 조회.
- 포털:
data.ex.co.kr/data.go.kr(ID15111644) - 경로:
/openapi/tollfee/tollFeeBetweenTcs(data.ex.co.kr 기준) - 메서드:
client.tollfee.between_tollgates()
파라미터
| 이름 | 필수 | 타입 | 설명 |
|---|---|---|---|
startUnitCode |
R | str |
출발 영업소 코드 |
endUnitCode |
R | str |
도착 영업소 코드 |
carType |
R | code |
차종 |
discountType |
O | code |
할인 유형 (0=정상, 1=심야, 2=출퇴근, 3=경차) |
응답 필드
| 필드 | 설명 |
|---|---|
startUnitCode / startUnitName |
출발 영업소 |
endUnitCode / endUnitName |
도착 영업소 |
routeCount |
경로 수 |
totalLength |
총 거리 (km) |
travelTime |
소요시간 (분) |
tollFee |
통행료 (원) |
tollFeeNight |
심야 할인 요금 |
tollFeeRush |
출퇴근 할인 요금 |
전국 영업소 코드/명칭 목록. 코드값 동기화 시 사용.
- 포털:
data.ex.co.kr - 경로:
/openapi/business/openapibusinessunit - 공공데이터포털 대응: 영업소 위치정보 (ID
15076728) - 메서드:
client.tollfee.tollgate_list()
파라미터: 페이지네이션 파라미터만.
응답 필드
| 필드 | 설명 |
|---|---|
unitCode |
영업소 코드 (3자리) |
unitName |
영업소명 |
routeNo / routeName |
소속 노선 |
exDivCode |
운영기관 |
xValue / yValue |
좌표 (KATEC 또는 WGS84) |
headOfficeCode / branchOfficeCode |
본부/지사 코드 |
휴게소 master성 코드/명칭/노선/방향/전화번호와 일부 대표 시설 여부를 조회한다.
- 포털:
data.ex.co.kr - 경로:
/openapi/business/serviceAreaRoute - 메서드:
client.restarea.route_facilities()
파라미터
| 이름 | 필수 | 타입 | 설명 |
|---|---|---|---|
routeName |
O | str |
노선명 |
direction |
O | str |
방향 |
serviceAreaName |
O | str |
휴게소명 |
routeCode |
O | str |
노선코드 |
serviceAreaCode |
O | str |
휴게소코드 |
응답 필드
| 원본 필드 | 모델 필드 | 타입 | 설명 |
|---|---|---|---|
routeCode |
route_code |
`str | None` |
serviceAreaCode |
service_area_code |
str |
휴게소코드 |
serviceAreaCode2 |
service_area_code2 |
`str | None` |
routeName |
route_name |
`str | None` |
direction |
direction |
`str | None` |
serviceAreaName |
service_area_name |
`str | None` |
telNo |
phone_number |
`str | None` |
svarAddr |
address |
`str | None` |
brand |
brand |
`str | None` |
convenience |
convenience |
`str | None` |
maintenanceYn |
has_maintenance |
`bool | None` |
truckSaYn |
is_truck_rest_area |
`bool | None` |
batchMenu |
representative_food |
`str | None` |
- 포털:
data.ex.co.kr/data.go.kr표준 (tn_pubr_public_rest_area_api) - 경로 (data.go.kr):
https://api.data.go.kr/openapi/tn_pubr_public_rest_area_api - 메서드:
client.restarea.list_all()
파라미터 (data.go.kr 표준)
| 이름 | 필수 | 타입 | 설명 |
|---|---|---|---|
serviceKey |
R | str |
인증키 |
pageNo |
O | int |
페이지 |
numOfRows |
O | int |
건수 |
type |
O | str |
xml/json (언더스코어 없음, 표준데이터셋이라 _type 아님) |
restAreaNm |
O | str |
휴게소명 검색 |
routeNm |
O | str |
노선명 검색 |
응답 주요 필드
| 필드 | 설명 |
|---|---|
restAreaNm |
휴게소명 |
routeNm |
노선명 |
directionContent |
방향 (상/하행) |
lcLatitude / lcLongitude |
위도/경도 |
gasStnYn, lpgStnYn, evChargYn |
주유소/LPG/전기충전 여부 |
pharmacyYn, clinicYn |
약국/의료시설 |
phoneNumber |
대표전화 |
referenceDate |
데이터 기준일 |
고속도로 휴게소별 기준 시각 날씨 정보를 조회한다. latest_weather()는 같은 endpoint를 최근 시간대부터 순차 조회해 비어 있지 않은 첫 페이지를 반환하는 helper다.
- 포털:
data.ex.co.kr - 기관 URL:
http://data.ex.co.kr/openapi/basicinfo/openApiInfoM?apiId=0508 - 경로:
/openapi/restinfo/restWeatherList - 메서드:
client.restarea.weather(),client.restarea.latest_weather()
파라미터
| 이름 | 필수 | 타입 | 설명 |
|---|---|---|---|
sdate |
R | str / date / datetime |
기준일 (YYYYMMDD) |
stdHour |
R | str / int |
기준 시각 (00~23) |
응답 필드
| 원본 필드 | 모델 필드 | 타입 | 설명 |
|---|---|---|---|
sdate |
sdate |
str |
기준일 |
stdHour |
std_hour |
str |
기준 시각 |
sdate + stdHour |
observed_at |
datetime |
KST 기준 관측/제공 시각 |
unitCode |
unit_code |
str |
휴게소 코드 |
unitName |
unit_name |
str |
휴게소명 |
routeNo |
route_no |
`str | None` |
routeName |
route_name |
`str | None` |
updownTypeCode |
direction_code |
`str | None` |
xValue / yValue |
lon / lat |
`float | None` |
addr |
address |
`str | None` |
measurement |
measurement_station |
`str | None` |
weatherContents |
weather |
`str | None` |
tempValue |
temperature |
`float | None` |
humidityValue |
humidity |
`float | None` |
windValue |
wind_speed |
`float | None` |
windContents |
wind_direction_code |
`str | None` |
rainfallValue |
rainfall |
`float | None` |
rainfallstrengthValue |
rainfall_strength |
`float | None` |
newsnowValue |
new_snow |
`float | None` |
snowValue |
snow |
`float | None` |
cloudValue |
cloud |
`float | None` |
dewValue |
dew_point |
`float | None` |
-99, -99.0, -99.000000 계열 결측값은 typed 필드에서 None으로 정규화하고 원문은 raw에 보존한다.
고속도로 휴게소 내 주유소의 정유사와 유종별 가격을 조회한다.
- 포털:
data.ex.co.kr - 경로:
/openapi/business/curStateStation - 메서드:
client.restarea.fuel_prices()
파라미터
| 이름 | 필수 | 타입 | 설명 |
|---|---|---|---|
routeName |
O | str |
노선명 |
direction |
O | str |
방향 |
oilCompany |
O | str |
정유사 |
serviceAreaName |
O | str |
휴게소명 |
routeCode |
O | str |
노선코드 |
serviceAreaCode |
O | str |
휴게소코드 |
응답 필드
| 원본 필드 | 모델 필드 | 타입 | 설명 |
|---|---|---|---|
routeCode |
route_code |
`str | None` |
serviceAreaCode |
service_area_code |
str |
휴게소코드 |
serviceAreaCode2 |
service_area_code2 |
`str | None` |
routeName |
route_name |
`str | None` |
direction |
direction |
`str | None` |
oilCompany |
oil_company |
`str | None` |
lpgYn |
has_lpg |
`bool | None` |
serviceAreaName |
service_area_name |
`str | None` |
telNo |
phone_number |
`str | None` |
svarAddr |
address |
`str | None` |
gasolinePrice |
gasoline_price |
`int | None` |
diselPrice / dieselPrice |
diesel_price |
`int | None` |
lpgPrice |
lpg_price |
`int | None` |
- 포털:
data.ex.co.kr - 경로:
/openapi/business/conveniServiceArea - 메서드:
client.restarea.convenience_facilities()
응답 필드는 포털 문서와 실제 응답 간 차이가 있을 수 있어 현재는 Page[dict]로 반환한다.
파라미터
| 이름 | 필수 | 타입 | 설명 |
|---|---|---|---|
direction |
O | str |
방향 |
serviceAreaName |
O | str |
휴게소명 |
routeCode |
O | str |
노선코드 |
serviceAreaCode |
O | str |
휴게소코드 |
EX-FOOD 가격 정보. 휴게소·매장·메뉴별 가격.
- 포털:
data.ex.co.kr - 경로:
/openapi/restinfo/restMenuList(대표 명칭, 실 경로는 포털에서 확인) - 메서드:
client.restarea.food_price()
응답 필드
| 필드 | 설명 |
|---|---|
serviceAreaCode |
휴게소 코드 |
serviceAreaName |
휴게소명 |
storeCode / storeName |
매장 |
foodCode / foodName |
음식명 |
price |
가격 (원) |
recommendYn |
대표 메뉴 여부 |
여러 시설 정보 엔드포인트는 모두 비슷한 패턴.
| 메서드 | 원본 엔드포인트 (data.ex.co.kr) | 주요 응답 필드 |
|---|---|---|
restarea.parking() |
/openapi/restinfo/restParking |
total, large, small, disabled (대수) |
restarea.wifi() |
/openapi/restinfo/restWifi |
wifiYn (제공 여부) |
restarea.restroom() |
/openapi/restinfo/restRestroom |
maleStool, femaleStool (변기 수) |
restarea.disabled_facility() |
/openapi/restinfo/restDisabled |
parking, tactile, lounge |
restarea.bus_transit() |
/openapi/restinfo/restBus |
routeName, operatingHours |
공통 파라미터: 페이지네이션. serviceAreaName으로 필터링 가능.
좌표를 포함한 영업소 상세 정보. tollgate_list()보다 풍부한 메타데이터.
- 포털:
data.go.kr(ID15076728) - 메서드:
client.facility.tollgate_info()
고속도로 졸음쉼터 설치 현황.
- 포털:
data.ex.co.kr/data.go.kr - 경로:
/openapi/restinfo/drowsyShelter(대표) - 메서드:
client.facility.drowsy_shelter()
응답 필드
| 필드 | 설명 |
|---|---|
seq |
일련번호 |
installYear |
설치년도 |
routeName |
노선명 |
mileage |
이정 (km) |
direction |
방향 |
name |
졸음쉼터명 |
차로제어 시스템(LCS) 시행 구간.
- 포털:
data.go.kr(ID15001283) - 메서드:
client.facility.shoulder_lane()
응답 필드
| 필드 | 설명 |
|---|---|
divCd / divNm |
구분 코드/명 |
section |
구간 (예: "양재IC ~ 신갈JCT") |
direction |
방향 |
length |
연장 (km) |
laneOperation |
차로 운영 형태 |
한국도로공사 전자조달 계약 현황.
- 포털:
data.go.kr(ID15128076) - 메서드:
client.admin.procurement_contracts()
응답 필드
| 필드 | 설명 |
|---|---|
noticeDivCode / noticeDivName |
공고 구분 |
noticeNo |
공고번호 |
contractName |
계약명 |
contractMethod |
계약방법 |
bizRegNo |
사업자등록번호 |
contractorName |
계약업체명 |
contractAmount |
계약금액 |
contractDept / mainDept |
계약/주관 부서 |
contractDate |
계약체결일자 |
DSRC, TCS, HIPASS, VDS, RSE 등 공통코드 일괄 조회.
- 포털:
data.go.kr(ID15042751— 파일데이터 형식, OpenAPI 미제공 시 라이브러리 내장 코드 사용) - 메서드:
client.reference.common_codes()
전국 고속도로 노선 마스터.
- 포털:
data.go.kr(ID15087178기준자료) - 메서드:
client.reference.routes()
응답 필드
| 필드 | 설명 |
|---|---|
routeNo |
노선번호 (4자리) |
routeName |
도로명 |
roadGradeCode |
도로등급구분코드 |
startNodeId / endNodeId |
시작/종료 노드 ID |
shortName / displayName |
단축명/표출명 |
startName / endName |
시점명/종점명 |
freeFlowSpeed |
소통원활 기준속도 |
congestionSpeed |
정체 기준속도 |
본 문서의 일부 엔드포인트 경로(/openapi/restinfo/restWifi 등)는
포털의 JavaScript 기반 UI 특성상 외부 문서로부터 100% 검증이 어려웠습니다.
실제 라이브러리 구현 시에는 다음 절차로 확인을 권장합니다.
- https://data.ex.co.kr/dataset/datasetList/list?pn=1에서 해당 데이터셋 페이지 진입
- OpenAPI 보기 버튼으로 호출 URL 확인
- 미리보기 기능으로 응답 구조 확인
- 결과를
tests/fixtures/에 저장하고 모델/테스트 작성
엔드포인트 URL이 변경되었거나 추가된 경우 PR을 환영합니다.
KrexClient와 모든 네트워크 서비스 메서드는 native async다. 조회와 디버그에는
await, 세션 관리에는 async with 또는 await client.aclose()를 사용한다.
동기 HTTP bridge, Async 접두사 클라이언트와 aio/adebug_call 별칭은 제거했다.
reference.routes, reference.common_codes, reference.api_catalog, 파싱과 코드표,
fixture 저장 등 로컬 유틸리티는 일반 함수다. 기존 서비스 인자·모델·선행 0 코드는 유지한다.
기존 TPS 변경의 기본값을 보존한다: max_rps=5.0, 버킷 capacity=1이다.
초기 버스트 없이 송신 사이에 최소 1/max_rps 간격을 둔다. 모든 서비스는 같은 버킷을
공유하고 각 재시도·리다이렉트·debug·latest_weather의 시간대 조회에도 토큰을 소비한다.
다른 라이브러리와 같은 구현의 AsyncTokenBucket을 rate_limiter=에 주입하면
여러 클라이언트가 요청 예산을 합산한다. 주입한 버킷이 max_rps보다 우선한다.
공통 버킷 클래스 자체의 기본 capacity는 max(1, max_rps)로 초기 burst를 허용하므로
Krex의 기본 간격을 유지하는 공유 버킷도 capacity=1을 명시한다.
버킷은 한 이벤트 루프에서 사용한다. 대기 취소는 토큰을 소비하지 않고 다음 대기자를 진행시킨다.
401/403/429는 즉시 실패한다. 5xx와 HTTPX 네트워크 오류는 기존 backoff를 유지하되 각 시도마다 새 토큰을 얻는다. 인자 검증 실패와 로컬 코드 조회는 토큰을 쓰지 않는다. HTTPX 리다이렉트는 계측한다. Digest/custom Auth처럼 내부 추가 송신이 가능한 인증 세션은 첫 전송 전에 거부한다. 인증 없는 세션과 HTTPX 기본 BasicAuth를 지원한다. 사용자 정의 transport 내부의 연결 재시도는 라이브러리 밖의 동작이다.
내부 HTTP 세션은 첫 요청에서 생성하고 클라이언트 종료 시 닫는다. session에 주입한 비동기 세션은 호출자가 닫는다. 동기 get을 제공하는 세션은 거부한다. 디버그 기록은 ContextVar로 작업마다 격리하며 성공·실패·취소 뒤 복구한다. 원문으로 오류 분류·모델 파싱을 마친 후 예외와 진단 출력의 키를 마스킹한다.
사용 예제: docs/async-tps.md.
공공데이터포털 응답은 response.header/response.body와 최상위 header/body
두 형태를 지원한다. 상태 코드 판정, 항목 정규화, 페이지 정보와 원문 보존은 동일하다.
parse_rest_area_weather을 패키지 root에서 제공한다. 네트워크 endpoint를 추가하지 않으며
공개 입력·DTO·예외와 신뢰 경계를 따른다.