Os parâmetros estruturam a consulta e orientam a Plataforma de Dados sobre quem localizar e qual conjunto de informações retornar.

Aqui você aprenderá:

A função de cada parâmetro (q, Datasets, Limit)
Como declarar chaves de identificação
As diferenças entre chaves principais, alternativas e opcionais
Quando e como combinar chaves
As listas completas de chaves, por tipo
Quando utilizar Limit

Esses conceitos são essenciais para que as próximas páginas façam sentido.

1️⃣ Parâmetros disponíveis

Parâmetro	Descrição	Tipo
`q`	Lista de chaves de busca da consulta, separadas por vírgula.	🛑 Obrigatório
`Datasets`	Lista de datasets retornados, podendo incluir modificadores.	🛑 Obrigatório
`Limit`	Limite máximo de entidades retornadas.	ℹ️ Opcional

2️⃣ Sobre o parâmetro `q`

O parâmetro q reúne as chaves de identificação enviadas para localizar uma entidade na Plataforma de Dados.
Ele funciona como o “quem estou tentando encontrar” dentro da sua consulta.

Cada chave segue o formato: nome_da_chave{valor}.

Exemplo simples

"q": "name{Maria Souza}"

❗️
O envio de q é obrigatório em todas as consultas.

🔑 Chaves de identificação

A Plataforma de Dados utiliza três tipos de chaves de identificação:

Chaves principais → identificam a entidade de forma única (1:1)
Chaves alternativas → podem retornar mais de uma entidade
Chaves complementares → refinam a busca e aumentam a precisão

A seguir, detalhamos cada grupo.

Chaves principais

São identificadores que possuem relação 1:1 com a entidade consultada.

Chave Principal	Descrição	Exemplo	API
`doc`	Número de Identificação de Pessoa ou Empresa (CPF/CNPJ)	`doc{12345678900}`	Pessoa ou Empresa
`zipcode`	Código Postal	`zipcode{12345000}`	Endereço
`licenseplate`	Número da Placa	`licenseplate{ABC1D23}`	Veículo
`processnumber`	Número do Processo	`processnumber{10000000120258260302}`	Processo
`receiptnumber`	Número da Nota Fiscal	`receiptnumber{123456789}`	Nota Fiscal
`ean`	Número do Código de Barras	`ean{12345678890123}`	Produto

Chaves alternativas

Quando o usuário não possuir uma chave principal, deve enviar ao menos uma chave alternativa. Por serem menos específicas, recomenda-se enviar duas ou mais chaves alternativas, ou combiná-las com chaves complementares.

Chave Alternativa	Descrição	Exemplo	API
`name`	Nome da entidade	`name{josé da silva}`	Pessoa ou Empresa
`classnumber` + `classorganization`	Número de registro em conselho de classe e nome da organização	`classnumber{123456}, classorganization{CFMSP}`	Pessoa
`nit`	Número de Inscrição do Trabalhador (ou número do RG)	`nit{123456789}`	Pessoa
`rntrc`	Número de Registro na ANTT	`rntrc{12345678}`	Pessoa ou Empresa
`domain`	Domínio (URL do site)	`domain{seudominio.com}`	Pessoa ou Empresa
`name` + `partialdoc`	Nome e informação parcial do documento de identificação da entidade	`name{big corp}, partialdoc{8768627}`	Pessoa ou Empresa

Chaves complementares

Chaves complementares não identificam sozinhas, mas ajudam a reduzir ambiguidades, aumentam a precisão e complementam as chaves alternativas.

Chaves complementares (clique para expandir)

