# PrismaData Entorno > Dossie agregado do microterritorio: habitacao (CNEFE), renda por faixa, concorrencia CNPJ, composicao favelas/ACI. MVP progressivo — blocos nao plugados vem como `null` no OUTPUT. **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____`; em lote, dicionário indexado pelas chaves enviadas. Detalhes em [Formato de Resposta](guias/formato-de-resposta.md). ## Endpoints ### `POST /location/entorno/agregado/raw` Dossie agregado do microterritorio (aninhado). **Exemplo curl**: ```bash curl -X POST "https://api.prismadata.io/v1/location/entorno/agregado/raw" \ -H "X-Apikey: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "ancora": { "latitude": -19.9323, "longitude": -43.9351, "endereco": "string", "cnpj": "11222333000144" }, "qualidade_minima_geocoder": "MEDIA", "isocrona": { "profile": "car", "minutos": 0, "metros": 0, "sentido": "SAINDO" }, "buffer": { "raio_m": 500 }, "wkt": "string", "filtros_cnpj": { "cnae_prefix": [ "string" ], "situacao_cadastral": [ "string" ], "qualidade_geo_min": "string", "matriz_filial": [ "string" ], "porte": [ "string" ], "capital_social_min": 0, "natureza_juridica": [ "string" ], "data_abertura_desde": "string", "opcao_mei": false, "incluir_cnae_secundario": false, "segmento": "string" }, "faixas_renda_mensal": { "p1": [ 0 ] }, "flags": { "favelas": false, "aci": false, "distancia_concorrentes": {}, "huff": false }, "incluir_geometria": false, "detalhe_concorrencia": "resumo", "incluir_indicadores": false, "incluir_dados_pdv": false, "excluir_mesma_raiz": true, "granularidade": "agregado", "descricoes": false }' ``` **Request body** (`application/json`): | Campo | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | `ancora` | object \| null | não | | | `qualidade_minima_geocoder` | string | não | Limite minimo de qualidade do geocode quando `ancora.endereco` for usado. Ordem: MUITO_ALTA > ALTA > MEDIA > BAIXA > MUITO_BAIXA. Default MEDIA. Rejeita CENTROIDE_MUNICIPIO/NAO_GEOCODIFICADO. | | `isocrona` | object \| null | não | | | `buffer` | object \| null | não | | | `wkt` | string \| null | não | | | `filtros_cnpj` | object | não | Filtros aplicados aos CNPJs contados no bloco de concorrencia. `porte` aceita canônico (MICRO/PEQUENA/DEMAIS/NAO_INFORMADO) e aliases tributários (ME→MICRO, EPP→PEQUENA) — normalização interna. | | `faixas_renda_mensal` | object | não | Faixas nao-sobrepostas de renda pessoal mensal. Cada valor eh `[min, max]`; null = infinito. Rotulos usados como sufixo em colunas do flat (sanitizados: lower, sem acento, `[a-z0-9]`). | | `flags` | object | não | Flags de camadas de composicao opt-in (v0.7+). Blocos core (`habitacao`, `renda_pessoal`, `concorrencia`) foram consolidados como sempre-ativos no contrato v1 e nao aparecem em flags — nao ha caso de uso para desliga-los. Camadas de composicao (`favelas`, `aci`) continuam opt-in — cada flag ativa dispara um evento de cobranca adicional. v0.8/C adiciona `distancia_concorrentes` (opt-in via sub-objeto ou None) para retornar top_n CNPJs mais proximos da ancora. v1.15 adiciona `huff` (opt-in via `true` ou sub-objeto). `true` é normalizado para `HuffParams()` com defaults; `false` vira `None`. | | `incluir_geometria` | boolean | não | So tem efeito no /raw. Quando true, `OUTPUT.geometria_estudo.wkt` carrega o WKT da area de estudo alem dos metadados de origem/parametros. No flat, ignorado com aviso em execucao. | | `detalhe_concorrencia` | string | não | So tem efeito no /raw. `resumo` (default): por_cnae, por_porte, redes_vs_independentes. `cruzado`: adiciona agregado fino (cnae x porte x matriz_filial). No flat, ignorado com aviso. | | `incluir_indicadores` | boolean | não | v0.8/A3+A4. Anexa `concorrencia.indicadores` com maturidade (idade_mediana_anos, frac_ate_2_anos), formalizacao (frac_mei, capital_social_mediano) e mortalidade (baixadas_24m, taxa_mortalidade_24m). Custo: 2 queries agregadas extras. | | `incluir_dados_pdv` | boolean | não | v0.9/B1. So valido com `ancora.cnpj` (com outra origem -> 422). Anexa `ancora.pdv` com atributos do estabelecimento (razao_social, cnae, porte, situacao, ...) + colunas flat pdv_*. Cobra evento CNPJ no billing. | | `excluir_mesma_raiz` | boolean | não | v0.9/C. So aplicavel com `ancora.cnpj`. Quando true (default), a autoexclusao expande para todas as filiais da mesma empresa (mesmos 8 primeiros digitos). false -> exclui apenas o CNPJ exato do ancora. | | `granularidade` | string | não | | | `descricoes` | boolean | não | So tem efeito no /raw. Quando true, anexa `concorrencia.descricoes: {cnae_codigo: descricao}`. Custo extra de latencia (~10-50ms). | **Response 200** (`application/json`): > Successful Response Tipo: `object`. **Outros códigos**: 422, 429 --- ### `POST /location/entorno/agregado` Dossiê em formato plano (canônico). Estudo de entorno com o mesmo conteúdo do `/agregado/raw`, com os blocos achatados em campos escalares (uma linha por requisição). Blocos ausentes viram `_disponivel=false`. **Exemplo curl**: ```bash curl -X POST "https://api.prismadata.io/v1/location/entorno/agregado" \ -H "X-Apikey: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "ancora": { "latitude": -19.9323, "longitude": -43.9351, "endereco": "string", "cnpj": "11222333000144" }, "qualidade_minima_geocoder": "MEDIA", "isocrona": { "profile": "car", "minutos": 0, "metros": 0, "sentido": "SAINDO" }, "buffer": { "raio_m": 500 }, "wkt": "string", "filtros_cnpj": { "cnae_prefix": [ "string" ], "situacao_cadastral": [ "string" ], "qualidade_geo_min": "string", "matriz_filial": [ "string" ], "porte": [ "string" ], "capital_social_min": 0, "natureza_juridica": [ "string" ], "data_abertura_desde": "string", "opcao_mei": false, "incluir_cnae_secundario": false, "segmento": "string" }, "faixas_renda_mensal": { "p1": [ 0 ] }, "flags": { "favelas": false, "aci": false, "distancia_concorrentes": {}, "huff": false }, "incluir_geometria": false, "detalhe_concorrencia": "resumo", "incluir_indicadores": false, "incluir_dados_pdv": false, "excluir_mesma_raiz": true, "granularidade": "agregado", "descricoes": false }' ``` **Request body** (`application/json`): | Campo | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | `ancora` | object \| null | não | | | `qualidade_minima_geocoder` | string | não | Limite minimo de qualidade do geocode quando `ancora.endereco` for usado. Ordem: MUITO_ALTA > ALTA > MEDIA > BAIXA > MUITO_BAIXA. Default MEDIA. Rejeita CENTROIDE_MUNICIPIO/NAO_GEOCODIFICADO. | | `isocrona` | object \| null | não | | | `buffer` | object \| null | não | | | `wkt` | string \| null | não | | | `filtros_cnpj` | object | não | Filtros aplicados aos CNPJs contados no bloco de concorrencia. `porte` aceita canônico (MICRO/PEQUENA/DEMAIS/NAO_INFORMADO) e aliases tributários (ME→MICRO, EPP→PEQUENA) — normalização interna. | | `faixas_renda_mensal` | object | não | Faixas nao-sobrepostas de renda pessoal mensal. Cada valor eh `[min, max]`; null = infinito. Rotulos usados como sufixo em colunas do flat (sanitizados: lower, sem acento, `[a-z0-9]`). | | `flags` | object | não | Flags de camadas de composicao opt-in (v0.7+). Blocos core (`habitacao`, `renda_pessoal`, `concorrencia`) foram consolidados como sempre-ativos no contrato v1 e nao aparecem em flags — nao ha caso de uso para desliga-los. Camadas de composicao (`favelas`, `aci`) continuam opt-in — cada flag ativa dispara um evento de cobranca adicional. v0.8/C adiciona `distancia_concorrentes` (opt-in via sub-objeto ou None) para retornar top_n CNPJs mais proximos da ancora. v1.15 adiciona `huff` (opt-in via `true` ou sub-objeto). `true` é normalizado para `HuffParams()` com defaults; `false` vira `None`. | | `incluir_geometria` | boolean | não | So tem efeito no /raw. Quando true, `OUTPUT.geometria_estudo.wkt` carrega o WKT da area de estudo alem dos metadados de origem/parametros. No flat, ignorado com aviso em execucao. | | `detalhe_concorrencia` | string | não | So tem efeito no /raw. `resumo` (default): por_cnae, por_porte, redes_vs_independentes. `cruzado`: adiciona agregado fino (cnae x porte x matriz_filial). No flat, ignorado com aviso. | | `incluir_indicadores` | boolean | não | v0.8/A3+A4. Anexa `concorrencia.indicadores` com maturidade (idade_mediana_anos, frac_ate_2_anos), formalizacao (frac_mei, capital_social_mediano) e mortalidade (baixadas_24m, taxa_mortalidade_24m). Custo: 2 queries agregadas extras. | | `incluir_dados_pdv` | boolean | não | v0.9/B1. So valido com `ancora.cnpj` (com outra origem -> 422). Anexa `ancora.pdv` com atributos do estabelecimento (razao_social, cnae, porte, situacao, ...) + colunas flat pdv_*. Cobra evento CNPJ no billing. | | `excluir_mesma_raiz` | boolean | não | v0.9/C. So aplicavel com `ancora.cnpj`. Quando true (default), a autoexclusao expande para todas as filiais da mesma empresa (mesmos 8 primeiros digitos). false -> exclui apenas o CNPJ exato do ancora. | | `granularidade` | string | não | | | `descricoes` | boolean | não | So tem efeito no /raw. Quando true, anexa `concorrencia.descricoes: {cnae_codigo: descricao}`. Custo extra de latencia (~10-50ms). | **Response 200** (`application/json`): > Successful Response Tipo: `object`. **Outros códigos**: 422, 429 --- ### `POST /location/entorno/agregado/batch` Lote de estudos em formato plano (até 100 por requisição). Entrada: `{id_cliente: }`. Saída: objeto indexado pelas mesmas chaves enviadas; cada item traz `SUCESSO`, `EXCEPTION`, `OUTPUT` (dossiê plano) e `STATS`. A falha de um item não derruba o lote: o item volta com `SUCESSO=false` e o motivo em `EXCEPTION`. **Exemplo curl**: ```bash curl -X POST "https://api.prismadata.io/v1/location/entorno/agregado/batch" \ -H "X-Apikey: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ``` **Request body** (`application/json`): Tipo: `object`. **Response 200** (`application/json`): > Successful Response Tipo: `object`. **Outros códigos**: 422, 429 --- ## Recursos relacionados - Documentação Redoc interativa: https://prismadata.io/redoc.html#tag/PrismaData-Entorno - OpenAPI só deste produto (JSON): https://prismadata.io/llm/openapi/prismadata-entorno.json - OpenAPI completo: https://prismadata.io/openapi.yaml - Índice geral: https://prismadata.io/llms.txt