해운 공공데이터로 내 업무 도구 만들기

⚓

이 페이지에서 할 일

나라에서 무료로 열어 둔 해운 데이터(선박 입출항, 컨테이너, 운임 등)를 클로드 코드로 불러와서, 내 업무에 쓰는 화면과 리포트를 만들어 봅니다.

공공데이터포털에서 쓰고 싶은 데이터를 신청합니다 (1분, 무료)

내 인증키를 복사해 둡니다

클로드 코드에게 만들어 달라고 말합니다

준비물: 공공데이터포털 회원 계정 (가입하기), 클로드 코드

먼저 알아 둘 말

말	쉽게 말하면
API	데이터를 받아 오는 창구예요. 사람이 웹사이트를 눌러 보는 대신, 프로그램이 이 창구에 요청해서 데이터를 받아 옵니다.
활용신청	"이 데이터 쓰겠습니다"라고 신청하는 것이에요. API마다 한 번씩 해야 하고, 해운 API는 모두 신청하면 바로 승인돼요.
인증키	내가 신청한 사람이 맞다는 걸 보여 주는 긴 비밀번호예요. 계정에 하나라서, API를 여러 개 신청해도 같은 키를 씁니다.
호출부호	배마다 붙은 고유 번호예요(예: D5YU8). 여러 API에 같이 나와서, 서로 다른 데이터를 한 배 기준으로 이어 붙일 때 씁니다.
항만청 코드	항만을 가리키는 숫자 3자리예요. 부산 020, 광양 622처럼 씁니다. 아래 표에 전부 있어요.

1. 데이터 신청하기 (API 하나에 1분)

공공데이터포털에 로그인한 상태에서 따라 하세요. 그림은 "선사부호 업체명" API 예시지만, 다른 API도 순서가 똑같아요.

① 찾기

공공데이터포털 검색창에 API 이름을 넣고, 결과에서 이름을 누르세요.

아래 표에 있는 API 이름을 눌러도 같은 화면으로 바로 갑니다.

② 활용신청 누르기

상세 화면 위쪽의 파란 활용신청 버튼을 누르세요. 새 탭에 신청서가 열려요.

③ 신청서 쓰기

활용목적: 기타를 고르세요.

설명칸: 무엇에 쓸지 한두 줄 적으세요. 예) 해운 업무 AI 교육 실습. 입출항 자료를 정리하는 도구를 만든다.

아래로 내려서

쓸 기능의 네모칸을 모두 체크하고

이용허락범위 동의합니다를 체크한 뒤

파란 활용 신청하기 버튼을 누르세요.

④ 승인됐는지 확인

오른쪽 위 마이페이지 → 데이터 활용 → Open API → 활용신청 현황으로 가세요. 신청한 API 앞에 [승인] 이 보이면 끝이에요.

⑤ 인증키 복사하기

[승인]된 API 이름을 누르면 아래쪽에 두 가지가 보여요.

End Point: 데이터를 받아 오는 주소

일반 인증키: 내 비밀번호 같은 키. 통째로 복사해 두세요.

🔒

인증키는 비밀번호처럼 다뤄 주세요.

단톡방, 노션, 발표 자료, 깃허브에 붙여 넣지 마세요. 다른 사람이 내 이름으로 데이터를 쓰게 됩니다. (위 그림도 키를 가렸어요)

2. 인증키를 클로드 코드에게 알려 주기

인증키는 .env라는 파일에 넣어 두고 씁니다. 파일 만들기부터 키 넣기까지 클로드 코드에게 맡기세요.

1단계 · 클로드 코드에게 부탁하기

아래 문장을 복사해서, 끝에 ⑤에서 복사한 인증키를 붙여 넣고 보내세요.

Plain Text

이 폴더에 .env 파일을 만들고, DATA_GO_KR_KEY 값으로 아래 인증키를 넣어 줘. .env는 깃에 올라가지 않게 .gitignore에도 넣어 줘.
인증키: 여기에_복사한_인증키

2단계 · 됐는지 보기

VS Code 왼쪽 탐색기에 .env 파일이 생겨요. 눌러서 열어 보면 이렇게 한 줄이 들어 있어요.

