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=Y | mrv와 함께: 누락된 연도를 마지막 알려진 값으로 앞으로 채움 |
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.CD | GDP (현재 US$) |
NY.GDP.MKTP.KD.ZG | GDP 성장률 (연간 %) |
NY.GDP.PCAP.CD | 1인당 GDP (현재 US$) |
NY.GNP.PCAP.CD | 1인당 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.AR5 | 1인당 CO2 배출량 (t CO2e) |
IT.NET.USER.ZS | 인터넷 사용자 (인구 대비 %) |
NE.EXP.GNFS.ZS | 재화 및 서비스 수출 (GDP 대비 %) |
BX.KLT.DINV.WD.GD.ZS | FDI 순유입 (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를 읽으세요.