Reference¶

Queries¶

`transferegovpy.get(module, table, *, limit=1000, offset=0, page_size=MAX_PAGE, use_cache=None, base_url=None, **filters)` ¶

Retrieve rows from a TransfereGov table.

Filters

Name each filter after one of the table's query parameters and give it a single value. Parameters are combined with AND::

tg.get("parcerias", "proposta", situacao_proposta="Aprovada")
tg.get("parcerias", "proposta", sg_uf_recebedor="PE", ano_proposta=2025)

The services compare for equality and nothing else: there is no greater-than, no pattern match and no "is one of". A parameter takes one value, so query each value and concatenate the results when you need several.

Parameter names, and the permitted values of the enumerated ones, are in Portuguese because they belong to the API. Use :func:~transferegovpy.params to see them. A name the packaged schema does not know is an error rather than a request: these services ignore a parameter they do not recognise and answer with the whole table, so an unchecked typo would return plausible, wrong data.

Pagination

The services return at most 200 rows per request, so limit above that is met by fetching successive pages. limit counts rows, not pages; use math.inf for every matching row. Several tables hold hundreds of thousands of rows, so check the size with :func:count first.

Row order is the server's and cannot be set: these APIs publish no ordering parameter. It was checked to be stable across page sizes, across repeated calls and at depth, which is what makes multi-page collection safe. The number of rows collected is checked against the total the API reports, and a mismatch is reported as a warning.

Parameters:

Name	Type	Description	Default
`module`	`str`	`"especiais"`, `"fundoafundo"` or `"parcerias"`. Aliases such as `"fundo_a_fundo"` are accepted.	required
`table`	`str`	A table name from :func:`~transferegovpy.tables`.	required
`limit`	`float \| int`	Maximum number of rows to return. `math.inf` for every matching row.	`1000`
`offset`	`int`	Rows to skip before the first one returned.	`0`
`page_size`	`int`	Rows per request, between 1 and 200.	`MAX_PAGE`
`use_cache`	`bool \| None`	Serve the request from the response cache. `None` follows :func:`~transferegovpy.cache_enabled`.	`None`
`base_url`	`str \| None`	Override the API base URL.	`None`

Returns:

Type	Description
`DataFrame`	:func:`metadata` reports the totals the API gave and how many pages were fetched. A column the API sends as an array of objects comes back holding lists; `fields(nested=)` describes what is inside.

`transferegovpy.count(module, table, *, use_cache=None, base_url=None, **filters)` ¶

Count the rows a query matches without retrieving them.

Worth doing before a large :func:get: the biggest table in these APIs holds over a million rows, which at 200 rows a request is more than five thousand requests.

`transferegovpy.updated_at(module, base_url=None)` ¶

When a module's data was last refreshed.

Each module publishes the timestamp of its last load. It is the only freshness signal these APIs give: they send no ETag, Cache-Control or Last-Modified header.

`transferegovpy.especiais(table, **kwargs)` ¶

:func:get with the module fixed to "especiais".

`transferegovpy.fundo_a_fundo(table, **kwargs)` ¶

:func:get with the module fixed to "fundoafundo".

`transferegovpy.parcerias(table, **kwargs)` ¶

:func:get with the module fixed to "parcerias".

`transferegovpy.metadata` ¶

Discovery: what the APIs publish, without making a request.

`modules()` ¶

List the TransfereGov API modules.

Returns:

Type	Description
`DataFrame`	One row per module: its name, the label used in this documentation, the number of tables it publishes, and its API base URL.

`tables(module=None, counts=False)` ¶

List the tables a module publishes.

Parameters:

Name	Type	Description	Default
`module`	`str \| None`	A module name from :func:`modules`. Aliases such as `"fundo_a_fundo"` are accepted. `None` lists the tables of every module.	`None`
`counts`	`bool`	Add a `rows` column with the number of rows each table currently holds. This is the only part of this function that needs a network connection: it makes one request per table, so `tables(counts=True)` with no module makes fifty-five. Responses are cached.	`False`