Plain Text

DATA_GO_KR_KEY=내_인증키

키가 제대로 동작하는지도 바로 확인해 보세요. 키를 복사하다 글자가 빠졌거나 활용신청이 아직 안 됐으면 여기서 미리 알 수 있어요.

Plain Text

이 인증키로 선박운항정보 API를 한 번 불러서 부산항 어제 입항 선박 3척만 보여 줘. https://www.data.go.kr/data/15006353/openapi.do

🔗

문장 끝의 링크는 무엇인가요?

공공데이터포털에서 그 API를 설명하는 상세 화면 주소예요. 1번 ①에서 이름을 누르면 나오는 바로 그 화면이에요.

이 화면에는 무엇을 넣어서 요청하고(항만 코드, 날짜 등), 무엇이 돌아오는지(선명, 입항 시각 등) 적혀 있어요. 클로드가 이걸 읽고 코드를 짜서, 주소를 주면 헤매지 않고 한 번에 맞혀요.

다른 API를 쓸 때는 이렇게 주소를 구하세요.

이 페이지 아래 표에서 API 이름을 누르거나, 공공데이터포털에서 검색해 연 뒤

브라우저 위쪽 주소창의 주소를 통째로 복사해요. https://www.data.go.kr/data/숫자/openapi.do 모양이에요.

클로드에게 보낼 문장 끝에 붙여 넣으면 돼요.

배 이름이 나오면 준비 끝이에요. 오류가 나오면 아래 5. 막힐 때를 보세요.

그다음부터는 클로드 코드에게 무엇을 만들지 말할 때 맨 앞에 이 문장을 붙이세요.

Plain Text

공공데이터포털 인증키는 .env 파일의 DATA_GO_KR_KEY에 있어. 코드에 키를 직접 쓰지 마.

처음 쓰는 API라면 위에서 처럼 공공데이터포털 상세 화면 주소도 같이 주세요. 아래 3번 표의 API 이름에 걸린 링크가 바로 그 주소예요.

3. 무엇을 만들 수 있나

선박운항정보 하나만 신청해도 되는 것

먼저 해양수산부_선박운항정보 하나만 신청하세요. 항만별로 어떤 배가 언제 들어오고 나갔는지(선명, 선종, 선석, 전출항지, 차항지, 신고 대리점 등)를 알려 주는 API예요. 이것 하나로 아래 6가지를 다 만들 수 있어요.

만들 것	무엇을 보나	클로드 코드에게 이렇게 말하세요
① 항만 입출항 조회 화면	항만과 기간을 고르면 어떤 배가 들고 났는지 표와 그래프로 보여 줘요	"선박운항정보 API로 부산항 최근 1주 입출항을 보는 웹을 만들어 줘. 항만과 기간을 고를 수 있게 하고, 선종별 그래프도 넣어 줘"
② 우리 배 아침 브리핑	내가 맡은 배들의 어제 입출항과 오늘 출항 예정을 매일 아침 한 장으로 정리해요	"호출부호 목록 파일을 읽어서 어제와 오늘 입출항을 한 장으로 요약해 줘. 매일 아침 8시에 자동으로 돌게 해 줘"
③ 선석 혼잡 현황	부두(선석)마다 배가 몇 척 들어왔고, 평균 몇 시간 머물렀는지 봐요	"광양항 지난달 선석별 입항 건수와 평균 머문 시간을 표로 만들어 줘"
④ 대리점별 실적 순위	입출항 신고를 가장 많이 한 대리점과 우리 회사 순위를 봐요	"부산항 이번 달 신고업체별 입항 건수 상위 20곳을 막대그래프로 보여 줘"
⑤ 항로 흐름 분석	배가 어디서 와서 어디로 가는지, 지난달보다 늘어난 항로는 어디인지 봐요	"울산항 외항선의 전출항지와 차항지 조합 상위 15개를 지난달과 비교해 줘"
⑥ 주간 항만 동향 리포트	매주 월요일, 주요 항만의 입출항을 지난주와 비교한 보고서를 받아요	"부산·광양·울산·인천의 지난주 입출항을 비교하는 주간 리포트를 만들어 줘. 매주 월요일 아침에 자동으로 만들어지게 해 줘"

