인구 이력 조회 API 레퍼런스
세계은행의 국가별 연간 총인구를 조회합니다.
economics_ —REST와 다음 economics_ MCP 도구입니다. 둘 다 같은 데이터 형식을 반환하며 같은 크레딧을 사용합니다.
엔드포인트 및 요청
GET /v1/economics/{country}/population/observationscurl --request GET \
--url "https://api.narwhalapi.com/v1/economics/USA/population/observations?start=2024&limit=100" \
--header "Authorization: Bearer $NARWHAL_API_KEY"MCP에서 사용하는 도구: economics_ —아래의 해당 인수로 호출하세요.
매개변수
이 작업에서 허용되는 기간 형식: YYYY.
| 이름 | 필수 | 유형 | 의미 |
|---|---|---|---|
country | 예 | 경로 · ISO alpha-3 | 지원되는 대문자 국가 코드 1개입니다. 이 작업의 범위 목록을 확인하세요. |
start | 아니요 | 쿼리 · YYYY | 조회 범위의 첫 관측 기간이며, 해당 기간도 포함합니다. |
end | 아니요 | 쿼리 · YYYY | 조회 범위의 마지막 관측 기간이며, 해당 기간도 포함합니다. |
limit | 아니요 | 쿼리 · 정수, 1~1000 | 반환할 최대 기간 수입니다. 기본값은 100입니다. 한 페이지에 더 적은 기간이 포함될 수 있으므로 next_cursor를 따라가세요. |
cursor | 아니요 | 쿼리 · 불투명 문자열 | 이전 페이지의 next_cursor입니다. |
version | 아니요 | 쿼리 · first_reported | `first_reported`만 허용합니다. 기간별로 처음 저장된 값을 `first_reported_at`과 함께 반환합니다. `as_of`와 함께 사용할 수 없습니다. |
as_ | 아니요 | 쿼리 · YYYY-MM-DD | 지정한 UTC 날짜가 끝날 때까지 공표된 상태의 시계열을 반환합니다. `version`과 함께 사용할 수 없습니다. |
응답
{
"country": "USA",
"as_of": "2026-10-08T00:00:00Z",
"source": {
"publisher": "UN Population Division (World Population Prospects), national statistical offices, Eurostat, U.S. Census Bureau, Pacific Community: mid-year estimates",
"distributor": "World Bank, World Development Indicators (CC BY 4.0)"
},
"unit": "person",
"frequency": "annual",
"observations": [
{
"period": "2024",
"value": "340003797"
},
{
"period": "2025",
"value": "341784857"
}
],
"next_cursor": null
}| 필드 | 유형 | 필수 | 의미 |
|---|---|---|---|
country | 문자열 | 예 | 요청한 대문자 ISO alpha-3 국가 코드입니다. 관측값마다가 아니라 페이지당 한 번 반환합니다. |
as_ | RFC 3339 타임스탬프 | 아니요 | 이 페이지의 가장 최근 관측값을 소스가 마지막으로 갱신한 시각입니다. UTC 기준이며 소수점 이하 초는 없습니다. |
source | 객체 | 예 | publisher에는 원 발행 기관이, distributor에는 세계은행 세계개발지표(CC BY 4.0)가 표시됩니다. |
unit | 문자열 | 예 | 항상 person입니다. |
frequency | 문자열 | 예 | 항상 annual입니다. |
observations | 배열 | 예 | 채택된 관측값을 오래된 순서로 기간당 하나씩 반환합니다. 소스에 없는 값은 생략하며 채워 넣지 않습니다. 한 페이지의 관측값 수가 limit보다 적을 수 있으므로 next_cursor가 null이 될 때까지 따라가세요. |
observations[].period | 문자열 | 예 | 관측값이 나타내는 공식 월, 분기 또는 연도입니다. |
observations[].first_ | RFC 3339 타임스탬프 | 아니요 | version=first_를 사용할 때만 포함되는 이 UTC 타임스탬프는 Narwhal이 해당 기간의 데이터를 처음 저장한 시점을 기록합니다(측정값들이 별도로 저장된 경우에는 그중 가장 늦은 시점). 수집 시작 전에 공표된 기간에는 Narwhal의 최초 수집 시점이 표시됩니다. |
observations[].value | 십진수 문자열 | 예 | 연중 시점의 인구를 명 단위 정수로 나타냅니다. 법적 지위나 국적과 관계없이 모든 거주자를 포함합니다. 가장 최근 연도는 추계일 수 있습니다. |
next_ | 문자열 또는 null | 예 | 다음 페이지를 읽으려면 이 값을 변경하지 않고 cursor로 전달하세요. 마지막 페이지에서는 null입니다. |
API 오류 코드와 크레딧
400 invalid_— 국가, 기간 또는 필터 형식이 유효하지 않거나,query as_와of version을 함께 보냈습니다.400 invalid_— 커서 형식이 잘못되었거나 다른 필터 또는 작업에 대해 발급되었습니다.cursor 401 invalid_— Bearer 키가 누락되었거나 거부되었습니다.api_ key 404 series_— 요청과 일치하는 승인 관측값이 없습니다.not_ found 409 cursor_페이지네이션 커서가 너무 오래되었거나 대상 데이터가 변경되었습니다. 커서 없이 다시 시작하세요.expired 429 rate_—네트워크 또는 계정의 단기 구간 한도에 도달했습니다. 재시도 전 대기 시간은 다음 헤더를 따르세요:limit_ exceeded Retry-After.402 insufficient_— 잔액이 호출 비용에 부족합니다.credits 503 economics_— Narwhal이 승인 발표를 안전하게 제공할 수 없습니다.unavailable
Only a successful data response costs credit. 확인 모든 오류, 헤더 및 재시도 규칙.
최신성
기본적으로 이 경로는 Narwhal이 현재 채택한 시계열을 반환하며, 응답의 as_는 가장 최근 관측값의 갱신 시각입니다. 모든 키는 as_ 또는 version=first_로 과거 시점의 데이터를 조회할 수 있습니다. 과거 시점의 데이터 이력은 Narwhal의 최초 수집 시점부터 시작하며, 모든 과거 공표 내용을 재구성한 것은 아닙니다.
공식 출처에는 관측값이 없는 구간이 있을 수 있으며, 과거 데이터의 제공 범위도 출처마다 다릅니다. Narwhal은 누락된 관측값을 보간하거나 이전 값으로 채우지 않고 생략합니다.
현재 공개 베타 데이터 범위
215 국가
ABW, AFG, AGO, ALB, AND, ARE, ARG, ARM, ASM, ATG, AUS, AUT, AZE, BDI, BEL, BEN, BFA, BGD, BGR, BHR, BHS, BIH, BLR, BLZ, BMU, BOL, BRA, BRB, BRN, BTN, BWA, CAF, CAN, CHE, CHL, CHN, CIV, CMR, COD, COG, COL, COM, CPV, CRI, CUB, CUW, CYM, CYP, CZE, DEU, DJI, DMA, DNK, DOM, DZA, ECU, EGY, ERI, ESP, EST, ETH, FIN, FJI, FRA, FRO, FSM, GAB, GBR, GEO, GHA, GIB, GIN, GMB, GNB, GNQ, GRC, GRD, GRL, GTM, GUM, GUY, HKG, HND, HRV, HTI, HUN, IDN, IMN, IND, IRL, IRN, IRQ, ISL, ISR, ITA, JAM, JOR, JPN, KAZ, KEN, KGZ, KHM, KIR, KNA, KOR, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, LTU, LUX, LVA, MAC, MAF, MAR, MCO, MDA, MDG, MDV, MEX, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MNP, MOZ, MRT, MUS, MWI, MYS, NAM, NCL, NER, NGA, NIC, NLD, NOR, NPL, NRU, NZL, OMN, PAK, PAN, PER, PHL, PLW, PNG, POL, PRI, PRK, PRT, PRY, PSE, PYF, QAT, ROU, RUS, RWA, SAU, SDN, SEN, SGP, SLB, SLE, SLV, SMR, SOM, SRB, SSD, STP, SUR, SVK, SVN, SWE, SWZ, SXM, SYC, SYR, TCA, TCD, TGO, THA, TJK, TKM, TLS, TON, TTO, TUN, TUR, TUV, TZA, UGA, UKR, URY, USA, UZB, VCT, VEN, VGB, VIR, VNM, VUT, WSM, YEM, ZAF, ZMB, ZWE
연간 이력은 1960년부터 시작하며, 팔레스타인은 1990년부터입니다. 코소보와 채널 제도는 ISO alpha-3 코드가 없어 포함되지 않습니다. 인구의 최신값 경로는 없습니다. 성공한 요청은 Economics 호출 1회로 과금됩니다.
인도네시아 및 지역 경제 데이터 경로는 공개되지 않습니다. 일일 환율을 제공하는 API: 환율 API.
다음으로 돌아가기 모든 경제 데이터 작업.
무료 키로 시작하세요
매달 10달러 상당의 무료 크레딧을 드립니다. 카드는 필요하지 않습니다.매달 10달러 상당의 무료 크레딧. 카드는 필요하지 않습니다.
이 페이지가 도움이 되었나요?