ibge

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Jun 14, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

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

View Source
const BaseURL = "https://" + Host

BaseURL is the root every request is built from.

View Source
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.

View Source
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

func (c *Client) Get(ctx context.Context, url string) ([]byte, error)

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

func (c *Client) GetNameFrequency(ctx context.Context, name string) ([]*NameFrequency, error)

GetNameFrequency returns census frequency data for a given name, flattened to one NameFrequency record per decade.

func (*Client) GetNews

func (c *Client) GetNews(ctx context.Context, limit int) ([]*News, error)

GetNews returns recent IBGE news items.

func (*Client) GetRegions

func (c *Client) GetRegions(ctx context.Context) ([]*Region, error)

GetRegions returns the 5 Brazilian macro-regions.

func (*Client) GetStates

func (c *Client) GetStates(ctx context.Context) ([]*State, error)

GetStates returns all 27 Brazilian states.

type Config

type Config struct {
	UserAgent string
	Rate      time.Duration
	Retries   int
	Timeout   time.Duration
}

Config holds optional overrides a caller can inject before building a Client.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns sensible defaults.

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

func (Domain) Classify(input string) (uriType, id string, err error)

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.

func (Domain) Locate

func (Domain) Locate(uriType, id string) (string, error)

Locate is the inverse: the live https URL for a (type, id).

func (Domain) Register

func (Domain) Register(app *kit.App)

Register installs the client factory and every operation onto app.

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.

type Region

type Region struct {
	ID   int    `kit:"id" json:"id"`
	Code string `json:"code"`
	Name string `json:"name"`
}

Region represents one of the 5 Brazilian macro-regions.

type State

type State struct {
	ID     int    `kit:"id" json:"id"`
	Code   string `json:"code"`   // sigla e.g. "SP"
	Name   string `json:"name"`   // nome e.g. "São Paulo"
	Region string `json:"region"` // regiao.nome e.g. "Sudeste"
}

State represents a Brazilian state (unidade federativa).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL