tiingo

README

tiingo-go

Tiingo 금융 데이터 API 의 Go 클라이언트 라이브러리.

설치

go get github.com/kenshin579/tiingo-go@latest

Go 1.25+. 런타임 의존성 없음(테스트만 testify).

사용

c, err := tiingo.NewClientFromEnv() // TIINGO_API_KEY
if err != nil {
    log.Fatal(err)
}
ctx := context.Background()

// 자산 메타
m, _ := c.EOD.Meta(ctx, "AAPL")
fmt.Println(m.Name, m.ExchangeCode, m.StartDate, m.EndDate)

// 최신 종가
p, _ := c.EOD.LatestPrice(ctx, "AAPL")
fmt.Println(p.Date, p.Close, p.AdjClose)

// 기간 조회(주별 리샘플, 내림차순)
ps, _ := c.EOD.HistoricalPrices(ctx, "AAPL", &eod.PriceOptions{
    StartDate:    time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC),
    ResampleFreq: eod.ResampleWeekly,
    Sort:         "-date",
})

// 재무제표(최신 기간부터). 지표는 코드로 조회한다 — 신규 지표가 계속 추가되기 때문
ss, _ := c.Fundamentals.Statements(ctx, "AAPL", &fundamentals.StatementOptions{Sort: "-date"})
rev, ok := ss[0].StatementData.Get(fundamentals.CodeRevenue)

// 암호화폐 일봉(단일 페어는 PricesFor 로 바로 받는다)
cs, _ := c.Crypto.PricesFor(ctx, "btcusd", &crypto.PriceOptions{ResampleFreq: crypto.Resample1Day})

// 통화쌍 호가(복수 조회 가능)
qs, _ := c.Forex.TopOfBook(ctx, []string{"eurusd", "usdjpy"})

// IEX 실시간 스냅샷(장 마감 시 호가 필드는 nil)
iqs, _ := c.IEX.Quotes(ctx, []string{"AAPL", "MSFT"})

// 자산 검색(티커·이름). 같은 티커가 국가별로 중복될 수 있어 PermaTicker 로 구분한다
rs, _ := c.Search.Search(ctx, "apple", &search.SearchOptions{Limit: 5})

// ISIN 으로 자산 하나를 지목한다(문서 파라미터 표에는 없지만 동작한다)
byISIN, _ := c.Search.SearchByISIN(ctx, "US0378331005", nil)

실행 가능한 예시: examples/eod, examples/fundamentals, examples/crypto, examples/forex, examples/iex, examples/search.

인증

Tiingo 계정에서 발급한 토큰을 TIINGO_API_KEY 환경변수로 두거나 tiingo.NewClient(apiKey) 로 넘긴다. 토큰은 Authorization: Token <key> 헤더로 전송되며 URL 쿼리에 실리지 않는다.

커버리지

그룹	메서드	엔드포인트
End-of-Day	EOD.Meta	GET /tiingo/daily/<ticker>
End-of-Day	EOD.LatestPrice	GET /tiingo/daily/<ticker>/prices
End-of-Day	EOD.HistoricalPrices	GET /tiingo/daily/<ticker>/prices
Fundamentals*	Fundamentals.Definitions	GET /tiingo/fundamentals/definitions
Fundamentals*	Fundamentals.Meta	GET /tiingo/fundamentals/meta
Fundamentals*	Fundamentals.Statements	GET /tiingo/fundamentals/<ticker>/statements
Fundamentals*	Fundamentals.Daily	GET /tiingo/fundamentals/<ticker>/daily
Crypto	Crypto.Meta	GET /tiingo/crypto
Crypto	Crypto.Prices / PricesFor	GET /tiingo/crypto/prices
Crypto	Crypto.TopOfBook / TopOfBookFor	GET /tiingo/crypto/top
Forex	Forex.TopOfBook	GET /tiingo/fx/top
Forex	Forex.Prices	GET /tiingo/fx/<tickers>/prices
IEX	IEX.Quotes	GET /iex/
IEX	IEX.Prices	GET /iex/<ticker>/prices
Search	Search.Search	GET /tiingo/utilities/search
Search	Search.SearchByISIN	GET /tiingo/utilities/search

* Fundamentals 는 별도 구독(add-on)이다. 무료 플랜은 Dow 30 종목의 3년치만 제공하며, 권한 밖 종목은 APIError(400/403)로 돌아온다.

나머지 REST 그룹(News, Equity Realtime, BOATS, Fund Fees, Dividends/Splits)과 WebSocket 은 순차 추가 예정.

날짜 타입

Tiingo 는 같은 API 에서 두 가지 날짜 형식을 쓴다 — 가격은 2019-01-02T00:00:00.000Z, 메타는 1980-12-12. tiingo.Date(= types.Date)가 둘 다 받아 time.Time 으로 정규화하고 YYYY-MM-DD 로 직렬화한다. time.Time 을 임베드하므로 IsZero(), Before(), Year() 등을 그대로 쓸 수 있다. 다만 database/sql 에 직접 넘길 때는 d.Time 을 쓴다.

types.Time(루트 별칭 tiingo.Time)은 시각까지 보존한다. statementLastUpdated 처럼 갱신 시각이 의미 있는 필드, 그리고 암호화폐 시세처럼 인트라데이 값이 오는 필드에 쓰며, 직렬화는 RFC3339 다. 예를 들어 resampleFreq=1min 시세의 date 는 분 단위 시각이라 Date 로는 표현할 수 없다.

null 필드

