Communitygithub.com

Seleção de Locais e Análise de Canibalização

Constrói workflows no CARTO para selecionar locais ideais para novas instalações e analisar o risco de canibalização entre áreas de captação sobrepostas.

O que é Seleção de Locais e Análise de Canibalização?

Esta skill do CARTO permite que agentes de IA projetem e executem workflows de análise espacial para tomada de decisão de localização. Ela cobre três padrões principais: Seleção de Locais (Pattern A), que pontua e classifica candidatos com base em critérios espaciais e demográficos; Análise de Canibalização (Pattern B), que quantifica a sobreposição entre áreas de captação de lojas existentes e propostas; e Áreas Gêmeas/Locais Semelhantes (Pattern C), que usa um modelo PCA para encontrar áreas que se assemelham a locais de alto desempenho. A skill é acionada por palavras-chave como 'seleção de local', 'canibalização', 'nova loja' ou 'localização ideal'. Ela suporta plataformas como BigQuery, Snowflake e Postgres, e depende de ferramentas como `native.h3polyfill`, `native.isolines`, `native.buildtwinareasmodel` e `native.commercialhotspots` para construir pipelines de dados robustos. É essencial carregar as skills auxiliares `carto-create-workflow` e `carto-trade-area-analysis` para garantir o funcionamento correto.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CartoDB/agent-skills/tree/HEAD/skills/carto-site-selection

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Análise de Seleção de Locais e Canibalização

Constrói Workflows CARTO que identificam locais ideais para novas instalações (lojas, estações, escritórios) combinando critérios espaciais e que quantificam o risco de canibalização a partir de áreas de captação sobrepostas. Também cobre a descoberta de áreas gêmeas e locais semelhantes.

Pré-requisitos: Carregue carto-create-workflow para o processo de desenvolvimento, estrutura JSON e validação. Ele cobre ambos os caminhos de acesso — as ferramentas de workflow do servidor MCP (create_workflow, validate_workflow, run_workflow) quando anexado, e a CLI carto workflows caso contrário. Sinais de roteamento: carto-basics/references/access-paths.md. Carregue carto-trade-area-analysis se o workflow envolver isócronas, buffers ou enriquecimento de áreas de captação — ele cobre o pipeline de áreas de captação em detalhes.


Árvore de Decisão

Intenção do UsuárioPadrão
"Onde devo abrir uma nova loja?"Seleção de Locais (pontuação + classificação)
"Uma nova loja prejudicará as existentes?"Análise de Canibalização
"Encontrar locais semelhantes aos meus melhores desempenhos"Áreas Gêmeas / Locais Semelhantes

Instruções

Padrão A: Seleção de Locais (Pontuação + Classificação)

Locais existentes + Área alvo -> Indexação espacial -> Enriquecer com dados demográficos/POIs -> Pontuar/Classificar -> Filtrar melhores candidatos -> Salvar

Passo 1: Carregar Dados

Carregue dois conjuntos de dados com native.gettablebyname:

  • Locais existentes (lojas/instalações atuais)
  • Área alvo (ex.: limite da cidade, polígonos de distrito ou uma grade cobrindo a área de estudo)

Separando candidatos da rede existente quando ambos estão em uma única tabela. Se a fonte do usuário for uma única tabela onde os "candidatos" são definidos por um limite numérico (ex.: receita ≥ X, tamanho ≥ Y), use um native.where com esse predicado e conecte sua saída match ao pipeline de candidatos e sua saída unmatch ao pipeline da rede existente. Dois fluxos a partir de um nó — muito mais limpo do que orderby + limit + customsql NOT IN, e evita um customsql completamente. O limite aproxima "top N"; se o usuário disser explicitamente "exatamente top 25", orderby + limit ainda é a escolha certa, mas pague o custo extra do nó conscientemente.

Sucesso: Ambas as tabelas carregadas com colunas de geometria e identificadores únicos.

Passo 2: Construir Grade de Candidatos

Preencha a área alvo com células H3 ou Quadbin usando native.h3polyfill ou native.quadbinpolyfill. Cada célula é um micro-local candidato.

Sucesso: Uma grade contígua de células cobrindo a área de estudo.

Passo 3: Enriquecer Candidatos

Anexe sinais de demanda a cada célula — população, renda, tráfego de pedestres, densidade de POIs — usando native.h3enrich, native.joinv2 ou o Data Observatory.

Se os candidatos forem polígonos contínuos (áreas de captação / distritos) em vez de uma grade, a escolha entre native.enrichpolygons e native.spatialjoin + native.groupby é importante — veja carto-spatial-enrichment Passo 4 para a troca (dependência de AT vs contagem de nós vs predicado / controle de junção).

Sucesso: Cada célula da grade possui colunas numéricas representando fatores de demanda/adequação.

Passo 4: Filtrar por Proximidade a Locais Existentes

Use native.h3distance para calcular a distância em saltos de cada célula candidata ao local existente mais próximo. Filtre células que estão muito próximas (risco de canibalização) ou muito distantes (custo logístico). A saída é a contagem de saltos, não a distância métrica — converta usando o comprimento da borda da resolução (veja Armadilhas).

