Community연구 & 데이터 분석github.com

World Bank API 지표

AI 에이전트가 무료 World Bank API(API 키 불필요)를 사용하여 GDP, 인구, 인플레이션 등 약 30,000개의 개발 지표를 가져올 수 있도록 하는 스킬입니다.

World Bank API 지표란 무엇인가요?

이 스킬은 AI 에이전트(Claude Code, Cursor 등)가 World Bank Indicators API를 통해 방대한 양의 글로벌 개발 데이터를 검색할 수 있게 해줍니다. API 키나 회원가입이 전혀 필요 없으며, 정해진 속도 제한도 없는 무료 HTTPS GET 요청을 사용합니다. 약 30,000개의 시계열 지표를 217개 경제 주체와 78개 지역/소득 그룹에 대해(일부는 1960년까지) 제공합니다. 스킬은 Python 3.8+ 스크립트와 직접 API 호출 방식을 모두 지원합니다. 'wb_data.py' 번들 스크립트는 일반적인 사용 사례(예: 여러 국가의 GDP)에 대해 단일 명령으로 데이터를 가져오고, 더 복잡한 쿼리(예: 분기별 데이터, 지표 검색)는 RESTful API를 통해 지원합니다. 응답은 JSON 형식으로 제공되며, 에러 처리, 시간 범위 지정, 최신 값 가져오기 등 실용적인 팁이 포함되어 있어 개발자가 쉽게 활용할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add NanookAI/worldbank-api

Installed? Explore more 연구 & 데이터 분석 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

World Bank 지표 API

World Bank 지표 API는 217개 경제 주체와 78개 지역/소득 그룹에 대해 약 30,000개의 시계열 지표를 제공하며, 일부 시리즈는 1960년까지 거슬러 올라갑니다. API 키, 회원가입, 문서화된 속도 제한 없음 — 일반 HTTPS GET 요청입니다.

기본 URL: https://api.worldbank.org/v2

항상 format=json을 추가하세요 — 기본 응답 형식은 XML입니다.

가장 빠른 방법: 번들 스크립트

일반적인 경우(하나 이상의 국가에 대한 하나 이상의 지표)에는 번들된 제로-의존성 스크립트(Python 3.8+, 표준 라이브러리만 사용)를 실행하세요:

python3 scripts/wb_data.py gdp US,JP,CN                    # 별칭 + ISO 코드, 최근 5년
python3 scripts/wb_data.py SP.POP.TOTL BR --date 2000:2024 # 명시적 지표 코드 + 범위
python3 scripts/wb_data.py inflation all --mrv 1           # 모든 경제 주체, 최신 값
python3 scripts/wb_data.py population WLD,EUU --json       # 그룹, 원시 JSON 출력
python3 scripts/wb_data.py --search "renewable energy"     # 키워드로 지표 코드 검색
python3 scripts/wb_data.py --aliases                       # 내장 지표 별칭 목록

종료 코드: 0 성공, 1 찾을 수 없음/데이터 없음, 2 API 또는 네트워크 오류.

그 외의 경우(국가 메타데이터, 주제/출처별 지표 검색, 월별/분기별 시리즈, 비-Python 환경)는 아래의 API를 직접 호출하세요.

핵심 데이터 쿼리

GET https://api.worldbank.org/v2/country/{codes}/indicator/{indicator}?format=json
  • {codes} — ISO-2 또는 ISO-3 국가 코드, 세미콜론으로 구분 (US;JP;CN), 그룹 코드 (WLD, EUU, HIC...), 또는 all (모든 265개 경제 주체+그룹).
  • {indicator} — NY.GDP.MKTP.CD와 같은 지표 코드 (대소문자 구분 안 함).

예시

