Parâmetros de Consulta

Visão Geral

Todos os datasets da Plataforma de Dados necessitam que sejam informados um ou mais campos de entrada, que são inseridos no parâmetro q do objeto de requisição. Parâmetros de chamada como doc, zipcode e licenseplate são utilizados para a identificação da entidade a ser consultada, pois possuem uma relação 1:1. Outros parâmetros, como referencedate, radius e mothername, são utilizados para configurar o retorno dos datasets ou inserir informações para suporte aos processo internos de obtenção dos dados.

Os parâmetros dos datasets da Plataforma de Dados são divididos em quatro categorias:

• 🛑 OBRIGATÓRIOS: o campo ou um parâmetro equivalente deve sempre ser informado, caso contrário a chamada irá falhar. Em alguns datasets, há campos que podem são obrigatórios apenas em certas condições, como em Unidades Federativas específicas.
• ⚠️ SEMI-OBRIGATÓRIOS: são campos necessários no processo de consulta, mas a BigData Corp tentará obter os dados internamente se não forem informados na chamada.
•  ℹ️  OPCIONAIS : os campos podem ser passados ou não, porém as chances de resultados satisfatórios aumentam quando estes são utilizados na consulta.
• 🔑 CHAVES ALTERNATIVAS: são campos equivalentes à chave obrigatória de consulta no dataset, podendo ser utilizados de forma isolada para consultar a entidade desejada.

Os parâmetros de entrada devem ser concatenados por vírgula. O exemplo abaixo mostra uma consulta por nome e data de nascimento.

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

As chaves podem ser combinadas de acordo com a necessidade do usuário. Por padrão, caso mais de um "candidato" possível seja encontrado associado às informações de entrada, a API retornará uma mensagem de erro. Para sempre receber um candidato, ou receber uma quantidade específica de candidatos, deve ser usado o parâmetro Limit, mostrado na URL exemplo abaixo:

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

CUIDADO: O preço da consulta é contabilizado por entidade retornada para cada dataset consultado. Se, em uma pesquisa com chaves alternativas, forem encontradas e retornadas 2 entidades diferentes, o custo será o valor dos datasets selecionados multiplicado por 2.

Chaves Principais por Entidade

Cada uma das entidades de consulta das APIs apresenta uma chave principal padrão. Abaixo está um tabela com a descrição de cada uma dessas chaves e sua(s) entidade(s).

Chaves Alternativas de Consulta

Para o caso de consultas por pessoas ou empresas, entendemos que você nem sempre terá o documento para utilizar como chave. Por isso, a BigData Corp desenvolveu uma ferramenta que possibilita a obtenção do documento de identificação a partir de campos alternativos. A tabela a seguir apresenta os campos alternativos aceitos para substituir o parâmetro doc. Pelo menos um deles deve estar preenchido dentro do parâmetro q para que uma busca seja bem sucedida.

Nota: Essa ferramenta é usada apenas nas APIs de Pessoas, Empresas e OnDemand. As APIs de Produtos e Endereços também possibilitam o uso de chaves alternativas de consulta, como descrito em seus respectivos datasets.

Parâmetros Opcionais

Além dos parâmetros descritos anteriormente, as APIs da Plataforma de Dados permitem a utilização de diversos outros parâmetros para se chegar a um resultado final mais assertivo, que estão descritos abaixo.