Semântica de distância — meça a canibalização a partir do polígono da área de captação, não do ponto candidato. Quando os candidatos são pontos com uma área de captação gerada (isolinha / buffer — veja carto-trade-area-analysis), compute native.distance do polígono da área de captação do candidato até os pontos concorrentes existentes, não do próprio ponto candidato. Motivo: ST_DISTANCE(polygon, point) = 0 sempre que o concorrente está dentro da área de captação — exatamente o sinal de canibalização que você deseja. A distância ponto a ponto apenas informa "quão longe está o concorrente mais próximo" e esconde a sobreposição. Escolha o radius consistente com o tamanho da área de captação (ex.: ~5 km para uma área de captação de 10 minutos a pé); raios grandes diluem o sinal. Este padrão polígono-para-ponto é o meio-termo entre o filtro de salto H3 do Padrão A e a análise completa de sobreposição de grade do Padrão B — use-o sempre que o candidato já tiver uma geometria de área de captação contínua.

Sucesso: As células candidatas estão dentro de uma faixa de distância sensível dos locais existentes, e qualquer sinal de canibalização é medido a partir do polígono da área de captação quando existir um.

Passo 5: Pontuar e Classificar

Use o padrão de pontuação de trade-area-analysis:

  1. Normalize cada variável para [0,1] com native.normalize
  2. Pontuação composta via native.selectexpression com pesos definidos pelo usuário
  3. Classifique com native.orderby (descendente) + native.limit (top N)

Sucesso: Uma lista classificada de células candidatas com pontuações compostas e variáveis contribuintes.

Passo 6: Salvar

Use native.saveastable. A coluna H3/Quadbin é diretamente visualizável no CARTO Builder.

Sucesso: Workflow validado pronto para upload.


Padrão B: Análise de Canibalização

Locais existentes + Propostos -> Áreas de captação (isolinha/buffer) -> Preencher grade -> Intersecionar/Juntar -> Medir sobreposição -> Salvar

Passo 1: Carregar Dados

Carregue locais existentes e locais propostos (ou uma única tabela com uma coluna de sinalização distinguindo-os). Se ambos os conjuntos estiverem em uma única tabela e a divisão for definida por um limite numérico (ex.: receita ≥ X), veja a divisão match/unmatch do native.where no Passo 1 do Padrão A — ela produz ambos os fluxos a partir de um nó e evita customsql.

Sucesso: Ambos os conjuntos carregados com geometria e identificadores únicos.

Passo 2: Gerar Áreas de Captação

Crie áreas de captação em torno de locais existentes e propostos usando native.isolines (realista) ou native.buffer (simples). Use os mesmos parâmetros para ambos os conjuntos para garantir comparabilidade.

Sucesso: Cada local tem um polígono de área de captação com parâmetros consistentes.

Passo 3: Preencher Grade com Índice Espacial

Converta todos os polígonos de área de captação em células H3 ou Quadbin com native.h3polyfill. Preserve o identificador do local e um sinalizador is_proposed.

Sucesso: Uma linha por célula por local, com ID do local e sinalizador de tipo.

Passo 4: Encontrar Sobreposição

Use native.joinv2 (junção interna na coluna de índice espacial) entre as células dos locais existentes e as células dos locais propostos. O resultado contém células compartilhadas por pelo menos um local existente e um proposto.

Sucesso: A saída contém apenas células que estão em ambas as áreas de captação, existente e proposta.

Passo 5: Medir Impacto

Use native.groupby para agregar a sobreposição:

  • Por local existente: contagem de células sobrepostas / total de células na área de captação desse local = porcentagem de sobreposição
  • Enriqueça células sobrepostas com população ou receita para quantificar a demanda compartilhada

Use native.selectexpression para calcular a razão de sobreposição.

Sucesso: Cada local existente tem uma métrica de sobreposição mostrando quanto de sua área de captação é compartilhada com locais propostos.

Passo 6: Salvar

Use native.saveastable.

Sucesso: Workflow validado com métricas de canibalização por local.


Padrão C: Áreas Gêmeas / Locais Semelhantes

Locais de melhor desempenho -> Áreas de captação -> Enriquecer -> Construir modelo de similaridade -> Pontuar todas as áreas candidatas -> Classificar -> Salvar

Passo 1: Identificar Locais de Referência

Carregue o conjunto de dados completo de locais. Filtre para os melhores desempenhos (ex.: quartil superior por receita) usando native.wheresimplified ou native.orderby + native.limit.

Sucesso: Um subconjunto de locais de alto desempenho isolado como conjunto de referência.

Passo 2: Gerar e Enriquecer Áreas de Captação

Crie áreas de captação de isócrona ou buffer em torno dos locais de referência. Preencha com H3/Quadbin. Enriqueça com dados demográficos, POIs e quaisquer variáveis relevantes.

Sucesso: Cada local de referência tem um perfil demográfico rico.

Passo 3: Construir Modelo de Áreas Gêmeas

Use native.buildtwinareasmodel (BUILD_TWIN_AREAS_MODEL) para criar um modelo de similaridade baseado em PCA a partir dos locais de referência enriquecidos.

  • Entrada: locais de referência enriquecidos com colunas de características numéricas
  • O modelo captura a "assinatura" multivariada de locais de sucesso

