brmarket

README

brmarket

Go package to fetch index composition from B3, the Brazilian stock exchange. Given an index symbol (e.g. IBOV), it returns the constituent securities and their theoretical weights.

Each call makes a live HTTP request to B3's public IndexComposition endpoint, so it needs network access and can fail with network, status, or decoding errors.

Install

go get github.com/cesarvspr/brmarket/v2

Usage

package main

import (
	"fmt"
	"log"

	"github.com/cesarvspr/brmarket/v2"
)

func main() {
	info, err := brmarket.GetSharesForIndex(brmarket.IBOV.String())
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%s (%s): %d constituents\n",
		info.Index.Symbol, info.Index.Description, len(info.UnderlyingList))

	for _, c := range info.UnderlyingList {
		fmt.Printf("  %-6s %.3f%%\n", c.Symb, c.IndxCmpnPctg)
	}
}

Context, deadlines, cancellation

Use GetSharesForIndexContext to control the request lifetime:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

info, err := brmarket.GetSharesForIndexContext(ctx, brmarket.IBOV.String())

GetSharesForIndex is a thin wrapper that calls this with context.Background() and a default 15s client timeout.

Errors

Errors are wrapped and can be matched with errors.Is:

_, err := brmarket.GetSharesForIndex("NOPE")
if errors.Is(err, brmarket.ErrIndexNotFound) {
	// unsupported symbol
}

Sentinel	Meaning
ErrIndexNotFound	the symbol is not a supported B3 index
ErrUnexpectedStatus	B3 returned a non-200 HTTP status
ErrUnexpectedResponse	B3 returned 200 but the body was not a valid index composition

Working with index symbols

idx, err := brmarket.ParseIndexType("IBOV") // brmarket.IBOV, nil
sym := brmarket.IBOV.String()               // "IBOV"

Supported indexes

IBOV  IBXX  IBXL  IBRA  IGCX  ITAG  IGNM  IGCT
IDIV  MLCX  SMLL  IVBX  ICO2  ISEE  ICON  IEEX
IFNC  IMOB  INDX  IMAT  UTIL  IFIX  IFIL  BDRX
GPTW  IDVR  IBLV  IBSD  IBHB

License

MIT

Documentation

Overview

Package brmarket fetches B3 (the Brazilian stock exchange) market-index composition over HTTP.

The entry point is GetSharesForIndex, which returns the constituents and theoretical weights of a B3 index such as IBOV. GetSharesForIndexContext is the context-aware variant. Supported indexes are the IndexType constants (IBOV, IBXX, ... BDRX); use ParseIndexType to turn a symbol string into an IndexType, or IndexType.String to go the other way.

Every fetch performs a live HTTP request against B3's public IndexComposition endpoint, so it requires network access and may fail with network, status, or decoding errors. Errors are wrapped and can be matched with errors.Is against ErrIndexNotFound, ErrUnexpectedStatus, and ErrUnexpectedResponse.

Index

• Variables
• type B3IndexInfo
  • func GetSharesForIndex(index string) (B3IndexInfo, error)
  • func GetSharesForIndexContext(ctx context.Context, index string) (B3IndexInfo, error)
  • func (b B3IndexInfo) UpdatedAt() (time.Time, error)
• type BizStatus
• type Constituent
• type IndexMeta
• type IndexType
  • func IndexFromString(input string) (*IndexType, error)
  • func ParseIndexType(symbol string) (IndexType, error)
  • func (i IndexType) String() string
• type Message

Examples

• GetSharesForIndex
• IndexType.String

Variables

var (
	// ErrIndexNotFound is returned when a symbol does not match a supported B3 index.
	ErrIndexNotFound = errors.New("brmarket: index not found")
	// ErrUnexpectedStatus is returned when B3 responds with a non-200 HTTP status.
	ErrUnexpectedStatus = errors.New("brmarket: unexpected HTTP status")
	// ErrUnexpectedResponse is returned when B3 responds 200 but the body is not a
	// recognizable index composition (for example a WAF/HTML page or an error
	// envelope that decodes into an empty result).
	ErrUnexpectedResponse = errors.New("brmarket: unexpected response body")
)

Sentinel errors returned by this package. Match them with errors.Is.

Types

type B3IndexInfo

