Documentation
¶
Overview ¶
Package ibge is the library behind the ibge command line: the HTTP client, request shaping, and the typed data models for the IBGE (Brazilian Institute of Geography and Statistics) public API at servicodados.ibge.gov.br. No API key is required.
The Client here is the spine every command shares. It sets a real User-Agent, paces requests so a busy session stays polite, and retries the transient failures (429 and 5xx) that any public API throws under load. Build your endpoint calls and JSON decoding on top of it.
Index ¶
- Constants
- type Client
- func (c *Client) Get(ctx context.Context, url string) ([]byte, error)
- func (c *Client) GetMunicipalities(ctx context.Context, state string, limit int) ([]*Municipality, error)
- func (c *Client) GetNameFrequency(ctx context.Context, name string) ([]*NameFrequency, error)
- func (c *Client) GetNews(ctx context.Context, limit int) ([]*News, error)
- func (c *Client) GetRegions(ctx context.Context) ([]*Region, error)
- func (c *Client) GetStates(ctx context.Context) ([]*State, error)
- type Config
- type Domain
- type Municipality
- type NameFrequency
- type News
- type Region
- type State
Constants ¶
const BaseURL = "https://" + Host
BaseURL is the root every request is built from.
const DefaultUserAgent = "ibge/dev (+https://github.com/tamnd/ibge-cli)"
DefaultUserAgent identifies the client to the IBGE API. A real, honest User-Agent is both polite and the thing most likely to keep you unblocked.
const Host = "servicodados.ibge.gov.br"
Host is the API host this client talks to.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
HTTP *http.Client
UserAgent string
// Rate is the minimum gap between requests. Zero means no pacing.
Rate time.Duration
Retries int
// contains filtered or unexported fields
}
Client talks to the IBGE API over HTTP.
func NewClient ¶
func NewClient() *Client
NewClient returns a Client with sensible defaults: a 30s timeout, a 300ms minimum gap between requests, and five retries on transient errors.
func (*Client) Get ¶
Get fetches url and returns the response body. It paces and retries according to the client's settings. The caller owns nothing extra; the body is read fully and closed here.
func (*Client) GetMunicipalities ¶
func (c *Client) GetMunicipalities(ctx context.Context, state string, limit int) ([]*Municipality, error)
GetMunicipalities returns municipalities, optionally filtered by state code. limit ≤ 0 means return all (uses the API's default pagination behaviour).
func (*Client) GetNameFrequency ¶
GetNameFrequency returns census frequency data for a given name, flattened to one NameFrequency record per decade.
func (*Client) GetRegions ¶
GetRegions returns the 5 Brazilian macro-regions.
type Domain ¶
type Domain struct{}
Domain is the ibge driver. It carries no state; the per-run client is built by the factory Register hands kit.
func (Domain) Classify ¶
Classify turns any accepted input into the canonical (type, id). - numeric string → ("municipality", id) - 2-letter uppercase → ("state", code) - otherwise → ("name", name)
func (Domain) Info ¶
func (Domain) Info() kit.DomainInfo
Info describes the scheme, the hostnames a pasted link is matched against, and the identity reused for the binary's help and version.
type Municipality ¶
type Municipality struct {
ID int `kit:"id" json:"id"`
Name string `json:"name"`
State string `json:"state"` // UF.sigla
StateName string `json:"state_name"` // UF.nome
MicroRegion string `json:"micro_region"`
MesoRegion string `json:"meso_region"`
}
Municipality represents a Brazilian municipality (city).
type NameFrequency ¶
type NameFrequency struct {
Name string `kit:"id" json:"name"`
Period string `json:"period"`
Count int `json:"count"`
}
NameFrequency holds the census frequency of a name in one decade.
type News ¶
type News struct {
ID int `kit:"id" json:"id"`
Title string `json:"title"`
Intro string `json:"intro"`
Published string `json:"published"` // data_publicacao
Type string `json:"type"`
}
News is one IBGE news item.