Screener

POST

/screener

Retorna uma lista filtrada e ranqueada de empresas com base em critérios de mercado e fundamentos (ex.: preço, volume, setor, ratios “droplets”).

Como funciona

1. Você envia um conjunto de filters (critérios de inclusão/exclusão).
2. Opcionalmente define sort (ordenação por campos ou por um droplet específico).
3. O endpoint retorna:
   • metadata com o espelho da consulta (ordenação, limite, quantidade retornada)
   • data com os resultados ranqueados e o detalhamento de como cada filtro/sort foi aplicado em cada empresa

O screener utiliza o último pregão (cotações) e os últimos ratios publicados para cada empresa.

---

Parâmetros de requisição (body JSON)

Parâmetro	Tipo	Descrição	Obrigatório
limit	integer	Máximo de resultados (1–500). Default: 50.	Opcional
primaryOnly	boolean	Se true, retorna apenas o ticker mais líquido por empresa. Default: true.	Opcional
filters	array	Lista de filtros (objetos).	Opcional
sort	array	Lista de critérios de ordenação. Default: [{ "by": "volume", "order": "desc" }]	Opcional

---

Ordenação (sort)

Array de objetos no formato:

[{ "by": "<campo>", "order": "asc" }
  { "by": "close_price", "order": "desc" }
]

Tipos de filtros

Escalar (preço, volume, funcionários)

Campos: close_price, volume, employee_count. Use op e value (ou min/max para between).

{ "type": "close_price", "op": ">=", "value": 10 }

{ "type": "volume", "op": ">", "value": 100000 }

{ "type": "employee_count", "op": "between", "min": 100, "max": 5000 }

Setor

{ "type": "sector", "in": ["FINANCIALS", "INFORMATION_TECHNOLOGY"] }

IDs podem ser macrosetores (ex.: FINANCIALS) ou microsetores (ex.: TRADITIONAL_BANKS). Macrosetores são expandidos internamente.

Ratio (droplet)

type é "droplet" e o ID do ratio vai em id (sem prefixo droplet:).

{ "type": "droplet", "id": "PRICE_TO_EARNINGS", "op": "<", "value": 15 }

Para intervalo: { "type": "droplet", "id": "PRICE_TO_EARNINGS", "op": "between", "min": 5, "max": 20 }

Operadores

Operador	Descrição	Uso
">="	Maior ou igual	value
">"	Maior	value
"<="	Menor ou igual	value
"<"	Menor	value
"=="	Igual	value
"between"	Entre (inclusive)	min e max

Exemplo de body

{
  "sort": [{ "by": "droplet:PRICE_TO_EARNINGS", "order": "asc" }],
  "limit": 5,
  "primaryOnly": true,
  "filters": [
    { "type": "close_price", "op": ">=", "value": 10 },
    { "type": "sector", "in": ["FINANCIALS", "INFORMATION_TECHNOLOGY"] },
    { "type": "droplet", "id": "PRICE_TO_EARNINGS", "op": "<", "value": 15 }
  ]
}

Resposta

Código	Descrição
200	Retorna a lista ranqueada.
400	Parâmetros ausentes ou inválidos.
401	Não autorizado.

Formato da resposta

A resposta é um objeto com os campos abaixo:

Campo	Tipo	Descrição
metadata	object	Espelho da consulta e contagem de resultados.
data	array	Resultados ranqueados.
sort	array	Mostra o(s) critério(s) e o value usado na ordenação.
filters	array	Mostra cada filtro com o valor aplicado (applied_value) ou, no caso de droplet, o resolved_id quando aplicável.

Exemplo

{
  "metadata": {
    "sort": [{ "by": "droplet:PRICE_TO_EARNINGS", "order": "asc" }],
    "limit": 5,
    "primaryOnly": true,
    "count": 1
  },
  "data": [
    {
      "rank": 1,
      "ticker": "NEXP3",
      "trading_name": "NEXPE",
      "current_price": 3.39,
      "sector_id": "FINANCIALS",
      "sector_name": "Financeiro",
      "sort": [
        {
          "by": "droplet:PRICE_TO_EARNINGS",
          "order": "asc",
          "value": 0.0857549239020555
        }
      ],
      "filters": [
        {
          "type": "close_price",
          "op": ">=",
          "value": 10,
          "applied_value": 3.39
        },
        {
          "type": "droplet",
          "id": "PRICE_TO_EARNINGS",
          "op": "<",
          "resolved_id": "PRICE_TO_EARNINGS_CS",
          "value": 0.086
        }
      ]
    }
  ]
}

informação

O screener usa sempre o último pregão (cotações) e os últimos ratios publicados para cada empresa.