# Renda

> A API de renda fornece estimativas da renda na região próxima de determinada coordenada geográfica. Veja que esta informação de renda não se refere à uma pessoa específica, mas sim a uma região em que ela mora ou se encontra em determinado momento.

**Base**: `https://api.prismadata.io/v1`

**Autenticação**: header `X-Apikey` (ou query `api_key`). Detalhes em [Autenticação](autenticacao.md).

**Formato de resposta**: JSON plano com campos `prismadata__<serviço>__<campo>`; em lote, dicionário indexado pelas chaves enviadas. Detalhes em [Formato de Resposta](guias/formato-de-resposta.md).

## Endpoints

### `GET /location/personal_income_static`

Endpoint para se consultar a renda estimada do setor censitário que contém a coordenada geográfica (latitude/longitude). Retorna a posição da renda da região em percentis nos contextos nacional, estadual (UF) e municipal, além da faixa salarial típica em múltiplos de salário mínimo. Caso a coordenada não esteja dentro de nenhum setor censitário com dados de renda disponíveis (por exemplo, fora do território brasileiro), valores nulos são retornados.

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/location/personal_income_static?lat=-19.932378368680315&lng=-43.9351245162891" \
  -H "X-Apikey: SEU_TOKEN"
```

**Parâmetros**:

| Nome | Local | Tipo | Obrigatório | Descrição |
|------|-------|------|-------------|-----------|
| `lat` | query | number | sim | Latitude do ponto a ser estudado. |
| `lng` | query | number | sim | Longitude do ponto a ser estudado. |

**Response 200** (`application/json`):

> Successful Response

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__personal_income_static__faixa_sm_min` | number \| null | sim | Limite inferior da faixa salarial em múltiplos de salário mínimo (SM). Exemplo: 5.0 significa 5 SM |
| `prismadata__personal_income_static__faixa_sm_max` | number \| null | sim | Limite superior da faixa salarial em múltiplos de salário mínimo (SM). Null quando a faixa é aberta (acima de 10 SM) |
| `prismadata__personal_income_static__percentil_br` | integer \| null | sim | Dado o contexto do brasileiro, em qual percentil esta renda se encontra. Valores maiores indicam que a região do ponto apresenta pessoas com renda elevada dentro do contexto brasileiro. |
| `prismadata__personal_income_static__percentil_mun` | integer \| null | sim | O percentil da renda da região da coordenada geográfica em relação ao município brasileiro em que o ponto se encontra. Valores elevados indicam uma região com renda elevada naquele município. |
| `prismadata__personal_income_static__percentil_uf` | integer \| null | sim | O percentil da renda da região da coordenada geográfica em relação à unidade da federação brasileira (Estado) em que o ponto se encontra. Novamente, valores maiores significam regiões de renda elevada dentro do contexto da UF. |

**Outros códigos**: 401, 403, 422, 429

---

### `GET /location/personal_income_pdf`

Endpoint para se consultar a renda na coordenada geográfica. As informações retornadas são gerados por um modelo que é uma função de densidade de probabilidade (Probability Density Function - PDF). Opcionalmente, pode-se definir um perfil detalhado do indivíduo que se deseja estimar a renda.

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/location/personal_income_pdf?lat=-19.932378368680315&lng=-43.9351245162891" \
  -H "X-Apikey: SEU_TOKEN"
