openfigi

package module
v1.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 5, 2025 License: Apache-2.0 Imports: 12 Imported by: 0

README

openfigi

A client for the OpenFIGI API.

Types of queries

  • Search
  • Filter (Search but with total count)
  • Mapping

Instructions

  1. Construct a builder.

    • Search and Filter use BaseItemBuilder, then construct a BaseItem.
    • Mapping uses MappingItemBuilder, then construct a MappingItem. MappingRequest is []MappingItem.

  2. Set the properties through setters. (.Set[...](...))

  3. Build the item (.Build()). The package will validate the content of the item, reducing bad API calls.

  4. [optional] API Key, set with SetAPIKey(string).

  5. Use the client to make the request.

    • BaseItem use .[Search|Filter](query string, start string) returning SearchResponse or FilterResponse
    • MappingRequest use .Fetch() returning []SingleMappingResponse
    • SearchResponse and FilterResponse have a .Next() method to fetch the next page.

Developing

  • make generate to generate the constants and hashset for validation
  • make test for testing, will run make generate

Documentation

Overview

openfigi: a client for the OpenFIGI API.

3 types of queries:

  • Search
  • Filter (Search but with total count)
  • Mapping

Instructions:

  1. Construct a builder.

    - Search and Filter use BaseItemBuilder, then construct a BaseItem.

    - Mapping uses MappingItemBuilder, then construct a MappingItem. MappingRequest is []MappingItem.

  2. Set the properties through setters. (".Set[...](...)")

  3. Build the item: BaseItemBuilder.Build, MappingItemBuilder.Build. The package will validate the content of the item, reducing bad API calls.

  4. [optional] API Key, set with SetAPIKey.

  5. Use the client to make the request.

    - BaseItem.Search, BaseItem.Filter, returning SearchResponse or FilterResponse

    - MappingRequest.Fetch returning []SingleMappingResponse

    - SearchResponse.Next, FilterResponse.Next to fetch the next page.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func APIBaseUrl 

func APIBaseUrl() string

func APIKey 

func APIKey() string

func SetAPIBaseUrl 

func SetAPIBaseUrl(url string)

func SetAPIKey 

func SetAPIKey(url string)

Types

type BaseItem 

type BaseItem struct {
	// Exchange code (cannot use in conjunction with `micCode`).
	// See https://api.openfigi.com/v3/mapping/values/exchCode
	ExchCode string `json:"exchCode,omitempty"`
	// ISO market identification code(MIC) (cannot use in conjunction with `exchCode`).
	// See https://api.openfigi.com/v3/mapping/values/micCode
	MicCode string `json:"micCode,omitempty"`
	// Currency.
	// See https://api.openfigi.com/v3/mapping/values/currency
	Currency string `json:"currency,omitempty"`
	// Market sector description.
	// See https://api.openfigi.com/v3/mapping/values/marketSecDes
	MarketSecDes string `json:"marketSecDes,omitempty"`
	// Security type.
	// See https://api.openfigi.com/v3/mapping/values/securityType
	SecurityType string `json:"securityType,omitempty"`
	// An alternative security type. `securityType2` is typically less specific than `securityType`.
	// Use `marketSecDes` if `securityType2` is not available.
	// See https://api.openfigi.com/v3/mapping/values/securityType2
	SecurityType2 string `json:"securityType2,omitempty"`
	// `true` to include equity instruments that are not listed on an exchange.
	IncludeUnlistedEquities bool `json:"includeUnlistedEquities,omitempty"`
	// Option type. Values: "Call" | "Put"
	OptionType string `json:"optionType,omitempty"`
	// Strike price interval, [a, b], where a, b are Numbers or null.
	// At least one entry must be a Number. When both are Numbers, a <= b.
	// [a, null]: [a, ∞); [null, b]: (-∞, b].
	Strike *interval[float64] `json:"strike,omitempty"`
	// Contract size interval, [a, b], where a, b are Numbers or null.
	// At least one entry must be a Number. When both are Numbers, a <= b.
	// [a, null]: [a, ∞); [null, b]: (-∞, b].
	ContractSize *interval[float64] `json:"contractSize,omitempty"`
	// Coupon interval, [a, b], where a, b are Numbers or null.
	// At least one entry must be a Number. When both are Numbers, a <= b.
	// [a, null]: [a, ∞); [null, b]: (-∞, b].
	Coupon *interval[float64] `json:"coupon,omitempty"`
	// Expiration date interval, [a, b], where a, b are date Strings [YYYY-MM-DD] or null.
	// At least one entry must be a date String.
	// When both are date String, a and b are no more than 1 year apart.
	// [a, null]: [a, a + (1Y)]; [null, b]: [b - (1Y), b].
	// **Requirement**: `securityType2` is `Option`.
	Expiration *interval[string] `json:"expiration,omitempty"`
	// Maturity interval, [a, b], where a, b are date Strings [YYYY-MM-DD] or null.
	// At least one entry must be a date String.
	// When both are date String, a and b are no more than 1 year apart.
	// [a, null]: [a, a + (1Y)]; [null, b]: [b - (1Y), b].
	// **Requirement**: `securityType2` is `Pool`.
	Maturity *interval[string] `json:"maturity,omitempty"`
	// State code.
	// See https://api.openfigi.com/v3/mapping/values/stateCode
	StateCode string `json:"stateCode,omitempty"`
}