Returns:

Type	Description
`DataFrame`	One row per table: its module, name, the endpoint path it maps to, its number of columns and filterable parameters, and the description published in the schema.

`fields(module, table, nested=None)` ¶

List the columns of a table.

Column names stay in Portuguese because they are the API's own contract. Not every column can be filtered on; :func:~transferegovpy.params lists the ones that can.

Parameters:

Name	Type	Description	Default
`module`	`str`	A module name from :func:`modules`.	required
`table`	`str`	A table name from :func:`tables`.	required
`nested`	`str \| None`	The name of a list column, to describe the columns of the objects inside it instead of the table's own. `None` describes the table.	`None`

Returns:

Type	Description
`DataFrame`	One row per column: its name, the pandas dtype the package coerces it to, the type the API declares, the sub-schema it nests when it is a list column, and its description.

`schema_date()` ¶

When the packaged schema was taken from the APIs.

The package validates filters and types columns against a copy of the APIs' OpenAPI documents taken on this date. A column added upstream since then is still returned, but is typed by inspection rather than from the schema.

Discovery¶

`transferegovpy.modules()` ¶

List the TransfereGov API modules.

Returns:

Type	Description
`DataFrame`	One row per module: its name, the label used in this documentation, the number of tables it publishes, and its API base URL.

`transferegovpy.tables(module=None, counts=False)` ¶

List the tables a module publishes.

Parameters:

Name	Type	Description	Default
`module`	`str \| None`	A module name from :func:`modules`. Aliases such as `"fundo_a_fundo"` are accepted. `None` lists the tables of every module.	`None`
`counts`	`bool`	Add a `rows` column with the number of rows each table currently holds. This is the only part of this function that needs a network connection: it makes one request per table, so `tables(counts=True)` with no module makes fifty-five. Responses are cached.	`False`

Returns:

Type	Description
`DataFrame`	One row per table: its module, name, the endpoint path it maps to, its number of columns and filterable parameters, and the description published in the schema.

`transferegovpy.fields(module, table, nested=None)` ¶

List the columns of a table.

Column names stay in Portuguese because they are the API's own contract. Not every column can be filtered on; :func:~transferegovpy.params lists the ones that can.

Parameters:

Name	Type	Description	Default
`module`	`str`	A module name from :func:`modules`.	required
`table`	`str`	A table name from :func:`tables`.	required
`nested`	`str \| None`	The name of a list column, to describe the columns of the objects inside it instead of the table's own. `None` describes the table.	`None`

Returns:

Type	Description
`DataFrame`	One row per column: its name, the pandas dtype the package coerces it to, the type the API declares, the sub-schema it nests when it is a list column, and its description.

`transferegovpy.params(module, table)` ¶

List the parameters a table accepts as filters.

Every parameter may be passed to :func:~transferegovpy.get and :func:~transferegovpy.count as a keyword argument. Parameter names and their permitted values are in Portuguese because they belong to the API.

:param module: A module name from :func:~transferegovpy.modules. :param table: A table name from :func:~transferegovpy.tables. :returns: One row per parameter: its name, the pandas dtype a value maps to, the type the API declares, the permitted values when the parameter is enumerated, the pattern a value must match when it has one, and its description.

`transferegovpy.schema_date()` ¶

When the packaged schema was taken from the APIs.

The package validates filters and types columns against a copy of the APIs' OpenAPI documents taken on this date. A column added upstream since then is still returned, but is typed by inspection rather than from the schema.

Configuration¶

`transferegovpy.configure(**options)` ¶

Set connection options for the session, or read them back.

`transferegovpy.cache_dir(path=None)` ¶

Where cached responses are stored.

Called with no argument, reports the directory in use. Called with a path, switches to it for the rest of the session and creates it.

By default responses are cached in the session's temporary directory, so they are discarded when the process exits. To keep them between sessions, pass a persistent path or set TRANSFEREGOVPY_CACHE_DIR.

`transferegovpy.cache_clear()` ¶

Delete cached responses. Returns how many files were removed.