# Params opcionais: gender=M, age=50, is_responsible=false, income_compared=10000, date_income=2025-01-25
```

**Parâmetros**:

| Nome | Local | Tipo | Obrigatório | Descrição |
|------|-------|------|-------------|-----------|
| `lat` | query | number | sim | Latitude do ponto de origem. |
| `lng` | query | number | sim | Longitude do ponto de origem |
| `gender` | query | Genero \| null | não | Gênero da pessoa que se deseja analisar a renda. [M, F, male, female] |
| `age` | query | number \| null | não | Idade da pessoa que se deseja analisar a renda |
| `is_responsible` | query | AtributosBooleanos \| null | não | Indicador se as pessoas que se deseja analisar a renda são responsáveis pelo domicílio |
| `income_compared` | query | number \| null | não | Renda a ser comparada com a renda da região. |
| `date_income` | query | string(date) \| null | não | Data a ser consultada a renda no formato YYYY-MM-DD. Somente datas após 2022-01-01 são válidas. |

**Response 200** (`application/json`):

> Successful Response

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__personal_income_pdf__qtde_pessoas` | number \| null | sim | Estimativa da quantidade de pessoas que se encontram na vizinhança do ponto. |
| `prismadata__personal_income_pdf__qtde_pessoas_sem_renda` | number \| null | sim | Estimativa da quantidade de pessoas da região que não possuem uma renda mensal. |
| `prismadata__personal_income_pdf__renda_comparada_cdf` | number \| null | não | Quando uma renda a ser comparada é informada, indica quantas pessoas (em termos percentuais) da região possuem uma renda inferior à renda pesquisada. Só está presente na resposta quando o parâmetro `income_compared` é informado na requisição. |
| `prismadata__personal_income_pdf__renda_comparada_pdf` | number \| null | não | Quando uma renda a ser comparada é informada, indica o quão provável é alguém possuir exatamente aquela renda na região. Só está presente na resposta quando o parâmetro `income_compared` é informado na requisição. |
| `prismadata__personal_income_pdf__renda_comparada_z_score` | number \| null | não | Quando uma renda a ser comparada é informada, indica o desvio desta renda com a renda característica da região. Valores próximos à zero indicam uma proximidade das rendas e valores com magnitude elevada indicam valores díspares entre si. Valores de z-score positivos, indicam uma renda comparada acima da renda característica da região e valores negativos indicam valores abaixo da renda característica da região. Só está presente na resposta quando o parâmetro `income_compared` é informado na requisição. |
| `prismadata__personal_income_pdf__renda_media_pessoas` | number \| null | sim | Indica a renda média entre as pessoas da região considerando-se todas as pessoas, inclusive as pessoas sem renda, que tendem a reduzir esse valor. |
| `prismadata__personal_income_pdf__renda_pessoas_com_renda_desvio_padrao` | number \| null | sim | Desvio padrão da PDF da renda da região, indicando o quão diversa é a renda dos indivíduos na região. Valores menores indicam uma renda mais homogênea e valores maiores uma renda mais variada. Este valor é obtido considerando somente as pessoas que apresentam renda mensal na região. |
| `prismadata__personal_income_pdf__renda_pessoas_com_renda_maxima` | number \| null | sim | Estimativa do valor de renda máxima mensal estimada na região. Este valor é obtido considerando somente as pessoas que apresentam renda mensal na região. |
| `prismadata__personal_income_pdf__renda_pessoas_com_renda_media` | number \| null | sim | Estimativa do valor de renda média mensal estimada na região. Este valor é obtido considerando somente as pessoas que apresentam renda mensal na região. |
| `prismadata__personal_income_pdf__renda_pessoas_com_renda_mediana` | number \| null | sim | Estimativa do valor que divide as pessoas entre o 50% mais rico e o 50% mais pobre da região. Este valor é obtido considerando somente as pessoas que apresentam renda mensal na região. |
| `prismadata__personal_income_pdf__renda_pessoas_com_renda_minima` | number \| null | sim | Estimativa do valor de renda mínima mensal da região. Este valor é obtido considerando somente as pessoas que apresentam renda mensal na região. |
| `prismadata__personal_income_pdf__renda_pessoas_com_renda_primeiro_quartil` | number \| null | sim | Estimativa do valor de renda mensal que divide o 25% mais pobre e o 75% mais rico da região. Este valor é obtido considerando somente as pessoas que apresentam renda mensal na região. |
| `prismadata__personal_income_pdf__renda_pessoas_com_renda_qtde` | number \| null | sim | Quantidade de pessoas que apresentam renda mensal. |
| `prismadata__personal_income_pdf__renda_pessoas_com_renda_terceiro_quartil` | number \| null | sim | Estimativa do valor de renda mensal que divide o 75% mais pobre e o 25% mais rico da região. Este valor é obtido considerando somente as pessoas que apresentam renda mensal na região. |
| `prismadata__personal_income_pdf__renda_total` | number \| null | sim | Estimativa da renda nominal total, que representa a soma da renda mensal de todos os indivíduos da região. |
| `prismadata__personal_income_pdf__renda_total_m2` | number \| null | sim | Estimativa da renda nominal total, que representa a soma da renda mensal de todos os indivíduos da região dividida pela área da região que se considera na modelagem. Valores maiores indicam não só uma região rica, mas também uma região verticalizada, isto é, com alta concentração espacial de renda. |

**Outros códigos**: 401, 403, 422, 429

---

### `POST /location/batch/personal_income_static`

Endpoint batch para consulta de renda estática. Recebe múltiplos pontos e retorna percentis e faixa salarial para cada um.

**Exemplo curl**:

```bash
curl -X POST "https://api.prismadata.io/v1/location/batch/personal_income_static" \
  -H "X-Apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "p1": [
           -19.9323,
           -43.9351
         ]
       }'
```

**Request body** (`application/json`):

Dicionário `{string: array[number]}`.
Dict de pontos para batch static: {"id": [lat, lng]}.

**Response 200** (`application/json`):

> Successful Response

Dicionário `{string: object}`.
Resultados estáticos por ponto. Chave = ID do ponto enviado na requisição.

**Outros códigos**: 401, 403, 422, 429

---

### `POST /location/batch/personal_income_pdf`

Endpoint batch para consulta de renda via PDF (Probability Density Function). Recebe múltiplos pontos, cada um com seus próprios parâmetros demográficos.

**Exemplo curl**:

```bash
curl -X POST "https://api.prismadata.io/v1/location/batch/personal_income_pdf" \
  -H "X-Apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "p1": {
           "lat": -19.9323,
           "lng": -43.9351,
           "date_income": "2025-01-25",
           "gender": "M",
           "age": 40,
           "is_responsible": false,
           "income_compared": 5000
         }
       }'
```

**Request body** (`application/json`):

Dicionário `{string: object \| array[number]}`.
Dict de pontos para batch PDF. Aceita ambos os formatos: - {"p1": [lat, lng]} (aggregator / sem params demográficos) - {"p1": {"lat": ..., "lng": ..., "gender": "M"}} (com params)

**Response 200** (`application/json`):

> Successful Response

Dicionário `{string: object}`.
Resultados PDF por ponto. Chave = ID do ponto enviado na requisição.

**Outros códigos**: 401, 403, 422, 429

---

## Recursos relacionados

- Documentação Redoc interativa: https://prismadata.io/redoc.html#tag/Renda
- OpenAPI só deste produto (JSON): https://prismadata.io/llm/openapi/renda.json
- OpenAPI completo: https://prismadata.io/openapi.yaml
- Índice geral: https://prismadata.io/llms.txt