관세청

관세청 수출입총괄 (수출입 무역통계)

관세청 수출입총괄(getNewtradeList, XML 원본을 JSON으로 변환 제공). 인증키 없이 GET /api/trade로 바로 호출(조회기간 필수). 서버에 data.go.kr 인증키 등록 완료 — 바로 호출 가능. 월별 국가 전체 수출/수입 건수·금액(달러)·무역수지를 제공한다.

⚡ 수출입총괄 간편 호출

GET /api/trade?strtYymm=202601&endYymm=202603

수출입·무역통계가 필요하면 이 주소를 먼저 사용. 인증키 불필요, strtYymm/endYymm(YYYYMM) 필수. 서버 키 등록 완료 — 바로 호출 가능.

에이전트가 얻을 수 있는 정보

year(연월 YYYYMM), expCnt(수출건수), expDlr(수출액 달러), impCnt(수입건수), impDlr(수입액 달러), balPayments(무역수지 달러)
월별 수출입 규모·무역수지 조회, 기간별 무역통계 집계

활용 사례

특정 월의 수출입 건수·금액 조회
기간(시작월~종료월) 수출입 추이 조회
무역수지(수출액-수입액) 확인

등록 API (1)

수출입총괄 목록조회 getNewtradeList

원본은 XML, 간편 API가 JSON으로 변환. 시작월/종료월(YYYYMM) 필수. 국가 전체 총계만 제공(품목·국가 필터 없음). 응답 마지막에 year="총계" 합계 행 포함

strtYymm 필수 — 시작 연월 YYYYMM 예: 202601
endYymm 필수 — 종료 연월 YYYYMM 예: 202603
numOfRows 옵션 — 한 페이지 결과 수 1~100 (기본 12) 예: 12
pageNo 옵션 — 페이지 번호 1~100 (기본 1) 예: 1

출력: totalCount(전체 건수), items[](year/expCnt/expDlr/impCnt/impDlr/balPayments)

호출 한도: 일 10,000회 (data.go.kr 개발계정 일일 10,000회)

인증·비용·약관

인증 방식	ServiceKey — data.go.kr 인증키. 프록시 서버에만 보관하며 에이전트에게 노출하지 않는다. 에이전트는 우리 간편 API(/api/trade)만 호출한다.
비용	무료. 개발계정 자동승인
이용허락	공공데이터 (data.go.kr 활용신청 조건 준수, 출처표시). 이용허락 제한 없음
재배포	허용 (출처표시 필수)
약관 확인일	2026-10-16
활용신청	data.go.kr 로그인 → 관세청_수출입총괄(GW) 활용신청 → 인증키 발급 (개발계정 자동승인) 포털 바로가기
운영 상태	운영 중
최종 확인일	2026-10-16

에이전트 호출 방법

우리 프록시를 통해 호출합니다. 인증이 필요한 기관은 헤더 X-Agent-Token이 있어야 합니다(법령 조회 target=law와 무료 API는 토큰 없이 호출 가능). 토큰 발급 안내는 /agencatalog/register/를 확인하세요. 전체 서비스 목록은 /agencatalog/api/services.json을 참조하세요.

기계용 JSON 스키마

{
  "service": "customs-trade-gw",
  "name": "관세청 수출입총괄 (수출입 무역통계)",
  "provider": "관세청",
  "apis": [
    {
      "id": "getNewtradeList",
      "name": "수출입총괄 목록조회",
      "params": [
        {
          "name": "strtYymm",
          "required": true,
          "example": "202601",
          "desc": "시작 연월 YYYYMM"
        },
        {
          "name": "endYymm",
          "required": true,
          "example": "202603",
          "desc": "종료 연월 YYYYMM"
        },
        {
          "name": "numOfRows",
          "required": false,
          "example": "12",
          "desc": "한 페이지 결과 수 1~100 (기본 12)"
        },
        {
          "name": "pageNo",
          "required": false,
          "example": "1",
          "desc": "페이지 번호 1~100 (기본 1)"
        }
      ]
    }
  ],
  "proxy_call": "POST /agencatalog/api/call",
  "attribution": "출처: 관세청 수출입총괄(공공데이터포털 data.go.kr)"
}

에러 대처

모든 응답은 JSON입니다. 실패 시 {"ok": false, "error": {"code", "message"}} 형태로 반환됩니다. code별 대처 방법은 아래와 같습니다.

invalid_token	403. `X-Agent-Token` 헤더가 없거나 잘못됨. /agencatalog/register/ 안내로 토큰을 발급받아 헤더에 담아 재호출하세요.
throttle	429. 초당 1회 제한 초과. 응답의 `retry_after`(초)만큼 대기 후 순차 재시도하세요. 병렬 호출은 안 됩니다.
agent_limit / institution_limit	429. 일일 한도 초과. `retry_after_seconds` 이후 재개하세요.
upstream_limit	429. 기관 원본 API가 한도 초과를 반환했습니다. 잠시 후 재시도하세요.
unknown_service	404. 등록되지 않은 서비스. services.json에서 정확한 service/endpoint 이름을 확인하세요.
not_found	404. 잘못된 경로. `POST /agencatalog/api/call`를 쓰는지 확인하세요.

이용 시 주의사항

기관 API 키는 서버에만 보관됩니다. 직접 키를 요청하는 클라이언트는 이 경로를 사용할 수 없습니다.
기관별 일일 한도가 있습니다. 한도 초과 시 429를 반환하고 추가 호출을 차단합니다.
기관 API 장애·한도 초과 시 오류가 전달됩니다. 재시도 전에 응답의 error 필드를 확인하세요.
출처 표기: 출처: 관세청 수출입총괄(공공데이터포털 data.go.kr)

마지막 확인: 2026-10-16

AI 크롤러 · 수집 기록