이렇게 만들면 ①은 아래 같은 화면이 나와요. 완성본을 바로 써 볼 수 있어요 → haeun-vessel-search.vercel.app

항만과 기간을 고르고 조회를 누르면 돼요. 처음 열 때는 10초 정도 걸릴 수 있어요.

API를 2개 이상 신청하면 되는 것

API 여러 개를 호출부호나 기간으로 이어 붙이면 더 깊이 볼 수 있어요. 필요한 API를 모두 신청한 뒤 해 보세요.

만들 것	필요한 API (눌러서 활용신청)	무엇을 보나	클로드 코드에게 이렇게 말하세요
⑦ 입출항 + 배 제원	선박운항정보 선박제원정보 서비스	들어온 배의 IMO번호, 길이, 흘수, 건조일을 붙여서 큰 배와 오래된 배가 얼마나 되는지 봐요	"선박운항정보로 부산항 이번 주 입항 선박을 불러오고, 호출부호로 선박제원정보를 조회해서 IMO번호·길이·건조일을 붙여 줘. 건조 20년이 넘은 배의 비율도 보여 줘"
⑧ 배별 컨테이너 양·적하	선박운항정보 외항컨테이너반출입정보	한 번 들어온 배가 컨테이너를 얼마나 내리고 실었는지 봐요	"광양항(622) 이번 주 입항 선박 목록을 만들고, 배마다 입항연도·입항횟수·호출부호로 외항컨테이너반출입정보를 조회해서 양하·적하 컨테이너 수를 표에 붙여 줘"
⑨ 운임 비교표	화물운임공표정보 신청 없이 보는 자료: KCCI 운임지수	같은 항로에서 선사마다 공표한 운임을 컨테이너 크기별로 비교하고, 시장 운임지수와 나란히 봐요	"화물운임공표정보에서 부산→상하이 항로의 최근 3개월 공표 운임을 선사별·컨테이너 크기별 표로 만들고, KCCI 페이지의 중국 항로 지수와 같은 그래프에 그려 줘"
⑩ 월간 물동량 대시보드	항만별 선박입출항실적 통계 수출입 컨테이너처리실적 통계 (국가별로도 보려면) 국가별 컨테이너처리실적 통계	항만별 입출항과 컨테이너 처리량이 달마다 어떻게 바뀌는지 봐요	"항만별 선박입출항실적 통계와 수출입 컨테이너처리실적 통계를 2025년 1월부터 지금까지 불러서, 부산·광양·울산의 월별 추이를 한 화면 대시보드로 만들어 줘"
⑪ 항만 날씨 위험 알림	선박운항정보 항만해양지수 내일의 운항예보	우리 배가 들어갈 항만의 바다 상태가 나쁘면 아침 브리핑 맨 위에 알려 줘요	"②의 아침 브리핑에 항만해양지수를 붙여 줘. 오늘 입출항 예정인 항만의 바다 상태가 나쁘면 맨 위에 경고로 보여 줘"
⑫ 인천항 선석 일정표	인천항 선석 이용 정보 인천항 선박 제원 정보	인천항 부두마다 어떤 배가 언제 붙는지 달력처럼 봐요	"인천항 선석 이용 정보를 불러서 부두별 접안 일정을 주간 달력으로 보여 주고, 배 이름을 누르면 인천항 선박 제원이 뜨게 해 줘"

💡

내 업무에 맞게 바꾸는 법: 예시 문장에서 항만 이름, 기간, 보고 싶은 항목만 바꿔서 말하면 돼요.

예) "부산항" → "광양항", "이번 주" → "지난 3개월", "선종별" → "국적별"

완성 예시 · 해운 세계지도 대시보드

🌏

바로 열어 보기 → haeun-vessel-map.vercel.app

공공데이터 API 2개를 클로드 코드로 이어 붙여 만든 대시보드예요. 실제 데이터로 돌아가고, 5분마다 새로 불러와요.

처음 열면 20초 정도 걸릴 수 있어요. 서버가 잠에서 깨는 시간이에요.

쓴 API

