API 문서
기본 URL: https://api.ondata.kr/v1
이용 가능한 API 상품
고객 콘솔의 API 서비스에서 승인·개통된 상품마다 별도의 서비스 키를 사용합니다. 아래 목록에는 현재 운영 상태로 공개된 상품만 표시됩니다.
| 데이터팩 | API 상품 | 버전 | 엔드포인트 |
|---|---|---|---|
| 기업·사업자 | 기업 디렉터리 API 공개 기업 식별자와 공시 대상 기업 정보를 표준화해 제공합니다. | v1 | GET /v1/datasets/business-directory/items |
| 글로벌 기업 | 글로벌 법인 LEI API LEI 또는 법인명으로 글로벌 법인 식별·등록정보를 조회합니다. | v1 | GET /v1/global/entities |
| 글로벌 기업 | 미국 SEC 기업 공시 API SEC EDGAR 공시를 CIK, 기업명, 서식과 접수기간으로 조회합니다. | v1 | GET /v1/global/sec/filings |
| global-compliance | 글로벌 제재·거래위험 API OFAC·UN 제재대상을 이름, 국가, 프로그램, 유형과 원천으로 조회합니다. | v1 | GET /v1/compliance/sanctions |
| 글로벌 경제 | 글로벌 국가·경제지표 API 국가·지표·연도별 인구와 주요 경제·사회지표를 조회합니다. | v1 | GET /v1/global/indicators |
| 글로벌 환경 | 글로벌 지진 이벤트 API 전 세계 지진을 발생일, 최소규모와 쓰나미 여부로 조회합니다. | v1 | GET /v1/global/earthquakes |
| 글로벌 환경 | 글로벌 자연재난 이벤트 API NASA EONET 자연현상을 카테고리, 상태와 기간으로 조회합니다. | v1 | GET /v1/global/natural-events |
| 글로벌 국가 | 글로벌 국가 기본정보 API 국가코드, 지역, 소득그룹, 수도와 좌표를 조회합니다. | v1 | GET /v1/global/countries |
| 글로벌 시장 | 글로벌 기준환율 API 유로 기준 주요 통화의 일별 기준환율과 역산값을 조회합니다. | v1 | GET /v1/global/exchange-rates |
| global-procurement | 글로벌 공공조달 API EU TED 공고를 키워드, 국가, CPV, 기간과 낙찰 여부로 조회합니다. | v1 | GET /v1/global/procurement/notices |
| global-safety | 글로벌 제품 리콜·안전조치 API openFDA 의약품·의료기기·식품 리콜을 유형, 분류, 업체, 국가, 상태와 보고기간으로 조회합니다. | v1 | GET /v1/safety/recalls |
| global-security | 사이버 취약점·악용위험 API CISA KEV·NVD 취약점을 CVE, 공급사, 제품, 랜섬웨어 연관과 기한으로 조회합니다. | v1 | GET /v1/security/vulnerabilities |
| 주소·지역 | 주소·행정구역 API 정제된 주소·행정구역 코드와 표준 식별자를 제공합니다. | v1 | GET /v1/datasets/address-admin-code/items |
| 경제·운영 | 공공·시장 지표 API 공공통계와 시장 지표를 공통 단위로 정리해 제공합니다. | v1 | GET /v1/datasets/market-indicators/items |
인증
Authorization: Bearer YOUR_API_KEY
상태 확인을 제외한 모든 요청에 활성 API 키가 필요합니다. 고객사 승인, 구독, 데이터셋 권한과 API 서비스 개통 상태가 함께 적용됩니다.
키와 서비스에 허용 IP/CIDR을 설정한 경우 두 제한을 모두 통과해야 합니다. 키는 용도별로 분리하고 유출이 의심되면 고객 콘솔에서 즉시 교체하세요.
엔드포인트
| 메서드 | 경로 | 인증 | 설명 |
|---|---|---|---|
| GET | /health | 불필요 | 서비스 상태 |
| GET | /datasets | 필요 | 구독에서 이용 가능한 데이터셋 |
| GET | /datasets/{slug} | 필요 | 출력 형식·필드 스키마·출처 정보 |
| GET | /datasets/{slug}/items | 필요 | 검수 승인된 수집 결과 |
| GET | /datasets/{slug}/records | 필요 | 정규화 레코드 cursor 목록 |
| GET | /datasets/{slug}/records/{record_key} | 필요 | 정규화 레코드 단건 |
| GET | /address/search | 필요 | 공식 도로명주소 실시간 검색 |
| GET | /global/countries | 필요 | 글로벌 국가 기본정보 검색 |
| GET | /global/indicators | 필요 | 국가·경제지표 조회 |
| GET | /global/exchange-rates | 필요 | ECB 유로 기준환율 조회 |
| GET | /global/entities | 필요 | GLEIF 글로벌 법인 검색 |
| GET | /global/earthquakes | 필요 | 전 세계 지진 이벤트 조회 |
| GET | /assets/{id} | 필요 | 승인 결과에 연결된 이미지 |
수집 결과 조회
limit은 1~100, after_id는 다음 페이지 시작점을 지정합니다.
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.ondata.kr/v1/datasets/address-admin-code/items?limit=50&after_id=0"정규화 레코드 조회
첫 요청은 cursor 없이 호출하고, 다음 요청에는 응답의 meta.next_cursor를 그대로 전달합니다. cursor 내부값을 직접 만들거나 수정하지 마세요.
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.ondata.kr/v1/datasets/business-directory/records?limit=50"도로명주소 검색
주소·행정구역 API가 개통된 고객만 사용할 수 있습니다. 검색 결과는 일정 시간 캐시되어 외부 원천 장애와 호출비용을 줄입니다.
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.ondata.kr/v1/address/search?query=세종대로%20110&limit=10"이미지 내려받기
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.ondata.kr/v1/assets/123" \
--output asset-123.jpg응답의 attribution과 license_url은 고객 화면·결과물에서 요구되는 출처표시에 사용해야 합니다.
호출 한도와 오류
서비스 응답에는 X-RateLimit-Limit, X-RateLimit-Remaining, X-Monthly-Limit, X-Monthly-Remaining 헤더가 포함됩니다. 429 응답의 Retry-After도 확인하세요.
| 상태 | 코드 | 대응 |
|---|---|---|
| 401 | UNAUTHORIZED | 키 원문·상태·만료 확인 |
| 403 | FORBIDDEN / IP_NOT_ALLOWED | 서비스 개통·데이터셋 권한·허용 IP 확인 |
| 422 | INVALID_REQUEST | 검색어, cursor와 요청값 확인 |
| 429 | RATE_LIMITED / SERVICE_QUOTA_EXCEEDED | 재시도 간격 또는 월 한도 조정 |
| 503 | SERVICE_UNAVAILABLE | 잠시 후 재시도하고 지속되면 고객지원 문의 |