Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 7 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,7 @@ size := httpClient.CacheSize()
- キャッシュキーはリクエストパス(クエリパラメータ含む)で区別されます
- 同時リクエストの重複排除(singleflight)により効率的に動作します
- 待機中にコンテキストをキャンセルした呼び出し元は即座にエラーで戻ります(進行中のリクエストは完了してキャッシュされます)
- 署名付きダウンロードURLを返すAPI(Bulk・TDnetのファイルURL取得)はURLが失効するためキャッシュを経由しません
- キャッシュはクライアントインスタンスの生存期間のみ有効です

## 利用可能なAPI
Expand All @@ -104,6 +105,7 @@ size := httpClient.CacheSize()
|---------|---------|------|
| **株価** | Quotes | 日次株価四本値 |
| **株価** | PricesAM | 前場四本値 |
| **株価** | MinuteQuotes | 株価分足 |
| **銘柄情報** | Listed | 上場銘柄一覧 |
| **財務** | Statements | 財務情報 |
| **財務** | FSDetails | 財務諸表詳細(BS/PL/CF) |
Expand All @@ -121,6 +123,11 @@ size := httpClient.CacheSize()
| **信用取引** | DailyMarginInterest | 日々公表信用取引残高 |
| **空売り** | ShortSelling | 業種別空売り比率 |
| **空売り** | ShortSellingPositions | 空売り残高報告 |
| **適時開示** | TimelyDisclosure | TDnet適時開示情報 |
| **EDINET** | EdinetMajorShareholders | 大株主状況 |
| **EDINET** | EdinetCrossShareholdings | 政策保有株式 |
| **EDINET** | EdinetLargeVolumeShareholders | 大量保有報告書 |
| **ダウンロード** | Bulk | CSV一括ダウンロード |