func (*BaseItem) AsMappingItem 

func (b_item *BaseItem) AsMappingItem(idType string, value any) (item MappingItem, err error)

Convert to MappingItem, requires `idType` and `value`

func (BaseItem) Filter 

func (item BaseItem) Filter(query string, start string) (res FilterResponse, err error)

Filter with BaseItem, query and start

Usage: 

builder := BaseItem{}.GetBuilder()
builder.SetCurrency("AUD")
item, _ := builder.Build()
res, err := item.Filter("CRYP", "QW9Fc1FrSkhNREF3TTBoYVdEVXkgMQ==.+avM2j1t25UWj8se/VnwSBhcM8LYMVpYykjqLj8hw70=")

func (BaseItem) GetBuilder 

func (BaseItem) GetBuilder() BaseItemBuilder

Usage: 

builder := BaseItem{}.GetBuilder()

func (BaseItem) Search 

func (item BaseItem) Search(query string, start string) (res SearchResponse, err error)

Search with BaseItem, query and start

Usage: 

builder := BaseItem{}.GetBuilder()
builder.SetCurrency("AUD")
item, _ := builder.Build()
res, err := item.Search("", "")

type BaseItemBuilder 

type BaseItemBuilder struct {
	// contains filtered or unexported fields
}

func (*BaseItemBuilder) Build 

func (b *BaseItemBuilder) Build() (item BaseItem, err error)

func (*BaseItemBuilder) SetContractSize 

func (b *BaseItemBuilder) SetContractSize(contractSize [2]any) *BaseItemBuilder

Usage: 

builder.SetContractSize([2]any{2.0, nil})

func (*BaseItemBuilder) SetCoupon 

func (b *BaseItemBuilder) SetCoupon(coupon [2]any) *BaseItemBuilder

Usage: 

builder.SetCoupon([2]any{nil, 2.0})

func (*BaseItemBuilder) SetCurrency 

func (b *BaseItemBuilder) SetCurrency(currency string) *BaseItemBuilder

func (*BaseItemBuilder) SetExchCode 

func (b *BaseItemBuilder) SetExchCode(exchCode string) *BaseItemBuilder

func (*BaseItemBuilder) SetExpiration 

func (b *BaseItemBuilder) SetExpiration(expiration [2]any) *BaseItemBuilder

Usage: 

builder.SetExpiration([2]any{"2021-01-01", "2022-01-01"})

func (*BaseItemBuilder) SetIncludeUnlistedEquities 

func (b *BaseItemBuilder) SetIncludeUnlistedEquities(include bool) *BaseItemBuilder

func (*BaseItemBuilder) SetMarketSecDes 

func (b *BaseItemBuilder) SetMarketSecDes(marketSecDes string) *BaseItemBuilder

func (*BaseItemBuilder) SetMaturity 

func (b *BaseItemBuilder) SetMaturity(maturity [2]any) *BaseItemBuilder

Usage: 

builder.SetMaturity([2]any{nil, "2022-01-01"})

func (*BaseItemBuilder) SetMicCode 

func (b *BaseItemBuilder) SetMicCode(micCode string) *BaseItemBuilder

func (*BaseItemBuilder) SetOptionType 

func (b *BaseItemBuilder) SetOptionType(optionType string) *BaseItemBuilder

func (*BaseItemBuilder) SetSecurityType 

func (b *BaseItemBuilder) SetSecurityType(securityType string) *BaseItemBuilder

func (*BaseItemBuilder) SetSecurityType2 

func (b *BaseItemBuilder) SetSecurityType2(securityType2 string) *BaseItemBuilder

func (*BaseItemBuilder) SetStateCode 

func (b *BaseItemBuilder) SetStateCode(stateCode string) *BaseItemBuilder

func (*BaseItemBuilder) SetStrike 

func (b *BaseItemBuilder) SetStrike(strike [2]any) *BaseItemBuilder