IEX 스냅샷은 장 마감 시간대에 호가·체결 관련 9개 필드가 null 로 온다. 값 타입으로 받으면 0 과 구분되지 않으므로 해당 필드는 포인터(*float64, *types.Time)이며 nil 은 "값 없음"이다. 없는 티커는 에러가 아니라 응답에서 빠지고 순서도 요청과 다르므로, 결과는 Ticker 필드로 찾는다.

검색 결과의 OpenFIGIComposite 는 값이 없을 때 Tiingo 가 null 과 문자열 "nan" 을 섞어 보내므로 둘 다 빈 문자열로 정규화된다. r.OpenFIGIComposite != "" 하나만 확인하면 된다.

에러 처리

p, err := c.EOD.LatestPrice(ctx, "NOSUCH")
if errors.Is(err, tiingo.ErrNotFound) {
    // 결과 없음
}
var apiErr *tiingo.APIError
if errors.As(err, &apiErr) {
    // apiErr.StatusCode: 401 토큰 오류, 403 권한/플랜, 404 없는 티커, 429 rate limit
}

Rate limit

Tiingo 는 시간당·일당 요청 수와 월 대역폭으로 제한하며 분/초 단위 제한은 없다. 현재 사용량은 API usage 에서 확인한다. 이 라이브러리는 재시도나 백오프를 하지 않는다(429 는 APIError 로 그대로 전달).

테스트

go test ./...                                       # 단위 테스트
TIINGO_API_KEY=... go test -tags integration ./...  # 실호출 통합 테스트
go build -o /dev/null ./examples/eod                # 예제 빌드(레포 루트의 동명 디렉터리와 겹치면 -o 필요)
go build -o /dev/null ./examples/search             # eod/·search/ 가 이에 해당한다

문서

• docs/api/README.md — Tiingo 문서 사이트 23페이지를 변환한 md + Tiingo 공식 llms.txt/llms-full.txt 원본. 재생성은 ./scripts/fetch-docs.sh 와 cd tools/gendocs && npm run gen.
• 설계·계획: docs/superpowers/

라이선스

MIT

Documentation

Overview

Package tiingo 는 Tiingo API 의 Go 클라이언트다.

Index

• Constants
• Variables
• type APIError
• type Client
  • func NewClient(apiKey string, opts ...Option) (*Client, error)
  • func NewClientFromEnv(opts ...Option) (*Client, error)
• type Date
• type Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(c *http.Client) Option
  • func WithTimeout(d time.Duration) Option
• type Time

Constants

const APIKeyEnv = "TIINGO_API_KEY"

APIKeyEnv 는 API 키를 읽는 환경변수 이름.

const DateLayout = types.DateLayout

DateLayout 은 Tiingo 요청 쿼리와 Date 직렬화에 쓰는 날짜 형식.

Variables

var ErrNotFound = httpclient.ErrNotFound

ErrNotFound 는 조회 결과가 없을 때 서비스 계층이 반환한다.

Types

type APIError

type APIError = httpclient.APIError

APIError 는 Tiingo 에러 응답이다. errors.As 로 StatusCode/Message 에 접근한다.

type Client

type Client struct {
	EOD          *eod.Client          // 일별 시세·메타(End-of-Day)
	Fundamentals *fundamentals.Client // 재무제표·일별 지표(Fundamentals, 별도 구독)
	Crypto       *crypto.Client       // 암호화폐 페어 메타·시세·호가
	Forex        *forex.Client        // 통화쌍 호가·시세
	IEX          *iex.Client          // 미국 주식 실시간 스냅샷·인트라데이 시세
	Search       *search.Client       // 티커·이름·ISIN 자산 검색
	// contains filtered or unexported fields
}

Client 는 tiingo-go 라이브러리의 단일 진입점이다. 카테고리별 서브클라이언트를 필드로 노출한다.

func NewClient

func NewClient(apiKey string, opts ...Option) (*Client, error)

NewClient 는 API 키로 Client 를 만든다. 키가 비어 있으면 에러다.

func NewClientFromEnv

func NewClientFromEnv(opts ...Option) (*Client, error)

NewClientFromEnv 는 TIINGO_API_KEY 환경변수로 Client 를 만든다.

type Date

type Date = types.Date

Date 는 Tiingo 의 날짜 값이다. 응답에서 두 형식(RFC3339 타임스탬프, YYYY-MM-DD)이 모두 오기 때문에 둘 다 받아 time.Time 으로 정규화하고, 직렬화할 때는 YYYY-MM-DD 로 쓴다. null 이나 빈 문자열은 zero value 가 되며 IsZero() 로 구분한다. types.Date 의 별칭이라 카테고리 패키지(eod 등)와 같은 타입이다.

type Option

type Option func(*clientOptions)

Option 은 Client 생성 옵션(functional option).

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL 은 API 베이스 URL 을 바꾼다(테스트/프록시용).

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient 는 사용자 정의 *http.Client 를 주입한다(설정 시 WithTimeout 은 무시된다).

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout 은 HTTP 타임아웃을 지정한다(기본 30s).

type Time

type Time = types.Time

Time 은 시각까지 의미 있는 Tiingo 타임스탬프다(예: statementLastUpdated). 날짜만 필요한 필드는 Date 를 쓴다 — Date 는 시각을 버리고 날짜만 남긴다. null 이나 빈 문자열은 zero value 가 되며 IsZero() 로 구분한다. types.Time 의 별칭이라 카테고리 패키지(fundamentals 등)와 같은 타입이다.