※各APIの利用可能なプランについては、[J-Quants公式サイト](https://jpx-jquants.com/)で確認してください。

Expand Down Expand Up @@ -297,18 +304,6 @@ quote.O, quote.H, quote.L, quote.C

詳細は[公式の移行ガイド](https://jpx-jquants.com/ja/spec/migration-v1-v2)を参照してください。

## エラーハンドリング

```go
quotes, err := jq.Quotes.GetDailyQuotesByCode(ctx, "9999")
if err != nil {
// APIエラーの詳細を取得
if apiErr, ok := err.(*client.APIError); ok {
fmt.Printf("APIエラー: %d - %s\n", apiErr.StatusCode, apiErr.Message)
}
}
```

## 注意事項

- J-Quants APIの利用には適切なサブスクリプションが必要です
Expand Down
162 changes: 162 additions & 0 deletions bulk.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
package jquants

import (
"context"
"encoding/json"
"fmt"

"github.com/utahta/jquants/client"
"github.com/utahta/jquants/types"
)

// BulkService はCSVファイルの一括ダウンロード(Bulk API)を提供するサービスです。
// ご契約プランでアクセス可能なエンドポイントのファイルが対象です。
// 株式ティックデータ(/equities/trades)はAPIでの提供がなく、このBulk API経由でのみ取得できます。
type BulkService struct {
client client.HTTPClient
}

// NewBulkService は新しいBulkServiceを作成します。
func NewBulkService(c client.HTTPClient) *BulkService {
return &BulkService{client: c}
}

// BulkListParams はダウンロード可能ファイル一覧のリクエストパラメータです。
type BulkListParams struct {
Endpoint string // 対象データのエンドポイント名(e.g. /equities/bars/daily)(endpoint、dateのいずれかが必須)
Date string // 対象日付(YYYY-MM、YYYYMM、YYYY-MM-DD、YYYYMMDD)(endpoint、dateのいずれかが必須)
From string // 取得期間の開始日(YYYY-MM、YYYYMM、YYYY-MM-DD、YYYYMMDD)(endpoint指定時のみ使用可)
To string // 取得期間の終了日(YYYY-MM、YYYYMM、YYYY-MM-DD、YYYYMMDD)(endpoint指定時のみ使用可)
}

// BulkListResponse はダウンロード可能ファイル一覧のレスポンスです。
type BulkListResponse struct {
Data []BulkFile `json:"data"`
}

// BulkFile はダウンロード可能ファイルの情報を表します。
// J-Quants API /bulk/list エンドポイントのレスポンスデータ。
type BulkFile struct {
Key string `json:"Key"` // ファイルのキー(/bulk/get でのダウンロード時に使用。e.g. equities/bars/daily/historical/2025/equities_bars_daily_202501.csv.gz)
LastModified string `json:"LastModified"` // 最終更新日時(ISO 8601形式)
Size int64 `json:"Size"` // ファイルサイズ(バイト)
}

// RawBulkFile is used for unmarshaling JSON response with mixed types
type RawBulkFile struct {
Key string `json:"Key"`
LastModified string `json:"LastModified"`
Size types.NullableInt64 `json:"Size"`
}

// UnmarshalJSON implements custom JSON unmarshaling for BulkListResponse
func (r *BulkListResponse) UnmarshalJSON(data []byte) error {
// First unmarshal into RawBulkFile
type rawResponse struct {
Data []RawBulkFile `json:"data"`
}

var raw rawResponse
if err := json.Unmarshal(data, &raw); err != nil {
return err
}

// Convert RawBulkFile to BulkFile
r.Data = make([]BulkFile, len(raw.Data))
for idx, rbf := range raw.Data {
r.Data[idx] = BulkFile{
Key: rbf.Key,
LastModified: rbf.LastModified,
Size: rbf.Size.Or(0),
}
}

return nil
}

// BulkGetParams はファイルダウンロード用URL取得のリクエストパラメータです。
// key単独、またはendpointとdateの組み合わせのどちらかを指定します(keyとendpoint/dateの併用は不可)。
type BulkGetParams struct {
Key string // ファイルのキー(/bulk/list で取得したKey)
Endpoint string // 対象データのエンドポイント名(e.g. /equities/bars/daily。dateと組み合わせて使用)
Date string // 対象日付(YYYY-MM、YYYYMM、YYYY-MM-DD、YYYYMMDD。endpointと組み合わせて使用)
}

// GetFiles はダウンロード可能ファイル一覧を取得します。
// endpointとして取引カレンダー(/markets/calendar)を指定した場合、from/toの期間に関わらず最新の1ファイルのみが返されます。
func (s *BulkService) GetFiles(ctx context.Context, params BulkListParams) (*BulkListResponse, error) {
// endpoint、dateのいずれかが必須
if params.Endpoint == "" && params.Date == "" {
return nil, fmt.Errorf("either endpoint or date parameter is required")
}
// from/toはendpoint指定時のみ使用可能
if (params.From != "" || params.To != "") && params.Endpoint == "" {
return nil, fmt.Errorf("from/to parameters can only be used with endpoint parameter")
}

path := "/bulk/list"

query := "?"
if params.Endpoint != "" {
query += fmt.Sprintf("endpoint=%s&", params.Endpoint)
}
if params.Date != "" {
query += fmt.Sprintf("date=%s&", params.Date)
}
if params.From != "" {
query += fmt.Sprintf("from=%s&", params.From)
}
if params.To != "" {
query += fmt.Sprintf("to=%s&", params.To)
}

if len(query) > 1 {
path += query[:len(query)-1] // Remove trailing &
}

var resp BulkListResponse
if err := s.client.DoRequest(ctx, "GET", path, nil, &resp); err != nil {
return nil, fmt.Errorf("failed to get bulk file list: %w", err)
}

return &resp, nil
}

// GetDownloadURL はファイルダウンロード用の署名付きURLを取得します。
// 取得したURLの有効期限は5分で、再利用はできません。ファイルはgzip形式で圧縮されたCSVです。
func (s *BulkService) GetDownloadURL(ctx context.Context, params BulkGetParams) (string, error) {
// key単独、またはendpointとdateの組み合わせのどちらかが必須
if params.Key != "" && (params.Endpoint != "" || params.Date != "") {
return "", fmt.Errorf("key parameter cannot be combined with endpoint or date parameter")
}
if params.Key == "" && (params.Endpoint == "" || params.Date == "") {
return "", fmt.Errorf("either key or endpoint and date parameters are required")
}

path := "/bulk/get"

query := "?"
if params.Key != "" {
query += fmt.Sprintf("key=%s&", params.Key)
}
if params.Endpoint != "" {
query += fmt.Sprintf("endpoint=%s&", params.Endpoint)
}
if params.Date != "" {
query += fmt.Sprintf("date=%s&", params.Date)
}

if len(query) > 1 {
path += query[:len(query)-1] // Remove trailing &
}

var resp struct {
URL string `json:"url"`
}
// 署名付きURLは5分で失効し1回限りのため、キャッシュを経由しない
if err := client.DoRequestNoCache(ctx, s.client, "GET", path, nil, &resp); err != nil {
return "", fmt.Errorf("failed to get bulk download URL: %w", err)
}

return resp.URL, nil
}
Loading
Loading