Sucesso: Um artefato de modelo que codifica o perfil demográfico dos melhores desempenhos.

Passo 4: Encontrar Locais Semelhantes

Use native.findsimilarlocations (FIND_SIMILAR_LOCATIONS) para pontuar todas as áreas candidatas contra o modelo de áreas gêmeas.

  • Entrada: áreas candidatas enriquecidas com as mesmas variáveis usadas para construir o modelo
  • Saída: pontuação de similaridade por candidato

Sucesso: Cada área candidata tem uma pontuação de similaridade relativa ao conjunto de referência.

Passo 5: Classificar e Salvar

Classifique pela pontuação de similaridade em ordem decrescente. Salve os melhores candidatos.

Sucesso: Uma lista classificada de áreas mais semelhantes aos locais de melhor desempenho.


Variante de Hotspots Comerciais

Para seleção de locais orientada pela demanda (ex.: "onde a demanda não atendida é mais alta?"), use native.commercialhotspots:

  1. Construa uma grade H3 sobre a área de estudo
  2. Enriqueça com a variável de demanda alvo (ex.: população de 15 a 34 anos)
  3. Execute native.commercialhotspots com variablecolumns e weights
  4. Filtre os resultados por significância (p_value < 0.05)
  5. Opcionalmente, filtre por native.h3distance de locais existentes para focar em áreas mal atendidas

Nota: variablecolumns usa sintaxe de lista no estilo Python (['col1', 'col2']), e weights é separado por vírgulas — veja as armadilhas de trade-area-analysis para detalhes.


Armadilhas

  • Maiúsculas/minúsculas do provedor e dialeto SQL. Esta skill usa nomes de colunas em minúsculas (h3, is_proposed, population, etc.) — convenção do BigQuery / Databricks / Postgres / Redshift. No Snowflake, identificadores não entre aspas aparecem em MAIÚSCULAS — refira-se a eles como H3, IS_PROPOSED, POPULATION. Veja carto-create-workflow/references/providers/<provider>.md para regras de maiúsculas/minúsculas e equivalentes de dialeto SQL.
  • native.commercialhotspots requer o módulo Retail do Analytics Toolbox. Valide com --connection para confirmar a disponibilidade.
  • Áreas Gêmeas e Locais Semelhantes usam PCA internamente — os resultados são sensíveis à seleção e escalonamento de variáveis. Inclua apenas variáveis relevantes e não redundantes. Normalize as entradas se as escalas diferirem muito.
  • A sobreposição de canibalização depende fortemente da definição da área de captação (raio do buffer, tempo da isolinha). Pequenas mudanças nos parâmetros podem inverter os resultados. Documente os parâmetros escolhidos e a justificativa.
  • native.h3distance retorna contagem de saltos, não distância física. Multiplique pelo comprimento aproximado da borda da célula para a resolução para obter uma distância métrica aproximada (ex.: res 8 ~ 460m, res 9 ~ 174m por salto).
  • Ao comparar regiões de diferentes tamanhos, normalize os dados demográficos para valores per capita ou por área para evitar viés de tamanho (ex.: densidade populacional em vez de população total).
  • O "melhor" local depende inteiramente dos critérios e pesos escolhidos — não há uma resposta objetivamente correta. Sempre documente as suposições e permita que o usuário ajuste os pesos.
  • Para o modelo de áreas gêmeas, use o mesmo conjunto de variáveis de enriquecimento tanto para os locais de referência quanto para os candidatos. Variáveis incompatíveis farão o modelo falhar ou produzir pontuações sem sentido.

Modelos de Referência

Tutoriais da Academia

TutorialProvedorURL
Pizza Hut Honolulu — seleção de locais com hotspots comerciaisBigQueryLink
Pizza Hut Honolulu — seleção de locais com hotspots comerciaisSnowflakeLink
Canibalização de lojas — quantificando o impacto de novas lojasBigQueryLink
Canibalização Starbucks — análise de sobreposição de grade H3BigQueryLink
Canibalização de lojas — sobreposição de grade QuadkeySnowflakeLink
Encontrar áreas gêmeas de lojas de melhor desempenhoBigQueryLink
Encontrar locais semelhantes com base em áreas de captaçãoBigQueryLink
Seleção de locais para estações de carregamento EVWorkflowsLink

Variações Comuns

VariaçãoComo
Expansão de varejoIsócronas -> enriquecer com demografia + densidade de concorrentes -> pontuação composta -> top N
Planejamento de território de franquiaPadrão de canibalização para garantir áreas de captação não sobrepostas antes de conceder territórios
Carregamento EV / serviços públicosGrade baseada em demanda (população, tráfego) + filtro de distância de existentes -> classificar células mal atendidas
Place-based / OOH publicitárioBuffers -> enriquecimento de audiência -> normalizar + ponderar -> top N (veja trade-area-analysis)
Otimização de agências bancáriasÁreas gêmeas das melhores agências -> encontrar áreas semelhantes mal atendidas -> propor novas agências
Concorrente ...

[truncado para tradução]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas