첫 Narwhal API 요청 보내기

REST 또는 MCP에서 Economics, FX, Equities, SEC 신고서, 팜유 가격 및 Calendars에 하나의 키를 사용하세요.

이 가이드는 CPI로 시작한 뒤 6개 API 각각의 작동 레퍼런스로 연결됩니다: api.narwhalapi.com.

경제 데이터 지원 범위

AUS, CAN, DEU, FRA, GBR, JPN, MYS, NLD, SGP 및 USA에서 사용할 수 있습니다. 모든 데이터 요청에는 Narwhal API 키가 필요합니다.

무료 베타 제한: 3,000 UTC 월간 성공 요청 수와 다음 30 분당 요청 수와 버스트 5 REST와 MCP는 동일한 한도를 공유합니다.

API 키 설정

키를 Bearer 토큰으로 다음에 보내세요 Authorization 헤더이며 URL에는 절대 넣지 않습니다. 계정을 만들고 무료 키 받기, 그런 다음 다음 항목을 읽으십시오 인증 가이드 저장하기 전에.

터미널

export NARWHAL_API_KEY="nw_live_..."

공식 CPI 요청

경로에 ISO 3자리 국가 코드를 전달하세요. 생략하면 period 최근 승인 완전 발표를 반환합니다.

요청

curl --request GET \
  --url https://api.narwhalapi.com/v1/economics/USA/cpi \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

응답 예시

{
  "country": "USA",
  "period": "2026-07",
  "value": "333.918",
  "base_period": "1982-84",
  "base_value": "100",
  "released_on": "2026-08-12"
}

Python 및 JavaScript 예제

애플리케이션에서 같은 환경 변수와 엔드포인트를 사용하세요. 이 예제는 기본 제공 라이브러리를 사용합니다.

Python 3

import json
import os
from urllib.request import Request, urlopen

request = Request(
    "https://api.narwhalapi.com/v1/economics/USA/cpi",
    headers={"Authorization": "Bearer " + os.environ["NARWHAL_API_KEY"]},
)
with urlopen(request, timeout=30) as response:
    data = json.load(response)
print(data)

JavaScript · Node.js 18+

const key = process.env.NARWHAL_API_KEY;
if (!key) throw new Error("Set NARWHAL_API_KEY first");
const response = await fetch(
  "https://api.narwhalapi.com/v1/economics/USA/cpi",
  { headers: { Authorization: "Bearer " + key }, signal: AbortSignal.timeout(30000) }
);
const data = await response.json();
if (!response.ok) throw new Error(JSON.stringify(data));
console.log(data);

사용할 API 선택

API	다음으로 시작
경제 데이터 API	10개 국가의 공식 제공 기관이 발표한 CPI, 인플레이션, 노동, GDP 및 무역 데이터입니다.
FX API	모든 환율의 타임스탬프와 함께 제공되는 현재 환율, 변환 및 페이지가 매겨진 과거 데이터입니다.
주식 데이터 API	보통주 종목을 확인하고 분할 조정된 일일 바를 조회하세요.
공휴일 달력 API	국가·지역·대체일 범위가 포함된 게시된 공휴일입니다.
팜유 생과방(FFB) API	지역 및 수령 연령별 공식 인도네시아 FFB 일정입니다.
SEC 신고서 API	기업 검색, 식별 정보 및 SEC 신고서 메타데이터입니다.

국가와 지표 선택

모든 라이브 국가에서 최신 발표 작업 9개와 이에 대응하는 과거 데이터 작업 9개를 이용할 수 있습니다. 다음 Economics API 레퍼런스 모든 경로와 응답 구조를 나열합니다.

지표	경로 접미사
CPI	`/cpi`
인플레이션	`/inflation`
실업률	`/unemployment`
경제활동 참가율	`/labour-force-participation`
GDP 및 성장률	`/gdp` · `/gdp-growth`
무역, 수출, 수입	`/trade` · `/trade/exports` · `/trade/imports`

MCP를 통해 연결

MCP 클라이언트에서 동일한 키와 스키마를 사용하세요. 도구 검색은 6개 API 전체에서 계정이 이용할 수 있는 작업을 나열합니다. 다음을 확인하세요 MCP 가이드.

클라이언트 중립 필드 맵

{
  "url": "https://api.narwhalapi.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_NARWHAL_API_KEY"
  }
}

MCP 클라이언트의 보안 시크릿 설정에서 플레이스홀더를 바꾸세요. 일반 JSON은 환경 변수를 자체적으로 확장하지 않습니다.

첫 tools/call

{
  "method": "tools/call",
  "params": {
    "name": "fx_get_rates",
    "arguments": { "base": "USD", "currencies": ["EUR", "JPY"] }
  }
}

초기화 및 tools/list 할당량을 소비하지 않습니다. 성공한 각 tools/call 요청 1회를 소비합니다.

응답 읽기

각 작업의 응답 스키마를 읽습니다. Economics는 도메인 객체를 반환하고 Equities는 다음을 사용합니다 meta/values 시계열 및 다음에 대해 count/data 종목에 대해.

규칙	의미
`period`	공식 발표가 반환하는 정확한 월, 분기 또는 연도입니다.
`released_on`	공식 발표일입니다.
십진 문자열	값은 이진 부동소수점으로 인한 예기치 않은 문제를 피합니다.
누락 데이터	불완전하거나 이용할 수 없는 발표는 폐쇄적으로 실패 처리되며 누락값이 0으로 바뀌지 않습니다.

읽기 Narwhal이 공식 발표를 저장하고 업데이트하는 방법.

성공 응답의 할당량 헤더

X-Request-IDX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset

상태와 코드로 오류 처리

먼저 HTTP 상태를 확인한 다음 다음을 사용하세요 code 애플리케이션 로직에서. detail 로그와 디버깅용입니다. 다음 오류 및 할당량 가이드 모든 공개 상태를 나열합니다.

RFC 9457 문제 응답

{
  "ok": false,
  "type": "https://narwhalapi.com/problems/invalid-query",
  "title": "Invalid query",
  "status": 400,
  "detail": "The request parameters are not valid for this operation.",
  "code": "invalid_query",
  "request_id": "019d1af4-8f33-7b21-91af-ef535f2dcf50",
  "instance": "/v1/economics/USA/cpi"
}

키에 도움이 필요하신가요? Narwhal API에 문의하세요.

다음의 새로운 내용 확인 변경 로그.

LLM? llms.txt를 읽으세요.