GET https://api.worldbank.org/v2/country/US;JP/indicator/NY.GDP.MKTP.CD?format=json&mrv=2
[
  {"page": 1, "pages": 1, "per_page": 50, "total": 4,
   "sourceid": "2", "lastupdated": "2026-07-01"},
  [
    {"indicator": {"id": "NY.GDP.MKTP.CD", "value": "GDP (current US$)"},
     "country": {"id": "US", "value": "United States"},
     "countryiso3code": "USA", "date": "2025",
     "value": 30769700000000, "unit": "", "obs_status": "", "decimal": 0},
    {"...": "국가×연도별 객체, 최신순"}
  ]
]

응답 구조: 2개 요소의 JSON 배열 — [0]은 페이지네이션 메타데이터, [1]은 데이터 배열(또는 일치하는 항목이 없으면 null). value는 국가가 보고하지 않은 연도의 경우 null입니다. 행은 국가별로 최신순으로 정렬됩니다.

시간 및 페이지네이션 매개변수

매개변수의미
date=2020 / date=2000:2024단일 연도 또는 범위. 월별 2025M01:2025M06, 분기별 2024Q1:2025Q4 (드문 월별/분기별 출처의 경우).
mrv=N국가당 최근 N개 값 (date를 덮어씀)
mrnev=N국가당 최근 N개 비어 있지 않은 값 — 많은 시리즈가 1~2년 지연되므로 "최신 가능" 값에 사용
gapfill=Ymrv와 함께: 누락된 연도를 마지막 알려진 값으로 앞으로 채움
per_page=N (기본값 50)페이지당 행 수; 큰 값(예: 20000)도 잘 작동 — 페이지를 피하기 위해 높게 설정
page=N페이지 번호; 메타데이터에서 page < pages인 동안 반복
footnote=y각 데이터 포인트에 footnote 필드 추가

하나의 호출에서 여러 지표를 사용하려면 명시적 출처가 필요합니다: /country/BR/indicator/NY.GDP.MKTP.CD;SP.POP.TOTL?source=2&format=json (출처 2 = World Development Indicators, 가장 일반적인 시리즈가 있는 곳).

가장 많이 사용되는 지표 코드 (모두 실시간 검증됨)

코드지표
NY.GDP.MKTP.CDGDP (현재 US$)
NY.GDP.MKTP.KD.ZGGDP 성장률 (연간 %)
NY.GDP.PCAP.CD1인당 GDP (현재 US$)
NY.GNP.PCAP.CD1인당 GNI, Atlas 방식 (현재 US$)
SP.POP.TOTL총 인구
FP.CPI.TOTL.ZG인플레이션, 소비자 물가 (연간 %)
SL.UEM.TOTL.ZS실업률 (% of labor force, ILO)
SP.DYN.LE00.IN출생 시 기대 수명 (년)
SI.POV.GINI지니 계수
SI.POV.DDAY빈곤 인구 비율 ($3.00/일, 인구 대비 %)
EN.GHG.CO2.PC.CE.AR51인당 CO2 배출량 (t CO2e)
IT.NET.USER.ZS인터넷 사용자 (인구 대비 %)
NE.EXP.GNFS.ZS재화 및 서비스 수출 (GDP 대비 %)
BX.KLT.DINV.WD.GD.ZSFDI 순유입 (GDP 대비 %)
PA.NUS.FCRF공식 환율 (US$당 현지 통화)
SP.URB.TOTL.IN.ZS도시 인구 (전체 인구 대비 %)

주제별로 그룹화된 100개 이상의 검증된 코드는 references/indicators.md에 있습니다. 필요한 시리즈가 이 표에 없으면 해당 파일을 읽으세요. 키워드로 검색하려면 스크립트의 --search 또는 references/endpoints.md의 검색 엔드포인트를 사용하세요 (API에는 서버 측 텍스트 검색이 없습니다).

국가 코드 및 그룹

국가: ISO-2 (US) 또는 ISO-3 (USA) 모두 작동합니다. 알아두면 좋은 그룹: WLD 세계, EUU 유럽 연합, EMU 유로 지역, HIC/UMC/LMC/LIC 소득 그룹, EAS 동아시아 및 태평양, ECS 유럽 및 중앙아시아, LCN 라틴 아메리카 및 카리브해, MEA 중동 및 북아프리카, SAS 남아시아, SSF 사하라 이남 아프리카, NAC 북미.

