TAGOBus-API

TAGOBus-API는 국가대중교통정보센터(TAGO)에서 제공하는 버스 정보 API를 Python에서 쉽게 사용할 수 있도록 만든 비공식 Python 라이브러리입니다.

설치

Unoffical-TAGO-API는 Python 3.10 이상을 지원합니다.

버전 정책

버전은 MAJOR.MINOR.PATCH 형식을 사용합니다.

• MAJOR: 하위 호환되지 않는 공개 API 변경
• MINOR: 하위 호환되는 기능 추가 및 deprecation
• PATCH: 하위 호환되는 버그 수정

현재 개발 버전은 0.14.0입니다. Deprecated Client 메서드와 기존 예외 alias는 1.0.0에서 제거할 예정입니다.

pip install Unoffical-TAGO-API

사용 전 준비사항

본 API를 사용하기 위해서는 공공데이터포털에서 TAGO 버스 관련 데이터를 활용 신청해야 합니다.

국토교통부_(TAGO)_버스정류소정보

국토교통부_(TAGO)_버스노선정보

국토교통부_(TAGO)_버스도착정보

국토교통부_(TAGO)_버스위치정보

서비스 키는 공공데이터포털 마이페이지에서 Decoding 키를 사용하세요.

주요 매개변수

라이브러리의 공개 API는 snake_case 매개변수를 사용합니다.

사용법

1. 클라이언트 생성

from tagoapi import TAGOClient

client = TAGOClient(service_key="YOUR_SERVICE_KEY")

2. 서비스 가능 도시 조회

cities = client.cities.list()

for city in cities:
    print(city.city_code, city.city_name)

3. 노선과 정류소 조회

routes = client.routes.list(city_code=22, route_no="북구1")

for route in routes:
    print(route.route_id, route.route_no)

stations = client.routes.list_stations(
    city_code=22,
    route_id=routes.items[0].route_id,
    num_of_rows=100,
)

print(stations.total_count)
for station in stations:
    print(station.station_id, station.station_name)

4. 오프라인 정류소 검색

StationCatalog는 패키지에 포함된 공식 정류소 스냅샷을 사용하므로 서비스 키나 네트워크 호출 없이 검색할 수 있습니다.

from tagoapi import StationCatalog

catalog = StationCatalog()

stations = catalog.search("중앙역", city_code=25)
station = catalog.get("DJB8001793")

• search(keyword, city_code=None, limit=100)은 정류소 이름의 부분 일치 결과를 원본 데이터 순서로 반환합니다.
• limit=None을 지정하면 일치하는 결과를 모두 반환합니다.
• get(station_id)은 정류소 ID가 없으면 None을 반환합니다.
• 데이터는 첫 조회 때 메모리에 읽히며 같은 인스턴스의 이후 조회에서 재사용됩니다.

내장 데이터는 공공데이터포털의 국토교통부_전국 버스정류장 위치정보 파일을 기반으로 합니다. 스냅샷 파일 기준일은 2025-06-15이고 CSV의 정보수집일은 2024-10-28입니다. 원본 데이터는 연간 갱신되므로 최신 변경이 즉시 반영되지 않을 수 있습니다.

목록 Resource는 TagoPage를 반환합니다.

page.items        # 현재 페이지의 모델 목록
page.page_no      # 현재 페이지 번호
page.num_of_rows  # 요청한 페이지 크기
page.total_count  # 전체 결과 수

TagoPage는 반복과 len()을 지원하므로 모델 목록처럼 순회할 수 있습니다.

5. 도메인 클래스

클라이언트와 Resource는 다음과 같은 도메인 객체를 반환합니다.

• CityCode: 서비스 가능 도시
• Station: 정류소 정보
• Vehicle: 버스 차량 정보
• Route: 버스 노선 정보
• ArrivalInfo: 버스 도착 정보

도메인 객체 필드

BaseModel

도메인 객체의 공통 상위 클래스이며 다음 메서드를 제공합니다.

obj.to_dict()          # 객체 → dict 변환
Station.from_dict(raw) # TAGO 응답 dict → Station 변환

CityCode

Station

Route

ArrivalInfo

Vehicle

지원 Resource API

기존 client.get_route_by_no() 등의 메서드는 호환성을 위해 유지되지만 DeprecationWarning을 발생시키며 1.0.0에서 제거될 예정입니다.

관계 데이터 조회

모델의 속성 접근은 네트워크 요청을 발생시키지 않습니다. 노선의 정류소나 정류소의 노선처럼 추가 조회가 필요한 데이터는 client.routes, client.stations 등의 Resource 메서드를 명시적으로 호출해야 합니다.

예외 처리

from tagoapi.exceptions import (
    RequestLimitExceededError,
    ServiceKeyNotRegisteredError,
    TagoAPIError,
)

try:
    cities = client.cities.list()
except ServiceKeyNotRegisteredError:
    print("서비스 키를 확인해주세요.")
except RequestLimitExceededError:
    print("요청 제한 횟수를 초과했습니다.")
except TagoAPIError as error:
    print(error)

개발 및 테스트

일반 테스트는 외부 네트워크를 사용하지 않습니다.

python -m pytest

실제 공공데이터 API 스모크 테스트는 명시적으로 활성화해야 합니다. 기본 검증 대상은 도시 코드 25, 노선 번호 100이며 환경변수로 변경할 수 있습니다.

TAGO_RUN_INTEGRATION=1 \
TAGO_API_KEY="YOUR_SERVICE_KEY" \
TAGO_TEST_CITY_CODE=25 \
TAGO_TEST_ROUTE_NO=100 \
python -m pytest -m integration tests/integration

오류 및 이슈

버그 제보 또는 기능 요청은 GitHub 이슈에 등록해주세요.