해양수산부_선박운항정보: 어느 항구에서 와서 어디로 가는지, 선종·대리점·출항 예정

울산항만공사_항내 선박위치정보: 울산항 주변 배의 위도·경도, 속력, 정박·항해 상태

해양수산부_선박위치정보(연안AIS) 통계: 한국 연안을 약 200개 해역으로 나눠 시간마다 잡힌 배 척수 (한 시간 늦게 올라옴)

세계 화면 · 우리 항만에 어디서 배가 오나

항만과 기간을 고르면, 그 항만에 들어온 외항선이 출발한 항구를 선으로 이어요. 배가 많이 온 항구일수록 선이 굵어요. 나갈 곳을 누르면 다음 기항지 쪽으로 바뀌어요.

울산항 화면 · 지금 배가 어디 있나

울산항 확대를 누르면 배 한 척 한 척이 점으로 보여요.

초록은 항해 중, 주황은 앵커리지(묘박지)에서 대기 중, 파랑은 부두에 계류 중이에요.

점을 누르면 선명, 선종, 출발지, 대리점, 출항 예정 시각이 나와요. 두 API를 호출부호로 이어 붙였기 때문이에요.

우리 배는 크게 표시하고 이름표를 달아요. (지금은 샘플 3척이에요)

오른쪽 앵커리지 대기 목록에서 지금 기다리는 배와 선종·출발지·대리점을 한눈에 봐요.

선종을 골라(탱커, 컨테이너, 벌크) 내 업무에 맞는 배만 볼 수 있어요.

한국 연안 화면 · 어느 바다에 배가 몰려 있나

한국 연안을 누르면 바다를 바둑판처럼 나눈 해역이 보여요. 배가 많이 잡힌 해역일수록 진한 파랑이에요.

해역에 마우스를 올리면 지금 척수와 어제 같은 시간 척수가 나와요.

오른쪽 카드에서 연안 전체가 어제보다 늘었는지 줄었는지(▲▼), 가장 붐비는 해역 5곳을 봐요.

부산, 광양·여수, 남해 쪽이 진하게 나오는 걸 바로 확인할 수 있어요.

🔑

연안 AIS 통계는 신청 방법이 달라요. 공공데이터포털에서 활용신청을 누르면 해양수산부 GICOMS 화면으로 넘어가고, 거기서 별도 인증키를 받아요.

신청할 때 사용할 주소(도메인)를 적어야 하고, 부를 때도 그 주소를 같이 보내야 해요. 이때 http:// 와 끝의 / 는 빼고 보내요. 예) localhost:8765

클로드 코드에게는 이렇게 말하면 돼요: "연안 AIS 통계 인증키는 .env의 AIS_KEY, 신청 도메인은 AIS_DOMAIN에 넣어 줘. 부를 때 domain 값은 http 없이 보내."

나도 만들어 보기

두 API를 모두 활용신청한 뒤, 클로드 코드에게 단계별로 말해 보세요. 한 번에 다 시키지 말고, 하나가 되는 걸 본 뒤 다음으로 넘어가요.

Plain Text

1) 울산항만공사 항내 선박위치정보 API로 울산항 배들을 지도에 점으로 찍어 줘. 항해 중은 초록, 앵커링은 주황, 계류는 파랑으로. https://www.data.go.kr/data/15156631/openapi.do

Plain Text

2) 선박운항정보 API로 울산항 최근 2주 입출항 기록을 불러서, 호출부호가 같은 배에 선종·출발지·대리점을 붙여 줘. 점을 누르면 보이게.

Plain Text

3) 오른쪽에 앵커리지 대기 중인 배 목록을 넣어 줘. fleet.csv에 넣은 호출부호는 우리 배로 크게 표시해 줘.

Plain Text

4) 부산항에 들어온 외항선이 어느 항구에서 왔는지 세계지도에 선으로 이어 줘. 항구 코드는 UN/LOCODE야.

Plain Text

5) 연안 AIS 통계(WFS, lage_ship_stats_view)로 가장 최근 시간의 해역별 선박 척수를 불러서, 해역을 척수만큼 진한 파랑으로 칠해 줘. 어제 같은 시간과도 비교해 줘. https://www.gicoms.go.kr/kodispub/api/EgovOpenApiGuide.do