country/all은 경제 주체 및 그룹을 함께 반환합니다 (연간 265행). 실제 국가만 유지하려면 /v2/country?format=json&per_page=400을 한 번 가져와서 region.value == "Aggregates"인 항목을 제거하세요.

국가 메타데이터 (지역, 소득 수준, 수도, 좌표):

GET https://api.worldbank.org/v2/country/JPN?format=json
GET https://api.worldbank.org/v2/country?incomeLevel=LIC&format=json&per_page=100

코드 예제

import requests

def wb_series(indicator: str, countries: str = "all", **params) -> list[dict]:
    """World Bank 시리즈를 가져와서 평면 데이터 포인트 목록을 반환합니다."""
    url = f"https://api.worldbank.org/v2/country/{countries}/indicator/{indicator}"
    r = requests.get(url, params={"format": "json", "per_page": 20000, **params}, timeout=30)
    r.raise_for_status()
    body = r.json()
    if "message" in body[0]:          # API 오류는 HTTP 200으로 반환됨
        raise ValueError(body[0]["message"][0]["value"])
    return body[1] or []

gdp = wb_series("NY.GDP.MKTP.CD", "US;JP;CN", date="2015:2024")
latest = wb_series("SP.DYN.LE00.IN", "all", mrnev=1)
const url = "https://api.worldbank.org/v2/country/US;JP/indicator/NY.GDP.MKTP.CD"
          + "?format=json&mrv=5&per_page=1000";
const [meta, rows] = await (await fetch(url)).json();
if (meta.message) throw new Error(meta.message[0].value);
for (const r of rows ?? []) console.log(r.country.value, r.date, r.value);

오류

오류는 HTTP 200과 함께 메시지 봉투로 반환됩니다 — 항상 확인하세요:

[{"message": [{"id": "120", "key": "Invalid value",
               "value": "The provided parameter value is not valid"}]}]
  • 120 — 잘못된 국가 또는 지표 코드 (World Bank가 다루지 않는 경제 주체, 예: 대만은 어떤 코드로도 데이터가 없음).
  • 175 — 지표가 존재하지만 데이터가 삭제 또는 보관됨 (예: 이전 CO2 시리즈 EN.ATM.CO2E.PC → EN.GHG.* 대체 사용; Doing Business 출처 전체가 보관됨). 후속 코드를 검색하세요.
  • 간헐적인 일시적 HTML "Request Error" 페이지가 JSON 대신 반환됨 — 실패 처리 전에 한 번 재시도하세요.

실용적인 팁

  • "최신 숫자"에는 mrv=1보다 mrnev=1을 선호하세요 — 대부분의 시리즈는 1~2년 지연되므로 mrv=1은 종종 value: null인 가장 최근 연도를 반환합니다.
  • per_page를 높게 설정하고(예: 20000) 거의 페이지를 나눌 필요가 없습니다; all 국가 × 1년은 265행에 불과합니다.
  • 메타데이터의 total은 null 값을 포함한 국가×기간 슬롯을 계산합니다.
  • 지역화된 이름: /v2 뒤에 언어 코드를 삽입하세요 — /v2/zh/country/CN/indicator/... (지원: en, es, fr, ar, zh). 레이블만 번역됩니다. 코드와 값은 동일합니다.
  • 데이터 수정은 대략 매월 이루어집니다. 메타데이터의 lastupdated는 출처의 갱신 날짜를 알려줍니다.
  • 연간이 기본입니다. 월별/분기별은 일부 출처(Global Economic Monitor source=15, 분기별 부채 source=20/22/23)에만 존재합니다 — references/endpoints.md를 참조하세요.

전체 엔드포인트 카탈로그(지표 목록, 주제, 출처, 지역, 소득 수준, 대출 유형, 언어, 월별/분기별 데이터)는 references/endpoints.md를 읽으세요; 주제별 100개 이상의 검증된 지표 코드는 references/indicators.md를 읽으세요.

관련 스킬