이용 가이드
?
역할 안내
표준데이터
OID
물리 아키텍처
Open API

빠른 시작 — 처음이라면 이 순서로

명세서 확인 → 토큰 준비 → 호출까지, 세 단계면 충분합니다.

1. 명세서 확인

명세서에서 API 경로·메서드·요청 형식을 확인합니다.

정보공유 › Open API

2. 토큰 준비

발급을 신청하고, 승인되면 토큰 키를 확인합니다.

정보공유 › Open API › 내 API 토큰

3. 호출하고 확인

Authorization 헤더로 요청하고 응답을 확인합니다.

API 요청 › JSON·RDF 응답
1 / 4

이용 흐름

명세서에서 제공 범위를 확인하고, 토큰을 준비한 뒤, 인증 헤더로 표준데이터를 조회하는 흐름으로 이용합니다.

1

명세서 확인

Open API

제공 API와 요청 형식을 확인합니다.

2

토큰 준비

사용자

발급 신청과 승인 이력을 확인합니다.

3

API 요청

연계시스템

경로·파라미터·인증 헤더를 구성합니다.

4

결과 확인

Open API

목록은 JSON, 상세는 RDF 로 받고 접근 로그가 남습니다.

분류 탭과 API 목록·상세가 나뉜 실제 Open API 명세서 화면
▲ 제공 범위와 엔드포인트를 확인하는 화면 · 클릭하면 크게 볼 수 있습니다
여기서 시작합니다 정보공유 › Open API → 로그인 없이 이용

확인할 것

  • 제공 범위 — 메시지·데이터 프레임·데이터 엘리먼트, 그리고 OID
  • 호출 기준 — 공개 데이터 API 는 모두 GET 요청이며 주소 끝의 슬래시(/)까지 적습니다
  • 토큰 필요 여부 — 모든 호출에 인증 토큰이 필요합니다

받을 수 있는 데이터

메시지
GET /api/v1/messages/ · /api/v1/messages/{id}/

서비스·시스템 간에 주고받는 최상위 단위입니다. 필드마다 데이터 프레임이나 데이터 엘리먼트를 가리킵니다.

데이터 프레임
GET /api/v1/data-frames/ · /api/v1/data-frames/{id}/

데이터 엘리먼트나 다른 데이터 프레임을 필드로 묶은 복합 단위입니다.

데이터 엘리먼트
GET /api/v1/data-elements/ · /api/v1/data-elements/{id}/

더 나누지 않는 기본 값 단위입니다. 데이터 유형·제약 표현식·단위를 정의합니다.

OID
GET /api/v1/oids/ · /api/v1/oids/{id}/

표준데이터에 붙는 국제 객체식별자입니다. 점 표기·상위·하위 OID와 연결된 표준데이터를 줍니다.

메시지 → 메시지 필드 → 데이터 프레임 → 데이터 프레임 필드 → 데이터 엘리먼트 순으로 이어집니다. 목록은 JSON, 메시지·데이터 프레임·데이터 엘리먼트 상세는 RDF 로 받습니다. OID 는 목록·상세 모두 JSON 이고, 상세의 instances 에서 연결된 메시지 등의 상세 주소로 이어 부를 수 있습니다.

이렇게 활용합니다

메시지 구조 가져오기

우리 시스템에 메시지 정의 — 필드·M/O·최대 반복과 그 아래 데이터 프레임·데이터 엘리먼트 — 를 반영합니다.

GET /api/v1/messages/?q=이름 → GET /api/v1/messages/{id}/?depth=full
ASN.1 정의 확인

인코딩·디코딩을 개발할 때 데이터 프레임·메시지의 ASN.1 코드와 인코딩 방식(UPER 등)을 받습니다.

GET /api/v1/data-frames/{id}/ → kadif:definitionText · sdo:encodingType
OID로 표준데이터 찾기

점 표기 OID만 알 때 어떤 표준데이터인지 찾아 그 상세로 이어 갑니다.

GET /api/v1/oids/?q=1.2.410.200053.2.1.61 → GET /api/v1/oids/{id}/ → instances[].url
변경 영향 범위 확인

데이터 엘리먼트가 바뀔 때 그 엘리먼트를 쓰는 상위 데이터 프레임·메시지를 확인합니다.

GET /api/v1/data-elements/{id}/ → 활용·연결(상위 프레임·메시지)

응답이 예상과 다르다면

응답 코드를 선택하면 먼저 확인할 내용을 볼 수 있습니다.

200 정상 처리

목록·OID 상세는 JSON, 그 밖의 상세는 RDF 를 반환합니다. 목록이 비어 있다면 검색어(q)에 맞는 공개 항목이 있는지 확인해 주세요.

400 요청 값 확인

depth 에 full 이 아닌 값을 넣었는지 확인하세요. depth 를 빼거나 full 로 바꿉니다.

401 토큰 확인

Authorization 헤더에 Token 과 토큰 키가 포함되어 있는지 확인하세요. 만료·회수된 토큰이나 비활성 계정으로는 호출할 수 없습니다.

404 주소와 ID 확인

명세서의 경로와 실제 요청 주소를 비교하세요. {id} 자리표시자를 실제 값으로 바꾸었는지, 대상이 공개 항목인지, 관리자가 제공을 중지한 API 인지 확인해 주세요.

406 형식 확인

상세 조회에 Accept: application/json 처럼 지원하지 않는 형식만 보냈는지 확인하세요. 4단계의 형식 표 값이나 ?format= 을 씁니다.

429 호출 한도 확인

분당·하루 호출 한도를 넘었습니다. 응답 헤더 Retry-After(초)만큼 기다린 뒤 다시 호출하세요.

API별 응답 명세 확인 ↗

알아두면 좋은 용어

화면에서 자주 만나는 다섯 가지입니다.

토큰(Token) Open API 호출에 사용하는 인증 키로, 발급 신청 후 승인되면 확인할 수 있습니다. 유효기간은 발급일로부터 3650일입니다.
API 인증 Authorization 헤더에 토큰을 담아 호출 사용자를 확인하는 절차입니다.
RDF 데이터를 '항목 — 속성 — 값' 세 칸 문장으로 적는 웹 표준 형식입니다. 상세 조회가 이 형식으로 응답합니다.
JSON 목록 조회가 쓰는 표준 데이터 형식입니다.
호출 한도 토큰마다 짧은 시간에 보낼 수 있는 요청 수입니다. 현재 분당 60회 · 하루 1,000회입니다.

추가로 확인이 필요한 내용은 Q&A로 남겨 주세요.

사용 신청 · 문의
한국지능형교통체계협회 주관연구기관신영섭 선임연구원 · diosix@itskorea.kr
㈜지슨 공동연구기관김건명 프로 · gmkim@gitsn.com

코드 직접 복사

자동 복사를 사용할 수 없습니다. 아래 코드를 선택해 복사해 주세요.

화면 캡처 확대 보기

이미지나 바깥 영역을 다시 누르거나 Esc 키를 누르면 닫힙니다.