Usage: 

builder.SetStrike([2]any{nil, 2.0})

type FIGIObject 

type FIGIObject struct {
	FIGI                string `json:"figi,omitempty"`
	SecurityType        string `json:"securityType,omitempty"`
	MarketSector        string `json:"marketSector,omitempty"`
	Ticker              string `json:"ticker,omitempty"`
	Name                string `json:"name,omitempty"`
	UniqueID            string `json:"uniqueID,omitempty"`
	ExchangeCode        string `json:"exchCode,omitempty"`
	ShareClassFIGI      string `json:"shareClassFIGI,omitempty"`
	CompositeFIGI       string `json:"compositeFIGI,omitempty"`
	SecurityType2       string `json:"securityType2,omitempty"`
	SecurityDescription string `json:"securityDescription,omitempty"`
	Metadata            string `json:"metadata,omitempty"` // Exists when API is unable to show non-FIGI fields
}

FIGI Object returned by the API

type FilterResponse 

type FilterResponse struct {
	SearchResponse
	Total int `json:"total"`
}

func (FilterResponse) Next 

func (filterRes FilterResponse) Next() (FilterResponse, error)

Continue filtering with previous FilterResponse using the "next" field of API response. Returns an error if there are no more results or filter error

Usage: 

res, err := item.Filter("CRYP", "")
if err != nil {
	fmt.Println("Error filtering:", err)
}
fmt.Printf("\n%+v\n", res.Data)
next, err := res.Next()
if err != nil {
	fmt.Println("Filter pause due to:", err)
}

type MappingItem 

type MappingItem struct {
	// BaseRequest fields
	BaseItem
	// Type of third party identifier. See https://www.openfigi.com/api#v3-idType-values
	// **Requirement**: For `BASE_TICKER` and `ID_EXCH_SYMBOL`, `securityType2` must be provided.
	Type string `json:"idType"`
	// The value for the represented third party identifier
	Value any `json:"idValue"`
}

func (*MappingItem) AsBaseItem 

func (m_item *MappingItem) AsBaseItem() (item BaseItem, err error)

Convert to BaseItem

func (MappingItem) GetBuilder 

func (MappingItem) GetBuilder(idType string, value any) MappingItemBuilder

Usage: 

builder := MappingItem{}.GetBuilder()

type MappingItemBuilder 

type MappingItemBuilder struct {
	BaseItemBuilder
	// contains filtered or unexported fields
}

func (*MappingItemBuilder) Build 

func (m *MappingItemBuilder) Build() (item MappingItem, err error)

type MappingRequest 

type MappingRequest []MappingItem

func (MappingRequest) Fetch 

func (m_req MappingRequest) Fetch() (res []SingleMappingResponse, err error)

Fetch the mappings

Usage: 

// Setters does not chain directly to the builder
aapl_builder := MappingItem{}.GetBuilder(constants.IDTYPE_TICKER, "AAPL")
aapl_builder.SetExchCode("US")

req := MappingRequest{
	aapl_builder.Build(),
	MappingItem{}.GetBuilder("ID_BB_UNIQUE", "EQ0010080100001000").Build(),
}
res, err := req.Fetch()

func (*MappingRequest) FromMappingItemBuilders 

func (req *MappingRequest) FromMappingItemBuilders(builders ...MappingItemBuilder) error

Helper to create a MappingRequest from MappingItemBuilders

Usage: 

req := MappingRequest{}
req.FromMappingItemBuilders(
	MappingItem{}.GetBuilder(constants.IDTYPE_TICKER, "AAPL"),
	MappingItem{}.GetBuilder("ID_BB_UNIQUE", "EQ0010080100001000"),
)

type SearchResponse 

type SearchResponse struct {
	Data     []FIGIObject `json:"data"`
	Error    string       `json:"error,omitempty"`
	NextHash string       `json:"next,omitempty"`
	// contains filtered or unexported fields
}

func (SearchResponse) Next 

func (searchRes SearchResponse) Next() (SearchResponse, error)

Continue searching with previous SearchResponse using the "next" field of API response. Returns an error if there are no more results or search error

Usage: 

res, err := item.Search("CRYP", "")
if err != nil {
	fmt.Println("Error searching:", err)
}
fmt.Printf("\n%+v\n", res.Data)
next, err := res.Next()
if err != nil {
	fmt.Println("Search pause due to:", err)
}

type SingleMappingResponse 

type SingleMappingResponse struct {
	Data    []FIGIObject `json:"data"`
	Error   string       `json:"error,omitempty"`
	Warning []string     `json:"warning,omitempty"`
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.