Chave	Descrição	Exemplo
`address`	Endereço	`address{Rua das Flores, 123}`
`addresscore`	Núcleo do endereço	`addresscore{Rua das Flores}`
`addressnumber`	Número do endereço	`addressnumber{123}`
`addresstypology`	Tipologia	`addresstypology{casa}`
`all`	Retornar todas as movimentações	`all{true}`
`birthdate` + `dateformat`	Data de nascimento e formato da data enviada	`birthdate{01-10-1990}, dateformat{dd-mm-yyyy}`
`brand`	Marca dos produtos	`brand{nike}`
`buildingcode`	Código postal / inscrição do prédio	`buildingcode{123456}`
`category`	Categoria de produtos	`category{eletronicos}`
`cities`	Lista de cidades	`cities{São Paulo, Rio de Janeiro}`
`city`	Nome da cidade	`city{Curitiba}`
`cnae`	Número da Atividade Econômica	`cnae{6201501}`
`complement`	Complemento do endereço	`complement{Apto 12}`
`court`	Tribunal	`court{TRF3}`
`distance`	Tamanho do raio de pesquisa, em km	`distance{10}`
`dividaativa`	Usar fonte de Dívida Ativa	`dividaativa{true}`
`ean`	Número do código de barras	`ean{7891234567890}`
`email`	E-mail adicional de entrada	`email{exemplo@dominio.com}`
`enddate` + `dateformat`	Data de término do período a ser consultado e o formato da data enviada	`enddate{31-12-2025}, dateformat{dd-mm-yyyy}`
`extended`	Retornar todas as entidades	`extended{true}`
`fathername`	Nome do pai	`fathername{José Silva}`
`floor`	Andar do imóvel	`floor{12}`
`geocode`	Código da área definida	`geocode{1234567}`
`group_level`	Nível de relacionamentos	`group_level{2}`
`householdcode`	Código postal / inscrição da casa	`householdcode{987654}`
`indigenouslandcode`	Código da terra indígena	`indigenouslandcode{TI1234}`
`isbn`	Código ISBN	`isbn{978-3-16-148410-0}`
`keywords`	Palavras-chave	`keywords{energia solar}`
`latitude`	Latitude	`latitude{-23.5505}`
`longitude`	Longitude	`longitude{-46.6333}`
`minmatch`	Similaridade mínima, em porcentagem	`minmatch{80}`
`mothername`	Nome da mãe	`mothername{Maria Souza}`
`neighborhood`	Bairro	`neighborhood{Centro}`
`nit`	Número de Inscrição do Trabalhador	`nit{123456789}`
`op`	Esferas de pesquisa	`op{CIVIL}`
`phone`	Telefone adicional	`phone{11999999999}`
`placeofbirth`	Local de nascimento	`placeofbirth{Sorocaba}`
`polygon`	Lista de coordenadas que formam um polígono	`polygon[-63.522601288613465, -2.0852205227110474, -62.91458204285954, -2.061274857038942, -63.070330815170884, -2.4697949735684355, -63.45385082496132, -2.5320904654187366]`
`prefix`	Consultar filiais e matrizes	`prefix{true}`
`radius`	Raio de pesquisa (km)	`radius{1}`
`referencedate` + `dateformat`	Data de referência para consulta, utilizada para consultas históricas (backtest), e o formato da data enviada. Se a data enviada for inválida, o retorno considerará a data atual.	`referencedate{01-01-2020}, dateformat{dd-mm-yyyy}`
`relationshiptype`	Tipo de relacionamento	`relationshiptype{coworker}`
`returncvmprocesses`	Retornar processos da CVM	`returncvmprocesses{true}`
`returnonlydifferentaddresses`	Retornar endereços diferentes	`returnonlydifferentaddresses{true}`
`returnonlydifferentemails`	Retornar e-mails diferentes	`returnonlydifferentemails{true}`
`returnonlydifferentphones`	Retornar telefones diferentes	`returnonlydifferentphones{true}`
`returnonlyvalidemails`	Retornar apenas e-mails válidos	`returnonlyvalidemails{false}`
`returnupdates`	Retornar atualizações	`returnupdates{true}`
`rgexpeditiondate` + `dateformat`	Data de emissão do RG	`rgexpeditiondate{12-05-2010}, dateformat{dd-mm-yyyy}`
`rgissuingagency`	Agência emissora do RG	`rgissuingagency{SSP}`
`rgissuinguf`	UF emissora do RG	`rgissuinguf{SP}`
`scnr`	Código de Imóvel Rural	`scnr{123456789}`
`searchterms`	Palavras-chave para busca	`searchterms{mineração}`
`startdate` + `dateformat`	Data de início e formato da data informada	`startdate{01-2020}, dateformat{mm-yyyy}`
`state`	Estado do Brasil	`state{São Paulo}`
`stateregistration`	Inscrição Estadual	`stateregistration{123456789}`
`type`	Tipo da consulta	`type{list}`
`uf`	Unidade Federativa	`uf{RJ}`
`updateslimit`	Limite de retorno das atualizações	`updateslimit{100}`
`withmatchrate`	Utilizar taxa de similaridade	`withmatchrate{true}`
`year`	Ano de referência	`year{2023}`
`zipcode`	Código postal (CEP)	`zipcode{01311000}`

💡
Dica:
Quanto mais chaves alternativas e complementares enviar, maiores as chances de chegar à entidade correta.

❗️
Atenção:
Em determinados datasets, chaves classificadas como complementares podem tornar-se obrigatórias em função de exigências específicas das fontes de dados.
Quando isso ocorrer, a obrigatoriedade será explicitamente indicada na seção "Chaves complementares relevantes" do respectivo dataset.

3️⃣ Sobre o parâmetro `Datasets`

O parâmetro Datasets informa quais conjuntos de dados devem ser retornados pela API. Ele funciona como o “o que quero receber dessa entidade”.

Exemplos de datasets comuns:

basic_data
kyc
processes

A lista de datasets completa fica na documentação específica de cada API, no menu lateral.

O Datasets também permite:

seleção de campos
uso de modificadores
composição de múltiplos datasets na mesma chamada

Essas funcionalidades são detalhadas na página “Personalizar retorno”.

4️⃣ Sobre o parâmetro `Limit`

O Limit controla o máximo de entidades retornadas quando a consulta não for suficientemente específica.

Use quando:

não houver chave principal
a consulta puder gerar múltiplas ocorrências
você quiser limitar a quantidade de entidades retornadas

Exemplo

{
  "Datasets": "basic_data",
  "q": "name{Joao da Silva}, birthdate{10-02-1995}, dateformat{dd-mm-yyyy}",
  "Limit": 5
}

5️⃣Resumo prático

q → quem estou procurando
Datasets → o que quero receber
Limit → quantidade máxima de entidades que desejo receber, quando a chave de busca não for 1:1

Esses três parâmetros formam a base de todas as consultas da Plataforma de Dados.

Próximos passos

Agora que você entende todos os parâmetros de consulta, siga para:

Personalizar retorno – selecionando campos, aplicando filtros e ordenações
Recursos adicionais – uso de dochash, tags e funcionalidades complementares

✨ A partir daqui, você já domina a lógica das requisições. Agora é só explorar como refinar e enriquecer seus retornos.