Errors¶

`transferegovpy._errors` ¶

Exceptions raised by transferegovpy.

Every error the package raises inherits from :class:TransferegovError, so a caller can catch the whole family with one except. The subclasses exist so that a caller can tell a bad query from a bad connection without parsing messages.

`TransferegovError` ¶

Bases: Exception

Base class for every error this package raises.

`SchemaError` ¶

Bases: TransferegovError

An unknown module, table or column.

`FilterError` ¶

Bases: TransferegovError

A filter that cannot be turned into a query parameter.

`URLTooLongError` ¶

Bases: TransferegovError

A request URL beyond what the service accepts.

Usually a filter built with :func:~transferegovpy.in_ over a long vector.

`ResponseError` ¶

Bases: TransferegovError

A response the package cannot make sense of.

`HTTPError` ¶

Bases: TransferegovError

A non-success HTTP status.

Attributes:

Name	Type	Description
`status`		The HTTP status code.
`detail`		The `message`, `details` and `hint` fields of the PostgREST error body, when it sent one.

`IncompleteResultWarning` ¶

Bases: UserWarning

Fewer rows were collected than the API reported as matching.

`ColumnTypeWarning` ¶

Bases: UserWarning

A column could not be coerced to the type the schema declares.

Reference¶

Queries¶

transferegovpy.get(module, table, *, limit=1000, offset=0, page_size=MAX_PAGE, use_cache=None, base_url=None, **filters) ¶

transferegovpy.count(module, table, *, use_cache=None, base_url=None, **filters) ¶

transferegovpy.updated_at(module, base_url=None) ¶

transferegovpy.especiais(table, **kwargs) ¶

transferegovpy.fundo_a_fundo(table, **kwargs) ¶

transferegovpy.parcerias(table, **kwargs) ¶

transferegovpy.metadata ¶

modules() ¶

tables(module=None, counts=False) ¶

fields(module, table, nested=None) ¶

schema_date() ¶

Discovery¶

transferegovpy.modules() ¶

transferegovpy.tables(module=None, counts=False) ¶

transferegovpy.fields(module, table, nested=None) ¶

transferegovpy.params(module, table) ¶

transferegovpy.schema_date() ¶

Configuration¶

transferegovpy.configure(**options) ¶

transferegovpy.cache_dir(path=None) ¶

transferegovpy.cache_clear() ¶

Errors¶

transferegovpy._errors ¶

TransferegovError ¶

SchemaError ¶

FilterError ¶

URLTooLongError ¶

ResponseError ¶

HTTPError ¶

IncompleteResultWarning ¶

ColumnTypeWarning ¶

`transferegovpy.get(module, table, *, limit=1000, offset=0, page_size=MAX_PAGE, use_cache=None, base_url=None, **filters)` ¶

`transferegovpy.count(module, table, *, use_cache=None, base_url=None, **filters)` ¶

`transferegovpy.updated_at(module, base_url=None)` ¶

`transferegovpy.especiais(table, **kwargs)` ¶

`transferegovpy.fundo_a_fundo(table, **kwargs)` ¶

`transferegovpy.parcerias(table, **kwargs)` ¶

`transferegovpy.metadata` ¶

`modules()` ¶

`tables(module=None, counts=False)` ¶

`fields(module, table, nested=None)` ¶

`schema_date()` ¶

`transferegovpy.modules()` ¶

`transferegovpy.tables(module=None, counts=False)` ¶

`transferegovpy.fields(module, table, nested=None)` ¶

`transferegovpy.params(module, table)` ¶

`transferegovpy.schema_date()` ¶

`transferegovpy.configure(**options)` ¶

`transferegovpy.cache_dir(path=None)` ¶

`transferegovpy.cache_clear()` ¶

`transferegovpy._errors` ¶

`TransferegovError` ¶

`SchemaError` ¶

`FilterError` ¶

`URLTooLongError` ¶

`ResponseError` ¶

`HTTPError` ¶

`IncompleteResultWarning` ¶

`ColumnTypeWarning` ¶