💡

알아 둘 것

배 한 척 한 척의 위치는 울산항만 공공데이터로 열려 있어요. 한국 연안 전체는 배 한 척씩이 아니라 해역별 척수로만 볼 수 있어요. 세계 화면의 선은 배의 실제 항로가 아니라 "출발 항구 → 도착 항구"를 잇는 선이에요.

선종·대리점은 최근 2주 울산 입출항 기록에 있는 배에만 붙어요. 어선이나 내항 소형선은 비어 있을 수 있어요.

인터넷에 올릴 때는 인증키를 화면 코드가 아니라 배포 환경 변수에 넣었어요. 위 링크에서도 키는 보이지 않아요.

4. 항만청 코드

클로드에게 항만 이름으로 말해도 되지만, 결과가 안 나오면 코드를 같이 알려 주세요.

지역	항만 (코드)
부산·경남	부산 020, 마산 810, 진해 814, 옥포 812, 장승포 813, 고현 816, 통영 815, 삼천포 811, 하동 817
울산·경북	울산 820, 포항 700, 포항신항 701, 영일만항 702, 후포 703, 울릉사동 705
전남	광양 622, 여수 620, 여천 621, 목포 610, 대불분실 616, 북항분실 617, 완도 611, 흑산도 601, 거문도 631
수도권	인천 030, 평택 031, 경인 050, 용기포 034, 연평도 035
충남·전북	대산 300, 당진화력 303, 보령 301, 태안 302, 군산 500, 장항 501
강원	동해 200, 묵호 202, 삼척 201, 옥계 204, 호산 206, 속초 203
제주	제주 900, 서귀포 901

5. 막힐 때

이럴 때	이렇게 하세요
`SERVICE_KEY_IS_NOT_REGISTERED_ERROR`(등록되지 않은 서비스키)가 나와요	그 API를 아직 신청하지 않았거나, 방금 신청했을 때 나와요. 활용신청 현황에서 [승인]인지 확인하고, 승인됐다면 잠시 기다렸다가 다시 해 보세요.
결과가 0건이에요	항만청 코드와 날짜를 확인하세요. 날짜는 `20260930`처럼 8자리로 넣어요. 클로드에게 "0건이 나와. 요청 값을 확인해 줘"라고 말해도 돼요.
데이터가 50건만 나와요	이 API는 한 번에 50건씩 줘요. "50건씩 나눠서 끝까지 다 받아 와 줘"라고 말하세요.
한참 기다려도 응답이 없어요	공공데이터포털 쪽에서 가끔 늦어요. "응답이 6초 넘게 없으면 다시 요청하게 해 줘"라고 말하면 클로드가 알아서 다시 불러요.
하루 사용량을 넘었다고 나와요	API마다 하루에 부를 수 있는 횟수가 정해져 있어요(대부분 1만 번). 다음 날 다시 쓸 수 있어요.
만든 화면을 인터넷에 올리고 싶어요	인증키가 화면 코드에 드러나면 안 돼요. "인증키가 브라우저에 보이지 않게 서버 쪽에서 API를 부르도록 바꾸고, 배포할 때는 환경 변수에 넣어 줘"라고 말하세요.

6. 해운 API 전체 목록

이름을 누르면 신청 화면으로 가요. 하루 한도는 하루에 부를 수 있는 횟수예요.

선박·운항

API	무엇을 알려 주나	하루 한도
해양수산부_선박운항정보	항만별 선박 입출항 신고 (선명, 선종, 선석, 입출항 시각, 전출항지, 차항지, 신고 대리점)	10,000
해양수산부_선박제원정보 서비스	배의 제원 (IMO번호, 톤수, 길이, 너비, 흘수, 건조일)	10,000
해양수산부_관제정보	항만 관제 정보	10,000
해양수산부_항만시설사용정보	항만 시설 사용 내역	10,000
해양수산부_항만시설 및 하역능력정보	항만 시설과 하역 능력	10,000
해양수산부_선박위치정보(연안AIS) 통계	한국 연안 해역별 시간당 선박 척수와 해역 지도. GICOMS에서 별도 인증키를 받고, 사용할 도메인을 등록해요	기관 기준

