API › Localização › Entorno # PrismaData Entorno Estudo da área de influência de um ponto em uma única consulta: domicílios, renda dos moradores por faixa e concorrência por atividade, com a área definida por tempo de deslocamento, raio ou polígono, para expansão, avaliação de ponto comercial e inteligência de mercado. Categoria Localização · Mercado Área de estudo Isócrona, raio ou polígono Âncora Coordenada, endereço ou CNPJ Fontes IBGE · Receita Federal · PrismaData Lote Até 100 estudos por chamada Nesta página Aplicações Conceito Consultas disponíveis Entradas Camadas opcionais Exemplos Atributos retornados Detalhes técnicos Limitações Para que serve ## Aplicações O Entorno responde, em uma chamada, às perguntas que antecedem a decisão sobre um ponto: quantos domicílios há na área que o ponto atende, qual é a renda de quem mora ali, quantos concorrentes já atuam na mesma atividade e quão perto eles estão. A área pode ser o alcance real de deslocamento (a pé, de carro ou de bicicleta), um raio fixo ou um polígono que você já usa, como um território de vendas. #### Expansão e Escolha de Ponto Compare candidatos a nova loja pelo tamanho do público residente, pela renda da área e pela densidade de concorrentes da mesma atividade, com o mesmo critério de área para todos. #### Avaliação da Rede Atual Rode o estudo para cada unidade da rede, em lote, e identifique lojas com público pequeno, concorrência crescente ou baixa participação estimada na demanda da região. #### Inteligência de Mercado Meça a saturação de um segmento em uma região: concorrentes por mil domicílios, redes contra independentes, idade mediana das empresas e taxa de fechamento nos últimos 24 meses. #### Crédito e Risco do Ponto Comercial Use o estudo a partir do CNPJ do estabelecimento para qualificar o ponto de um tomador PJ: público ao redor, concorrência direta e proximidade de aglomerações comerciais e de favelas. Entendendo o dado ## Conceito Todo estudo tem uma **âncora** e uma **área**. A âncora é o ponto estudado, informado como coordenada, endereço ou CNPJ; endereço e CNPJ são convertidos em coordenada antes do cálculo. A área é o recorte territorial: uma [isócrona]() (o que se alcança em X minutos ou X metros pela malha viária), um raio fixo em torno da âncora ou um polígono WKT enviado por você. Sobre essa área, a API calcula sempre três blocos: **habitação** (endereços e domicílios residenciais por tipo, a partir do cadastro de endereços do Censo 2022), **renda pessoal** (moradores por faixa de renda mensal) e **concorrência** (empresas ativas na área, filtradas pela atividade que interessa). Outras camadas, como favelas, aglomerações comerciais, concorrentes mais próximos e partição de demanda, entram quando pedidas. Se um bloco não puder ser calculado, o estudo não falha: o bloco vem nulo (ou com `_disponivel=false` no formato plano) e o motivo aparece em `execucao`. A resposta também informa a versão de cada base usada, o que torna o estudo reproduzível e auditável. Produto ## Consultas disponíveis As três rotas recebem o mesmo corpo JSON e calculam o mesmo estudo; mudam o formato da resposta e a quantidade de estudos por chamada. Os caminhos completos e os esquemas estão na [documentação técnica](). `/location/entorno/agregado` POST **Formato plano:** uma linha por estudo, com cada bloco achatado em campos escalares. Pronto para planilha, banco de dados ou modelo. `/location/entorno/agregado/raw` POST **Formato aninhado:** o mesmo estudo organizado por bloco, com as listas completas (concorrência por CNAE e por porte, concorrentes mais próximos, aglomerações da área) e, se pedido, o polígono da área. `/location/entorno/agregado/batch` POST **Lote:** até 100 estudos por chamada, no formato plano. Cada estudo leva uma chave sua e volta indexado por ela; a falha de um item não derruba o lote. Request ## Parâmetros de Entrada Envie exatamente uma forma de área: `ancora` \+ `isocrona`, `ancora` \+ `buffer` ou `wkt`. Combinações diferentes retornam `422` com a explicação. ### Âncora e área `ancora` object Uma única forma: `latitude` \+ `longitude`, `endereco` (texto livre, até 200 caracteres) ou `cnpj` (14 dígitos, com ou sem máscara). Com CNPJ, a coordenada é a do endereço cadastrado do estabelecimento. `isocrona` object `profile` (`car`, `foot` ou `bike`; padrão `car`), `minutos` (1 a 120) _ou_ `metros` pela malha viária (100 a 50.000) e `sentido` (`SAINDO`, padrão, ou `INDO`). `buffer` object `raio_m`: raio em linha reta em torno da âncora, de 100 m a 20 km. `wkt` string Polígono ou multipolígono em WKT (WGS84). Nesse modo não há âncora, e as camadas que dependem dela (concorrentes mais próximos, partição de demanda) não se aplicam. `qualidade_minima_geocoder` enum Com âncora por endereço, a qualidade mínima aceita na geocodificação: `MUITO_ALTA`, `ALTA`, `MEDIA` (padrão), `BAIXA` ou `MUITO_BAIXA`. Abaixo do limite, o estudo é recusado em vez de rodar sobre um ponto impreciso. ### Concorrência e renda `filtros_cnpj` object Define quem conta como concorrente: `cnae_prefix` (prefixos de CNAE, como `"4771"` para farmácias) ou `segmento` (agrupamentos de CNAEs por ramo, mutuamente exclusivo com `cnae_prefix`), `porte`, `matriz_filial`, `natureza_juridica`, `capital_social_min`, `data_abertura_desde`, `opcao_mei` e `incluir_cnae_secundario`. Por padrão contam só empresas com situação `ATIVA`. `faixas_renda_mensal` object Faixas próprias de renda pessoal mensal, em reais, no formato `{"rotulo": [min, max]}` (`null` = sem limite). Sem esse campo, valem as faixas A (acima de R$ 20 mil), B (R$ 10 mil a 20 mil), C (R$ 5 mil a 10 mil), D (R$ 2 mil a 5 mil) e E (até R$ 2 mil). `incluir_indicadores` boolean Acrescenta à concorrência indicadores de maturidade, formalização e mortalidade: idade mediana, fração aberta há até 2 anos, fração MEI, capital social mediano e empresas baixadas nos últimos 24 meses. `incluir_dados_pdv` / `excluir_mesma_raiz` boolean Só com âncora por CNPJ. O primeiro devolve os dados do próprio estabelecimento (atividade, porte, situação, idade). O segundo, ligado por padrão, tira da contagem de concorrentes todas as unidades da mesma empresa (mesma raiz de CNPJ); desligado, tira só o CNPJ da âncora. ### Formato da resposta `detalhe_concorrencia` enum No formato aninhado: `resumo` (padrão; por CNAE, por porte e redes × independentes) ou `cruzado` (acrescenta o cruzamento CNAE × porte × matriz/filial). `incluir_geometria` / `descricoes` boolean No formato aninhado: devolve o polígono da área estudada em WKT e a descrição de cada CNAE da concorrência. Composição ## Camadas opcionais Ligadas em `flags`, acrescentam blocos ao mesmo estudo, sem uma segunda chamada. 1 **distancia_concorrentes** Os concorrentes mais próximos da âncora (`top_n` de 1 a 20; padrão 5), com distância em linha reta (`geodesica`) ou pela malha viária (`rota`, informando o `profile`). Os concorrentes seguem os mesmos `filtros_cnpj` do estudo. 2 **huff** Partição da demanda pelo modelo de Huff: estima a participação esperada do ponto na demanda dos domicílios da área, considerando a atratividade e a distância de cada concorrente. Classifica os domicílios em cativos, disputados e perdidos. Exige âncora por CNPJ e filtro de atividade. O parâmetro `lambda` ajusta o peso da distância ao tipo de compra: `conveniencia`, `padrao` ou `destino`. 3 **aci** [Aglomerações comerciais]() que cruzam a área: quantas são, quantos pontos de venda reúnem, que fração da área ocupam e se a âncora está dentro de alguma. 4 **favelas** [Favelas e comunidades urbanas]() na área: quantidade de favelas e complexos, domicílios dentro delas, fração da área ocupada, se a âncora está dentro de uma e a distância até a mais próxima. Na prática ## Exemplos Dois estudos reais de farmácias (CNAE `4771`) na região da Savassi, em Belo Horizonte/MG, no formato plano. Os nomes dos campos aparecem sem o prefixo `prismadata__entorno__` e com parte dos campos omitida. 10 minutos a pé a partir da Praça da Liberdade POST /v1/location/entorno/agregado · ancora: -19.9319, -43.9380 · isocrona: foot, 10 min · cnae_prefix: 4771 · distancia_concorrentes: top 3 · incluir_indicadores { "modalidade": "isocrona", "isocrona_profile": "foot", "isocrona_minutos": 10, "habitacao_total_enderecos": 705, "habitacao_total_domicilios_residenciais": 4197, "habitacao_total_apartamentos": 4141, "habitacao_total_casas": 45, "renda_pessoal_total_pessoas": 7880, "renda_pessoal_faixa_a_frac": 0.144924, "renda_pessoal_faixa_b_frac": 0.271193, "renda_pessoal_faixa_c_frac": 0.22868, "renda_pessoal_faixa_d_frac": 0.133756, "renda_pessoal_faixa_e_frac": 0.221447, "concorrencia_total": 8, "concorrencia_redes": 6, "concorrencia_independentes": 2, "concorrencia_por_1000_domicilios": 1.9061, "concorrencia_idade_mediana_anos": 5.52, "concorrencia_frac_ate_2_anos": 0.25, "concorrencia_taxa_mortalidade_24m": 0.2, "concorrente_mais_proximo_distancia_m": 139.3, "concorrentes_topn_distancia_media_m": 254.3 } Em 10 minutos de caminhada há **4.197 domicílios** , quase todos apartamentos, e cerca de **7.900 moradores** ; 42% deles estão nas faixas A e B (renda pessoal acima de R$ 10 mil). Oito farmácias ativas atuam na área, seis delas de redes, o que dá **1,9 farmácia por mil domicílios**. A mais próxima está a 139 m do ponto. Um quarto das farmácias abriu há até 2 anos, e a taxa de fechamento nos últimos 24 meses é de 20%: um mercado com entrada e saída frequentes. Raio de 1 km em torno de uma farmácia de rede, com camadas POST /v1/location/entorno/agregado · ancora: CNPJ da filial · buffer: 1.000 m · cnae_prefix: 4771 · flags: huff, aci, favelas { "ancora_origem": "cnpj", "ancora_cnpj_qualidade_geo": "MUITO_ALTA", "modalidade": "buffer_circular", "buffer_raio_m": 1000, "habitacao_total_domicilios_residenciais": 25874, "renda_pessoal_total_pessoas": 49408, "concorrencia_total": 58, "concorrencia_por_1000_domicilios": 2.2416, "huff_disponivel": true, "huff_share_esperado": 0.338385, "huff_share_min": 0.317272, "huff_share_max": 0.354777, "huff_dom_cativos": 9906, "huff_dom_disputados": 6018, "huff_dom_perdidos": 9912, "huff_lambda_preset": "padrao", "aci_disponivel": true, "aci_n": 22, "aci_total_pdvs": 6028, "ancora_em_aci": false, "favelas_disponivel": true, "favelas_n": 0, "ancora_em_favela": false, "favela_mais_proxima_distancia_m_ao_poligono": 1775.5 } Com a âncora no CNPJ, a coordenada vem do endereço cadastrado (geocodificação **MUITO_ALTA**), e as outras unidades da mesma rede saem da contagem: restam **58 farmácias concorrentes** em 1 km. O modelo de Huff estima que o ponto capta cerca de **34% da demanda** dos domicílios da área, entre 32% e 35% conforme a calibragem: 9.906 domicílios são cativos, 6.018 estão em disputa e 9.912 tendem a outro concorrente. A área cruza 22 aglomerações comerciais, com mais de 6 mil pontos de venda, e não contém favelas; a mais próxima fica a 1,8 km. Consultas reais de novembro/2026. Os números mudam a cada atualização das bases. Response ## Atributos Retornados Campos do formato plano, exibidos sem o prefixo `prismadata__entorno__`. O formato aninhado traz o mesmo conteúdo agrupado por bloco (`habitacao`, `renda_pessoal`, `concorrencia`, `huff`, `aci`, `favelas`), mais as listas detalhadas. Âncora e área ancora_latitude / ancora_longitude Coordenada usada no estudo, já resolvida quando a âncora é endereço ou CNPJ. ancora_origem Como a âncora foi informada: `coordenada`, `endereco` ou `cnpj`. ancora_cnpj_qualidade_geo Com âncora por CNPJ, a qualidade da geocodificação do endereço do estabelecimento. modalidade Forma da área: `isocrona`, `buffer_circular` ou polígono enviado em WKT. isocrona_* / buffer_raio_m Parâmetros da área ecoados do pedido: perfil, minutos ou metros e sentido da isócrona, ou o raio do buffer. pdv_* Com `incluir_dados_pdv`: atividade (CNAE), porte, matriz ou filial, situação cadastral e idade do estabelecimento da âncora. Habitação habitacao_total_enderecos Endereços cadastrados na área. habitacao_total_domicilios_residenciais Domicílios residenciais na área, a medida de tamanho do público residente. habitacao_total_apartamentos / habitacao_total_casas Domicílios residenciais por tipo de moradia. Renda pessoal renda_pessoal_total_pessoas Moradores da área considerados na distribuição de renda. renda_pessoal_total_sem_renda Moradores sem renda pessoal. renda_pessoal_faixa_{rotulo}_pessoas / _frac Moradores estimados em cada faixa de renda pessoal mensal e a fração que representam. O rótulo é o da faixa padrão (`a` a `e`) ou o que você definiu em `faixas_renda_mensal`. renda_pessoal_salario_minimo_referencia Salário mínimo de referência, em reais, para quem quiser expressar as faixas em salários mínimos. Concorrência concorrencia_total Empresas na área que passam nos `filtros_cnpj` (por padrão, só as ativas). concorrencia_redes / _independentes / _sedes Divisão das empresas: **redes** são filiais; **independentes** são matrizes de micro ou pequeno porte; **sedes** são matrizes de porte maior. concorrencia_por_1000_domicilios Densidade de concorrentes em relação ao público residente. concorrencia_indice_vs_municipio Densidade da área comparada à do município. Pode vir `null`; nesse caso, o motivo aparece nos avisos de execução. concorrencia_idade_mediana_anos / _frac_ate_2_anos Com `incluir_indicadores`: idade mediana das empresas e fração aberta há até 2 anos. concorrencia_frac_mei / _capital_social_mediano Com `incluir_indicadores`: fração de MEIs e capital social mediano, em reais. concorrencia_baixadas_24m / _taxa_mortalidade_24m Com `incluir_indicadores`: empresas da atividade baixadas na área nos últimos 24 meses e a taxa de fechamento correspondente. concorrente_mais_proximo_distancia_m / concorrentes_topn_distancia_media_m Com `distancia_concorrentes`: distância ao concorrente mais próximo e distância média dos N mais próximos. A lista com CNPJ, razão social, porte e coordenada de cada um vem no formato aninhado. Camadas opcionais huff_share_esperado Participação esperada do ponto na demanda dos domicílios da área, de 0 a 1. huff_share_min / huff_share_max Menor e maior participação do ponto quando o peso da distância na escolha do consumidor varia dentro da faixa calibrada. Mostram quanto a participação esperada depende dessa calibragem: uma faixa estreita indica estimativa robusta. Sempre vale `huff_share_min ≤ huff_share_esperado ≤ huff_share_max`. huff_dom_cativos / _disputados / _perdidos Domicílios em que o ponto é a escolha dominante, em que divide a preferência com concorrentes e em que outro concorrente domina; os campos `huff_frac_*` trazem as mesmas frações. No formato aninhado, a participação estimada de cada concorrente. aci_n / aci_total_pdvs / aci_frac_area Aglomerações comerciais que cruzam a área, total de pontos de venda nelas e fração da área ocupada. No formato aninhado, a lista com nome, tipo, porte e faixa de renda de cada aglomeração. ancora_em_aci / ancora_aci_id Se a âncora está dentro de uma aglomeração comercial e qual. favelas_n / favelas_n_complexos / favelas_frac_area Favelas e complexos que cruzam a área e a fração da área ocupada por eles. favelas_domicilios_residenciais Domicílios residenciais da área que ficam dentro de favelas. ancora_em_favela / favela_mais_proxima_distancia_m_ao_poligono Se a âncora está dentro de uma favela e a distância, em metros, até a borda da mais próxima. {bloco}_disponivel `true` quando o bloco foi calculado; `false` quando não foi pedido ou não pôde ser calculado. Execução e auditoria execucao (avisos, blocos_ausentes) Avisos sobre o cálculo e, para cada bloco ausente, o motivo (por exemplo, camada não pedida) e como incluí-lo. cobertura_cnpjs_sem_geo_nacional_frac Fração das empresas do país sem localização, que por isso não entram na contagem de concorrentes. versao_* Versão de cada base usada no estudo (CNPJ, geocodificação, renda, rotas) e do contrato da resposta, para reproduzir o estudo. Referência ## Detalhes Técnicos #### Fontes * IBGE: cadastro de endereços do Censo 2022 e favelas e comunidades urbanas * Receita Federal: cadastro de CNPJ (dados abertos) * PrismaData: geocodificação, renda, isócronas e aglomerações comerciais #### Metodologia A área de estudo é construída a partir da âncora (isócrona pela malha viária, círculo geodésico ou o polígono enviado). Domicílios, moradores por faixa de renda e empresas são contados dentro dela. A concorrência usa as empresas com localização, filtradas pela atividade e pelos critérios pedidos. A partição de demanda segue o modelo de Huff, que pondera a atratividade de cada concorrente pela distância até os domicílios da área. #### Frequência de Atualização Cada bloco acompanha a atualização da sua base: o cadastro de CNPJ é mensal, e as bases do Censo mudam a cada nova divulgação do IBGE. A versão de cada base vem na própria resposta. #### Cobertura Todo o território nacional. As isócronas cobrem a malha viária pública. Cerca de 8% dos CNPJs ativos estão sem localização e não entram na contagem de concorrentes. Atenção ## Limitações #### Considere ao utilizar * Os números descrevem a população **residente**. Público flutuante (quem trabalha, estuda ou passa pela região) não entra, o que subestima a demanda em centros comerciais e corporativos. * A concorrência conta empresas pelo endereço cadastrado na Receita Federal e pela atividade declarada (CNAE). Empresas com endereço desatualizado, sem localização ou com CNAE que não reflete a operação real ficam fora da contagem ou entram onde não deveriam. * A renda é uma estimativa agregada da área, não a renda de uma pessoa. Use como perfil do público, não para decisão sobre um indivíduo. * Com âncora por endereço, um endereço mal geocodificado desloca toda a área de estudo. Ajuste `qualidade_minima_geocoder` ao seu uso e confira a coordenada devolvida. * A isócrona usa velocidades de referência da malha viária, sem trânsito em tempo real. Se o cálculo de isócrona estiver indisponível, a API devolve `503`; nesse caso, use `buffer` ou envie o polígono em `wkt`. * O raio do buffer vai de 100 m a 20 km, e a isócrona, até 120 minutos ou 50 km pela malha. Para análises regionais maiores, envie o polígono. * A partição de demanda é um modelo: o resultado depende da atividade filtrada, do `lambda` escolhido e do número de alternativas consideradas. Use para comparar pontos entre si, não como previsão de vendas. ## Pronto para testar? Explore o playground do Entorno: posicione a âncora no mapa, escolha a área e veja o estudo completo em tempo real. [ Abrir Playground ](<../api-playground/entorno/>) [ Solicitar acesso ]()