API › Routing › Isócronas # Isócronas Área alcançável a partir de um ponto em X minutos de carro, a pé ou de bicicleta — para catchment area, escolha de ponto comercial, cobertura de last-mile e definição de territórios. Categoria Routing Cobertura Nacional Perfis car · foot · bike Sentido SAINDO · INDO Nesta página Aplicações Conceito Sentido: SAINDO vs INDO Entradas Exemplos Atributos retornados Detalhes técnicos Limitações Para que serve ## Aplicações A isócrona delimita a região do espaço que pode ser alcançada, a partir de um ponto de origem (ou até um ponto de destino), dentro de um limite de tempo de deslocamento — considerando a malha viária real. É a base geoespacial para decisões de localização, cobertura e territorialização. #### Catchment area de PDV Dimensione a área de captura de clientes de uma loja, agência ou franquia a partir do tempo real de deslocamento em vez de raio euclidiano. #### Cobertura de last-mile Avalie a cobertura de entregas em N minutos a partir de um hub logístico e identifique lacunas de atendimento para novos centros de distribuição. #### Território comercial Construa territórios equilibrados para forças de vendas ou representantes com base no tempo de deslocamento entre pontos. #### Análise de acessibilidade Meça em quantos minutos a população de uma região consegue chegar a hospitais, escolas ou serviços essenciais de carro, a pé ou de bicicleta. Entendendo o dado ## Conceito Uma **isócrona** é um polígono que delimita todos os pontos do território que podem ser alcançados, a partir (ou até) uma coordenada de referência, dentro de um determinado limite de tempo de deslocamento. Diferente de um raio simples (círculo euclidiano), ela é calculada sobre a **malha viária real** — respeitando ruas, velocidades permitidas, sentidos e topologia da rede. O parâmetro `sentido` define a semântica da isócrona: **SAINDO** significa _“a partir deste ponto, aonde eu consigo chegar em X segundos?”_ — o polígono é construído seguindo o sentido natural das vias. Já **INDO** significa _“de onde eu consigo chegar até este ponto em X segundos?”_ — o polígono é construído seguindo as vias no sentido reverso. Em malhas com muitas vias de mão única, os dois polígonos podem ser bastante diferentes. ### Isócrona × isodistância × buffer: por que a diferença importa Três recortes reais a partir do mesmo ponto — **Av. Paulista, 2064, São Paulo/SP** (`-23.558308, -46.659477`), perfil `car`: ![Isócrona de 5 minutos de carro a partir da Av. Paulista](https://prismadata.io/imagens/isocronas/carro_5min.png) **Isócrona por tempo — 5 min de carro** malha viária + velocidades reais ![Isodistância de 500 metros percorridos pela malha viária a partir da Av. Paulista](https://prismadata.io/imagens/isocronas/carro_500m.png) **Isodistância — 500 m pela malha** distância acumulada via ruas ![Buffer circular geodésico de 500 metros de raio a partir da Av. Paulista](https://prismadata.io/imagens/isocronas/buffer_500m.png) **Buffer 500 m** círculo euclidiano, ignora ruas A **isócrona por tempo** reflete a velocidade real do perfil (o polígono cresce mais rápido nas vias principais). A **isodistância** mede o alcance rodoviário absoluto — bom quando o critério de negócio é "raio de X metros de rua". O **buffer euclidiano** é uma referência geométrica pura (círculo perfeito) — normalmente superestima a área acessível na prática. Interpretação ## Sentido: SAINDO vs INDO Escolha o sentido conforme a pergunta de negócio que você quer responder. Ambos os sentidos utilizam o mesmo `time_limit` em segundos e o mesmo `profile` de deslocamento. → **sentido: SAINDO** Área alcançável partindo do ponto. Use para dimensionar a catchment area de uma loja, o alcance de uma frota a partir de um hub, ou o território de um vendedor com base em seu domicílio. ← **sentido: INDO** Área de onde é possível chegar até o ponto. Use para responder “de quais bairros meus clientes conseguem chegar até esta agência em 20 minutos?” ou para modelagem de acessibilidade a serviços. Request ## Parâmetros de Entrada `lat` float Latitude WGS84 do ponto central da isócrona. **Obrigatório.** `lng` float Longitude WGS84 do ponto central da isócrona. **Obrigatório.** `time_limit` integer · segundos Limite de tempo de deslocamento em **segundos**. Faixa: `60` (1 min) a `7200` (2 h). Mutuamente exclusivo com `distance_limit`. Sem nenhum dos dois: aplica `600`s por retrocompatibilidade. `distance_limit` integer · metros **Modo isodistância** : limite de distância **acumulada pela malha viária** (não euclidiana). Faixa: `100` a `50000` m. Mutuamente exclusivo com `time_limit` — enviar os dois retorna `422`. `profile` enum Perfil de roteamento: `car`, `foot` ou `bike`. Padrão: `car`. `sentido` enum Direção do cálculo: `SAINDO` (a partir do ponto) ou `INDO` (até o ponto). Padrão: `SAINDO`. `condicao_transito` enum Ajuste de velocidade por condição de trânsito. Aplica multiplicador ao `time_limit` antes do cálculo. Só efetivo em `profile=car` no modo tempo; ignorado nos demais casos. Valores: `livre` (fator 1.00), `normal` (0.70, **padrão**), `pico_moderado` (0.50), `pico_pesado` (0.30). #### Breaking change (2026-08-31): default de `condicao_transito` O padrão mudou de `livre` (comportamento antigo, área otimista) para `normal` (0.70 do tempo bruto). Clientes que precisam do comportamento anterior devem passar `condicao_transito=livre` explicitamente. A mudança evita que quem não passa parâmetro receba áreas superestimadas sem saber. Na prática ## Exemplos Dois cenários a partir do mesmo endereço — **Av. das Nações Unidas, 12995, São Paulo/SP** (`-23.605541, -46.696247`) — ilustram como o sentido (`SAINDO`/`INDO`) e o perfil de deslocamento mudam completamente o polígono retornado. O campo `geometria` retorna sempre um **POLYGON em formato WKT** pronto para ser consumido por PostGIS, GeoPandas ou bibliotecas de visualização. Isócrona de 15 min de carro (SAINDO) — Av. das Nações Unidas, 12995, São Paulo/SP lat=-23.605541, lng=-46.696247 · profile=car · time_limit=900 · sentido=SAINDO · condicao_transito=normal ![Isócrona de 15 minutos saindo de carro da Av. das Nações Unidas 12995 em São Paulo, cobrindo Jardim Europa, Vila Olímpia, Brooklin Novo e adjacências](https://prismadata.io/imagens/isocronas/nacoes_unidas_15min_carro_saindo.png) { "geometria": "POLYGON ((-46.7392 -23.5719, ..., -46.7392 -23.5719))", "modo": "tempo", "limite_tempo_s": 900, "limite_distancia_m": null, "perfil": "car", "sentido": "SAINDO", "area_m2": 26814000, "condicao_transito": "normal", "fator_temporal": 0.7, "limite_tempo_s_efetivo": 630, "municipio_ibge": 3550308 } Polígono da região alcançável **em até 15 minutos saindo** do ponto, dirigindo em `condicao_transito=normal` (fator 0,7 — o motor recebe 630 s efetivos, refletindo a velocidade típica de um dia útil fora de pico). O contorno é fortemente alongado ao longo das Marginais Pinheiros e Av. das Nações Unidas, mostrando como o eixo viário determina o alcance real — muito diferente de um círculo geodésico. **Barreiras físicas aparecem no polígono.** O _Rio Pinheiros_ corta a área em duas: o lado oposto (Butantã, Morumbi) é praticamente inacessível dentro do orçamento de 15 min porque só pode ser atravessado pelas poucas pontes existentes — cada travessia consome minutos do budget. Um buffer euclidiano de mesma "distância equivalente" cruzaria o rio como se não existisse. Este é um caso clássico de por que isócrona ≠ raio. Isócrona de 30 min a pé (INDO) — mesmo endereço lat=-23.605541, lng=-46.696247 · profile=foot · time_limit=1800 · sentido=INDO ![Isócrona de 30 minutos indo a pé até a Av. das Nações Unidas 12995, cobrindo Vila Olímpia, Brooklin e adjacências](https://prismadata.io/imagens/isocronas/nacoes_unidas_30min_pe_indo.png) { "geometria": "POLYGON ((-46.7018 -23.5891, ..., -46.7018 -23.5891))", "modo": "tempo", "limite_tempo_s": 1800, "limite_distancia_m": null, "perfil": "foot", "sentido": "INDO", "area_m2": 3812400, "condicao_transito": "normal", "fator_temporal": 1.0, "limite_tempo_s_efetivo": 1800, "municipio_ibge": 3550308 } Polígono da região **de onde** pedestres conseguem chegar até o ponto em até 30 minutos caminhando. Como `condicao_transito` não afeta perfil `foot`, o `fator_temporal` volta para 1,0. A área (~3,8 km²) é ordens de grandeza menor que a de carro pelo mesmo ponto — útil para dimensionar catchment pedestre de um ponto comercial ou estação. Note o formato "espinha" ao longo do corredor Berrini, que reflete a hierarquia viária pedonal. **A barreira do Rio Pinheiros é ainda mais evidente a pé.** Como pedestres têm menos opções de travessia (basicamente as passarelas), o polígono fica quase todo confinado ao lado leste do rio — bairros como Morumbi e Chácara Santo Antônio, mesmo geograficamente próximos, ficam _funcionalmente inacessíveis_ no orçamento de 30 min. Um raio euclidiano de 2 km, por outro lado, cobriria os dois lados sem distinção — e superestimaria a captação pedestre real do endereço. Response ## Atributos Retornados O retorno do endpoint `/routing/isochrone` segue o schema `IsochroneResponseSchema` e contém a geometria do polígono da isócrona e os metadados do cálculo. Geometria geometria Polígono da isócrona em formato **WKT (POLYGON)** , no sistema de referência WGS84 (EPSG:4326). Pode ser lido diretamente por PostGIS (`ST_GeomFromText`) ou por bibliotecas como Shapely e GeoPandas. Métricas do cálculo modo Qual dimensão foi limitada no cálculo: `tempo` (isócrona clássica) ou `distancia` (isodistância). O campo não-usado (`limite_tempo_s` ou `limite_distancia_m`) vem `null`. area_m2 Área do polígono em **metros quadrados**. Útil como métrica direta de acessibilidade do ponto. limite_tempo_s Limite de tempo em **segundos** ecoado do request (parâmetro `time_limit`). `null` quando `modo=distancia`. limite_distancia_m Limite de distância em **metros** ecoado do request (parâmetro `distance_limit`). `null` quando `modo=tempo`. perfil Perfil de deslocamento utilizado: `car`, `foot` ou `bike`. sentido Sentido do movimento utilizado: `SAINDO` (a partir do ponto) ou `INDO` (até o ponto). Ajuste por trânsito (observabilidade) condicao_transito Nível de trânsito pedido no request. Valores: `livre`, `normal`, `pico_moderado`, `pico_pesado`. fator_temporal Multiplicador aplicado ao `time_limit`: `1.00` (livre), `0.70` (normal), `0.50` (pico moderado), `0.30` (pico pesado). limite_tempo_s_efetivo Tempo efetivamente enviado ao motor de roteamento após o ajuste (`time_limit × fator_temporal`, mínimo 60 s). `null` em modo distância. municipio_ibge Código IBGE do município identificado no ponto central (7 dígitos). Apenas observabilidade — _não_ afeta o fator temporal. `null` quando o ponto está fora de município mapeado. Referência ## Detalhes Técnicos #### Fontes * Motor de roteamento próprio da PrismaData * Malha viária brasileira derivada de fontes públicas abertas #### Metodologia Expansão de caminho mais curto (variante de Dijkstra) a partir do ponto central, ponderada por _tempo_ (modo `time_limit`) ou por _distância acumulada pela malha_ (modo `distance_limit`). O envelope alcançado é convertido em polígono via concave hull sobre os nós atingidos, respeitando sentidos e restrições do perfil. Em `profile=car` no modo tempo, `condicao_transito` aplica um multiplicador ao `time_limit` antes do corte — para compensar que velocidades nominais superestimam a área alcançável em pico real. #### Frequência de Atualização A malha viária é atualizada periodicamente a partir de snapshots públicos. #### Cobertura Todo o território nacional coberto pela malha viária pública. Perfis suportados: `car`, `foot` e `bike`. Atenção ## Limitações #### Considere ao utilizar * **Não considera tráfego em tempo real:** o cálculo usa velocidades típicas de referência por tipo de via, sem dados de congestionamento. Em horários de pico, a área real alcançável pode ser menor. * **Tempo máximo de 7200 segundos (2 horas):** valores fora da faixa `[60, 7200]` retornam erro de validação (HTTP 422). * **Precisão limitada pela malha viária:** em regiões com cobertura viária incompleta ou desatualizada na base pública, o polígono pode subestimar ou superestimar a área realmente alcançável. * **Ponto de origem fora da malha:** coordenadas em áreas sem cobertura de rede viária (mar aberto, matas fechadas) podem não retornar isócrona ou retornar polígono degenerado. ## Pronto para testar? Experimente a API de Isócronas no playground interativo com suas próprias coordenadas, perfil e tempo. [ Abrir playground ](<../api-playground/rotas-isocronas/>)