운임·비용

API	무엇을 알려 주나	하루 한도
해양수산부_화물운임공표정보	선사가 공표한 외항 화물 운임 (항로, 컨테이너 종류·크기별)	10,000
관세청_해상수출입 운송비용	나라별 해상 수출입 운송비용	10,000

화물·컨테이너

API	무엇을 알려 주나	하루 한도
해양수산부_외항컨테이너반출입정보	배별 외항 컨테이너 반입·반출	10,000
해양수산부_외항화물컨테이너정보	외항 화물 컨테이너 정보	1,000
해양수산부_외항화물반출입정보	배별 외항 화물 반입·반출	10,000
해양수산부_내항화물반출입정보	내항 화물 반입·반출	10,000
관세청_화물통관진행정보	B/L 번호로 통관 진행 상황 조회. 이 API는 UNI-PASS에 가입한 뒤 마이메뉴에서 따로 신청해요.	기관 기준

통계 (달마다 쌓이는 숫자)

API	무엇을 알려 주나	하루 한도
해양수산부_항만별 선박입출항실적 통계정보	항만별 월간 입출항 척수와 톤수	10,000
해양수산부_지역별 선박입출항실적 통계정보	지역별 월간 입출항 실적	10,000
해양수산부_수출입컨테이너처리실적 통계정보	월간 수출입 컨테이너 처리량	10,000
해양수산부_국가별컨테이너처리실적 통계정보	국가별 월간 컨테이너 처리량	10,000
해양수산부_연안화물 수송실적 통계정보	연안 화물 수송량	10,000
해양수산부_품목별 화물처리실적 통계정보	품목별 화물 처리량 (2023년 10월 이후 새 자료가 없어요)	10,000
관세청_국가별 입항물동량 실적	나라별 입항 물동량	10,000
관세청_국가별 출항물동량 실적	나라별 출항 물동량	10,000

항만공사별

API	무엇을 알려 주나	하루 한도
인천항 선박 입출항 정보	인천항 입출항 신고, 본선 동정	10,000
인천항 선석 이용 정보	인천항 부두별 접안 일정	10,000
인천항 물동량 처리 실적	인천항 월별·연간 물동량, 컨테이너 양적하	10,000
인천항 선박 제원 정보	인천항 입항 선박 제원	10,000
인천항 갑문 정보	갑문 입출거 시간표, 풍향·풍속, 실시간 수위	10,000
인천항 예도선 통합 정보	예선·도선 정보	10,000
인천항 항만운영 통계정보	부두·선종·품목별 통계	10,000
여수광양항만공사_입항정보	여수·광양항 입항 정보	1,000
여수광양항만공사_관제정보	여수·광양항 관제 정보	1,000
여수광양항만공사_월별 컨테이너 수송 실적	여수·광양항 월별 컨테이너 수송량	1,000
울산항만공사_항만 내 선박 운항정보	울산항 관제 기반 선박 운항	10,000

바다 날씨·안전

API	무엇을 알려 주나	하루 한도
국립해양조사원_항만해양지수	항만별 바다 상태 지수	10,000
국립해양조사원_뱃멀미지수	항로별 뱃멀미 예보	10,000
해양교통안전공단_실시간 교통정보	실시간 해상 교통 정보	500
해양교통안전공단_내일의 운항예보	해역별 내일 운항 예보	500

코드표

API	무엇을 알려 주나	하루 한도
관세청_선사부호 업체명	선사부호를 선사 이름으로 바꿔 줘요	10,000

7. API는 없지만 같이 보면 좋은 곳

KCCI 컨테이너 운임지수 (한국해양진흥공사): 매주 나오는 종합 운임지수와 13개 항로 지수. 클로드에게 "이 페이지의 표를 읽어서 정리해 줘"라고 할 수 있어요.

부산항만공사 외내항 컨테이너 통합 집계: 부산항은 API 대신 파일로 받아요.

Port-MIS (항만운영정보시스템): 해양수산부 입출항 API의 원래 자료가 있는 곳

UNI-PASS (관세청 전자통관): 화물 통관 진행 조회