type B3IndexInfo struct {
	BizSts         BizStatus     `json:"BizSts"`
	Index          IndexMeta     `json:"Index"`
	UnderlyingList []Constituent `json:"UnderlyingList"`
	Msg            Message       `json:"Msg"`
}

B3IndexInfo is the index-composition payload returned by B3.

func GetSharesForIndex

func GetSharesForIndex(index string) (B3IndexInfo, error)

GetSharesForIndex returns the B3 index composition for the given index symbol (for example "IBOV", or brmarket.IBOV.String()). Only Brazilian indexes are supported; an unsupported symbol yields ErrIndexNotFound.

It performs a live HTTP request with a default timeout. Use GetSharesForIndexContext when you need to control cancellation or deadlines.

Example

This example fetches the IBOV composition and prints each constituent's weight. It deliberately omits an "// Output:" line, so go test compiles it (keeping the docs honest) without making a live network call during the test run.

package main

import (
	"fmt"
	"log"

	"github.com/cesarvspr/brmarket/v2"
)

func main() {
	info, err := brmarket.GetSharesForIndex(brmarket.IBOV.String())
	if err != nil {
		log.Fatal(err)
	}
	for _, c := range info.UnderlyingList {
		fmt.Printf("%s: %.3f%%\n", c.Symb, c.IndxCmpnPctg)
	}
}

func GetSharesForIndexContext

func GetSharesForIndexContext(ctx context.Context, index string) (B3IndexInfo, error)

GetSharesForIndexContext is like GetSharesForIndex but honors the provided context for cancellation and deadlines.

func (B3IndexInfo) UpdatedAt

func (b B3IndexInfo) UpdatedAt() (time.Time, error)

UpdatedAt parses the response timestamp (Msg.DtTm) into a time.Time. B3 sends the timestamp without a timezone, so the result is in UTC's wall-clock form; treat it as the exchange's local time.

type BizStatus

type BizStatus struct {
	Cd string `json:"cd"`
}

BizStatus carries B3's business-status code for the response.

type Constituent

type Constituent struct {
	IndexTheoreticalQty float64 `json:"indexTheoreticalQty"`
	IndxCmpnPctg        float64 `json:"indxCmpnPctg"`
	Symb                string  `json:"symb"`
	Desc                string  `json:"desc"`
}

Constituent is a single security that makes up an index, with its theoretical quantity and percentage weight.

type IndexMeta

type IndexMeta struct {
	Symbol      string `json:"symbol"`
	Description string `json:"description"`
}

IndexMeta identifies the index a composition belongs to.

type IndexType

type IndexType int

IndexType identifies a B3 (the Brazilian stock exchange) market index.

const (
	IBOV IndexType = iota
	IBXX
	IBXL
	IBRA
	IGCX
	ITAG
	IGNM
	IGCT
	IDIV
	MLCX
	IVBX
	ICO2
	ISEE
	ICON
	IEEX
	IFNC
	IMOB
	INDX
	IMAT
	UTIL
	IFIX
	BDRX

	// Added in v2.1.0. When you add a constant here, add a matching entry to
	// indexNames below; the round-trip test enforces they stay in sync.
	SMLL
	IFIL
	GPTW
	IDVR
	IBLV
	IBSD
	IBHB
)

The B3 indexes this package can fetch. The zero value is IBOV.

func IndexFromString

func IndexFromString(input string) (*IndexType, error)

IndexFromString returns the IndexType for a B3 symbol.

Deprecated: use ParseIndexType, which returns the value directly instead of a pointer. IndexFromString is kept for backwards compatibility.

func ParseIndexType

func ParseIndexType(symbol string) (IndexType, error)

ParseIndexType returns the IndexType for a B3 symbol such as "IBOV". It returns ErrIndexNotFound (wrapped) if the symbol is not a supported index.

func (IndexType) String

func (i IndexType) String() string

String returns the B3 symbol for the index, e.g. "IBOV". It never panics: values outside the known range render as "IndexType(<n>)", matching the convention used by stringer-generated code (fmt may call String implicitly).

Example

package main

import (
	"fmt"

	"github.com/cesarvspr/brmarket/v2"
)

func main() {
	fmt.Println(brmarket.IBOV)
	fmt.Println(brmarket.BDRX)
}

Output:
IBOV
BDRX

type Message

type Message struct {
	DtTm string `json:"dtTm"`
}

Message carries response metadata such as the generation timestamp.