quantbrasil rankings return
Calcula o retorno histórico de um ranking do sistema
Sintaxe
quantbrasil rankings return --system <slug> --from <date> --to <date> --rebalance <frequency>Esta é uma operação de leitura. Modos de saída: json, human.
Argumentos e opções
| Nome | Tipo | Obrigatório | Descrição | Padrão |
|---|---|---|---|---|
--system <slug> | Opção | Sim | Slug do ranking do sistema | — |
--from <date> | Opção | Sim | Data inicial em AAAA-MM-DD | — |
--to <date> | Opção | Sim | Data final em AAAA-MM-DD | — |
--top <n> | Opção | Não | Número de ativos em cada rebalanceamento | 20 |
--rebalance <frequency> | Opção | Sim | Frequência: weekly, monthly, bimonthly, quarterly, semiannually ou annually | — |
--weight <method> | Opção | Não | Método de ponderação | equal |
--index-filter <filter> | Opção | Não | Filtro: NONE, IBOV, IBX100 ou SMLL | NONE |
--json | Opção | Não | Exibe saída JSON | — |
Exemplos
quantbrasil rankings return --system magic-formula --from 2024-01-18 --to 2026-05-25 --top 20 --rebalance quarterly
quantbrasil rankings return --system momentum-90d --from 2024-01-01 --to 2026-01-01 --top 10 --rebalance monthly --jsonSaída (--json)
Estrutura da resposta retornada com --json:
export interface RankingReturnResponse {
ok: boolean;
summary_markdown: string;
ranking: RankingDefinitionOut;
result: RankingReturnResult;
}
export interface RankingDefinitionOut {
id: string;
name: string;
kind: "SYSTEM" | "USER";
description: string | null;
order_metric: RankingMetricOut;
metrics: RankingMetricOut[];
latest_as_of: string | null;
total_assets: number | null;
return_simulation: RankingReturnSimulationOut;
}
export interface RankingReturnResult {
total_return: number;
annualized_return: number;
start_date: string;
end_date: string;
top_n: number;
rebalance_frequency: string;
rebalance_dates: RankingReturnRebalance[];
period_returns: RankingReturnPeriodReturn[];
ibov_return: number;
ibov_annualized_return: number;
}
export interface RankingMetricOut {
key: string;
label: string;
direction: "asc" | "desc";
unit: string | null;
}
export interface RankingReturnSimulationOut {
supported: boolean;
earliest_start_date: string | null;
max_top_n: number | null;
}
export interface RankingReturnRebalance {
date: string;
portfolio: RankingReturnAssetAllocation[];
}
export interface RankingReturnPeriodReturn {
start_date: string;
end_date: string;
total_return: number;
asset_returns: RankingReturnAssetReturn[];
}
export interface RankingReturnAssetAllocation {
ticker: string;
weight: number;
ranking_position: number;
}
export interface RankingReturnAssetReturn {
ticker: string;
return_value: number;
weight: number;
contribution: number;
}Exemplo de resposta
{
"ok": true,
"summary_markdown": "Retorno calculado para o ranking Magic Formula de 18/01/2024 a 25/05/2026.",
"ranking": {
"id": "magic-formula",
"name": "Magic Formula",
"kind": "SYSTEM",
"description": "Ranking fatorial baseado em qualidade e preço.",
"order_metric": {
"key": "magic_rank",
"label": "Posição Magic Formula",
"direction": "asc",
"unit": null
},
"metrics": [],
"latest_as_of": "2026-05-15",
"total_assets": 120,
"return_simulation": {
"supported": true,
"earliest_start_date": "2024-01-18",
"max_top_n": 30
}
},
"result": {
"total_return": 0.42,
"annualized_return": 0.168,
"start_date": "2024-01-18",
"end_date": "2026-05-25",
"top_n": 20,
"rebalance_frequency": "quarterly",
"rebalance_dates": [
{
"date": "2024-01-18",
"portfolio": [
{
"ticker": "PETR4",
"weight": 0.05,
"ranking_position": 1
}
]
}
],
"period_returns": [
{
"start_date": "2024-01-18",
"end_date": "2024-04-18",
"total_return": 0.05,
"asset_returns": [
{
"ticker": "PETR4",
"return_value": 0.05,
"weight": 0.05,
"contribution": 0.0025
}
]
}
],
"ibov_return": 0.25,
"ibov_annualized_return": 0.1
}
}