API 이해하고 연결하기
“남이 만든 기능을 내 것처럼”
02이 차시를 마치면
- 1.API가 무엇이고 요청-응답 구조가 어떻게 되는지 설명할 수 있다.
- 2.JSON 형태의 응답에서 필요한 값이 어디에 있는지 찾아 읽을 수 있다.
- 3.API 키를 발급받아 코드에 직접 노출하지 않는 방식으로 안전하게 보관할 수 있다.
- 4.외부 API를 호출해 받아온 데이터를 구글 시트에 자동으로 쌓을 수 있다.
- 5.API 문서에서 엔드포인트·파라미터·사용량 한도를 찾아 읽을 수 있다.
03왜 필요한가
04차시에서 시트 자동화를 익혔지만, 그 데이터는 전부 사람이 직접 입력한 것이었다. 실제 업무에서는 이런 경우가 많다 — 매일 아침 환율 사이트에 들어가 오늘 환율을 확인하고 정산 시트에 손으로 옮겨 적는 담당자, 공공 데이터 사이트에서 최신 통계를 확인해 보고서에 붙여 넣는 담당자. 데이터는 이미 인터넷 어딘가에 있는데, 그걸 가져오는 방법을 몰라 매번 눈으로 보고 손으로 옮긴다.
- 외부 사이트를 매번 열어 눈으로 확인하고 손으로 옮기는 데 시간이 든다.
- 사람이 옮기다 보니 숫자를 잘못 옮기거나 날짜를 빼먹는 실수가 생긴다.
- "이 데이터를 자동으로 가져올 수 없을까"라는 생각은 들지만 API가 뭔지 몰라 시도조차 못 한다.
- API 키를 코드에 그대로 적었다가 유출되는 사고를 어떻게 방지하는지 모른다.
04개념 설명
API는 정해진 형식으로 주고받는 대화 창구다
식당에서 주문하는 과정을 떠올려보자. 메뉴판을 보고(문서를 읽고), 정해진 형식으로 주문을 넣으면(요청을 보내면), 주방에서 음식을 만들어 내온다(응답을 돌려준다). API(Application Programming Interface)는 서로 다른 프로그램이 이런 식으로 정해진 규칙에 따라 데이터를 주고받는 창구다.
내가 특정 주소(엔드포인트)로 필요한 조건을 담아 요청을 보내면, 상대 서버가 정해진 형식으로 응답을 돌려준다. 이 형식과 규칙이 바로 API 문서에 적혀 있는 내용이다.
- 요청(Request) — 내가 무엇을 달라고 보내는 것
- 응답(Response) — 서버가 돌려주는 결과
- 엔드포인트(Endpoint) — 요청을 보내는 주소
JSON — 프로그램끼리 주고받는 데이터의 모양
JSON은 API 응답에서 가장 흔히 쓰이는 데이터 형식이다. 중괄호 { }는 하나의 정보 묶음을, 대괄호 [ ]는 여러 개를 나열한 목록을 뜻한다. 예를 들어 환율 정보를 담은 응답은 { "날짜": "2026-08-22", "환율": 1320.5 } 처럼 생겼을 수 있고, 여러 통화를 한 번에 받으면 이런 묶음이 목록으로 늘어선 모양이 된다.
사람이 읽는 시트(표)와 프로그램이 주고받는 JSON은 사실 같은 정보를 다른 모양으로 표현한 것뿐이다. JSON에서 원하는 값의 위치(이름표)만 찾으면, 그 값을 그대로 시트의 한 칸에 옮겨 담을 수 있다.
| 키 | 값 |
|---|---|
| 날짜 | 2026-08-22 |
| 환율 | 1320.5 |
- { } — 하나의 정보 묶음(객체)
- [ ] — 여러 묶음을 나열한 목록(배열)
- 이름표(키)와 값의 짝으로 이뤄진다
API 키 — 출입증이자 책임의 증표
많은 API는 누가 요청을 보냈는지 확인하기 위해 키(API Key)를 요구한다. 이 키는 건물 출입증과 비슷하다. 출입증을 남에게 보여주거나 잃어버리면, 그 사람이 내 이름으로 드나들며 문제를 일으킬 수 있는 것처럼, 키가 유출되면 남이 내 계정 한도로 요청을 보내거나 요금을 발생시킬 수 있다.
그래서 키는 코드 안에 직접 적지 않고, 코드와 분리된 별도의 저장소(Apps Script의 스크립트 속성, 또는 환경변수)에 보관한 뒤 코드에서는 이름으로만 불러와 쓴다. 이렇게 해두면 코드를 다른 사람과 공유하거나 화면에 띄워도 실제 키 값은 드러나지 않는다.
코드가 아니라 이 화면에만 값을 적어둔다 — 코드를 공유해도 값은 드러나지 않는다.
- 코드에 키 값을 직접 적지 않는다
- 스크립트 속성/환경변수 등 별도 저장소에 보관한다
- 유출이 의심되면 즉시 재발급(rotate)한다
API 문서 읽는 법 — 필요한 세 가지만 찾는다
API 문서는 처음 보면 방대해 보이지만, 시작 단계에서는 세 가지만 찾으면 된다. 요청을 보내는 주소(엔드포인트), 그 요청에 붙여야 하는 조건(파라미터), 그리고 돌아오는 응답이 어떤 모양인지 보여주는 예시다.
여기에 더해 사용량 한도(rate limit)를 반드시 확인해야 한다. 하루 또는 분당 몇 번까지 호출할 수 있는지를 모르고 쓰면, 갑자기 요청이 막히거나 예상치 못한 비용이 발생할 수 있다.
| 항목 | 의미 |
|---|---|
| 엔드포인트 | 요청 주소 |
| 파라미터 | 요청에 붙이는 조건 |
| 응답 예시 | 결과가 어떤 모양인지 |
| 사용량 한도 | 얼마나 자주 호출 가능한지 |
- 엔드포인트 — 요청 주소
- 파라미터 — 요청에 붙이는 조건
- 응답 예시 — 결과가 어떤 모양인지
- 사용량 한도 — 얼마나 자주 호출 가능한지
05실습 가이드
1. 무료 API 키 발급받기
- 공공데이터포털이나 환율·날씨 정보를 제공하는 공개 API 중 하나를 골라 회원가입 후 API 키(인증키) 발급을 신청한다.
- 즉시 발급되는 서비스도 있고 승인까지 시간이 걸리는 서비스도 있으니, 이번 실습을 시작하기 전에 미리 신청해둔다.
- 발급받은 키는 메모장 등 별도 파일에 임시로 적어두되, 아직 어떤 코드에도 붙여넣지 않는다.
예상 결과 — 사용 가능한 API 키(문자·숫자 조합) 한 개를 손에 넣는다.
안 될 때 — 승인이 지연되는 서비스라면, 신청 즉시 키가 발급되는 다른 공개 API(무료 환율·날씨 API 등)로 바꿔 진행한다.
2. API 키를 스크립트 속성에 저장하기
- 04차시에서 쓰던 시트(또는 새 시트)에서 '확장 프로그램 → Apps Script'를 연다.
- 왼쪽 톱니바퀴(프로젝트 설정) 메뉴에서 '스크립트 속성'에 속성을 추가한다.
- 속성 이름(예: API_KEY)과 발급받은 키 값을 등록하고 저장한다.
예상 결과 — 스크립트 속성 목록에 API_KEY 항목이 값과 함께 등록된다. 코드에는 아직 키가 등장하지 않는다.
안 될 때 — 스크립트 속성 메뉴가 안 보이면 프로젝트 설정(톱니바퀴) 화면인지 확인한다. 코드 편집기 화면과는 다른 탭이다.
3. API 문서에서 필요한 정보 확인하기
- 선택한 API의 공식 문서에서 엔드포인트 주소, 필수 파라미터, 응답 예시를 찾는다.
- P5-1 프롬프트로 문서 내용을 AI에게 붙여넣고 핵심만 정리해달라고 요청한다.
예상 결과 — 엔드포인트 주소, 필요한 파라미터, JSON 응답 예시가 한눈에 정리된다.
안 될 때 — 문서가 영어로만 되어 있어도 괜찮다. 해당 페이지를 통째로 복사해 AI에게 붙여넣고 번역 겸 요약을 요청한다.
4. 요청 코드 작성하고 응답 확인하기
- P5-2 프롬프트로 UrlFetchApp을 이용한 호출 코드를 요청한다(키는 스크립트 속성에서 불러오도록 명시).
- 받은 코드를 편집기에 붙여넣고 실행한다.
- 실행 로그에 응답 JSON이 출력되는지 확인한다.
예상 결과 — 실행 로그에 API가 돌려준 JSON 원문이 찍힌다.
안 될 때 — 로그에 401·403 같은 인증 에러가 보이면 스크립트 속성 이름과 코드에서 불러오는 이름이 정확히 같은지 확인한다. P5-4(복구 프롬프트)를 사용한다.
5. 필요한 값만 골라내기
- 로그에 찍힌 JSON을 보고, 시트에 쌓고 싶은 값(예: 날짜, 환율 수치)이 어느 위치에 있는지 확인한다.
- P5-3 프롬프트로 필요한 값만 뽑아내는 코드로 다듬어달라고 요청한다.
예상 결과 — 실행 로그에 JSON 전체가 아니라 원하는 값만 깔끔하게 출력된다.
안 될 때 — 값이 undefined로 나오면 JSON 구조를 다시 확인해 값이 어느 depth(중첩된 객체·배열 여부)에 있는지 JSON 원문과 함께 AI에게 재질문한다.
6. 시트에 한 줄씩 쌓기
- 새 시트 탭(예: '환율기록')을 만들고 헤더(날짜, 값 등)를 적는다.
- 5단계 코드에 이어서, 뽑아낸 값을 이 시트 맨 아래 행에 추가하는 코드를 요청해 붙여넣는다.
- 실행 버튼을 여러 번 눌러 실행할 때마다 새 행이 쌓이는지 확인한다.
예상 결과 — 실행할 때마다 '환율기록' 시트에 새로운 행이 하나씩 추가된다.
안 될 때 — 같은 행이 계속 덮어써지면 마지막 행을 찾는 부분(getLastRow 등)이 빠진 것이다. "매번 새 행에 추가되게 고쳐줘"라고 요청한다.
7. 에러와 사용량 한도 대비하기
- API 문서에서 확인한 사용량 한도(하루·분당 호출 횟수 등)를 코드 주석이나 별도 메모로 남겨둔다.
- P5-5 프롬프트로 호출 실패 시 재시도하거나 에러를 기록하는 코드를 보강해달라고 요청한다.
예상 결과 — 호출이 실패해도 스크립트가 멈추지 않고, 실패 사실이 로그나 시트에 기록된다.
안 될 때 — 계속 실패한다면 짧은 시간에 너무 많이 호출해 한도를 넘겼을 수 있다. 잠시 기다렸다가 다시 실행하고, 호출 빈도를 낮춘다.
8. (선택) 매일 자동으로 쌓이게 만들기
- 04차시에서 익힌 트리거 설정 방법으로, 이번 스크립트를 매일 정해진 시각에 실행되도록 등록한다.
- 하루 이틀 지난 뒤 시트에 날짜별로 데이터가 실제로 쌓이고 있는지 확인한다.
예상 결과 — 트리거 목록에 등록되고, 다음날 시트에 새 행이 자동으로 추가되어 있다.
안 될 때 — 트리거는 등록됐는데 데이터가 안 쌓이면, 왼쪽 '실행' 메뉴에서 트리거 실행 기록에 에러가 있는지 확인한다.
06실전 프롬프트
07이것만은 주의
무슨 일이 생기나 — 스크립트를 다른 사람과 공유하거나 사본을 넘길 때, 코드 안에 적힌 키가 그대로 노출된다. 이 키로 다른 사람이 요청을 보내면 내 계정 한도로 처리되거나 요금이 청구될 수 있다.
대처 — 키는 항상 스크립트 속성(또는 환경변수)에 저장하고 코드에는 이름만 남긴다. 이미 코드에 적어 공유한 적이 있다면 즉시 키를 재발급(rotate)한다.
무슨 일이 생기나 — 테스트 삼아 실행 버튼을 여러 번 누르거나 반복문 안에 호출을 넣어 짧은 시간에 너무 많이 요청하면, API가 일시 차단되거나 과금 구간으로 넘어갈 수 있다.
대처 — 실습 전에 문서에서 무료 한도(하루/분당 횟수)를 확인해둔다. 테스트는 최소 횟수로만 하고, 반복 실행이 필요하면 트리거 간격을 넉넉히 둔다.
무슨 일이 생기나 — 서버 점검, 네트워크 문제, 파라미터 오타 등으로 응답이 실패할 수 있는데, 이를 대비하지 않으면 스크립트가 중간에 멈추거나 잘못된 값이 시트에 쌓인다.
대처 — 실패 시 처리(에러 기록, 재시도)를 항상 코드에 포함시킨다.
무슨 일이 생기나 — 실제 응답 구조를 확인하지 않고 "아마 이렇게 생겼을 것"이라고 짐작해 코드를 짜면, 값이 비거나 엉뚱한 위치의 데이터를 가져온다.
대처 — 항상 실행 로그로 실제 JSON을 먼저 눈으로 확인한 뒤, 그 구조를 그대로 AI에게 보여주고 코드를 요청한다.
무슨 일이 생기나 — 무료 한도가 있는 API도 일정량을 넘으면 자동으로 유료 결제로 전환되는 경우가 있다. 확인하지 않고 계속 쓰면 예상치 못한 청구서를 받을 수 있다.
대처 — 발급 시 안내되는 무료 한도와 초과 시 정책(자동 과금 여부)을 미리 확인한다. 가능하면 사용량 알림을 설정해둔다.
08자가 점검
09과제
자신의 업무나 관심 분야와 관련된 공개 API(환율, 날씨, 공공데이터 등) 하나를 골라, 이번 실습과 같은 흐름(키 발급 → 안전하게 보관 → 호출 → 필요한 값만 추출 → 시트에 쌓기)으로 데이터를 하루 이상 자동으로 쌓아본다.
제출 형식 — ① 사용한 API 이름과 문서 링크 ② 데이터가 쌓인 시트 캡처(최소 2회 이상 실행분) ③ 스크립트 속성에 키를 저장한 화면 캡처(키 값은 가려도 됨) ④ 사용한 프롬프트와 AI 응답 요약을 하나의 문서로 정리해 제출한다.
10더 알아보기
- 공공데이터포털 — 무료로 API 키를 발급받을 수 있는 공공데이터 오픈 API 모음
- UrlFetchApp 공식 문서 — Apps Script에서 외부 API를 호출하는 방법 참고용
- 엔드포인트(Endpoint)
- — API 요청을 보내는 주소.
- JSON
- — API 응답에서 흔히 쓰이는, 중괄호와 대괄호로 데이터를 표현하는 형식.
- 사용량 한도(Rate Limit)
- — 정해진 시간 안에 API를 호출할 수 있는 최대 횟수.
다음 차시 예고 — 다음 차시에서는 지금까지 기능 위주로 만들어온 화면을, 보기 좋고 신뢰감 있게 다듬는 디자인 원칙과 AI에게 디자인을 지시하는 법을 다룹니다.