Principais conceitos

Para gerar um isócrono, forneça à API uma origem, um modo de viagem (como carro, moto, bicicleta ou a pé) e um limite de tempo. Também é possível ajustar as preferências de trajeto e a aparência visual do polígono resultante.

Meios de transporte

Use o parâmetro obrigatório travelMode (travel_mode) para especificar o meio de transporte:

• DRIVE: calcula a acessibilidade de um carro de passeio em vias transitáveis usando limites de velocidade, hierarquia de vias, penalidades de conversão e, opcionalmente, condições de trânsito em tempo real.
• TWO_WHEELER: calcula a acessibilidade de um veículo motorizado de duas rodas (como uma motocicleta ou scooter) usando regras de acesso rodoviário específicas do modo e velocidades modeladas mais baixas do que DRIVE em estradas de alta velocidade. Como resultado, um isócrono de TWO_WHEELER normalmente cobre uma área maior que BICYCLE, mas menor que DRIVE ao longo de rodovias de alta velocidade.
• BICYCLE: calcula a acessibilidade de um ciclista em ruas, ciclofaixas e caminhos compartilhados, com velocidades ajustadas para o tipo de via e a inclinação, excluindo rodovias e vias expressas de acesso controlado.
• WALK: calcula a acessibilidade de um pedestre em calçadas, caminhos, trilhas e ruas acessíveis a pedestres, com velocidade de caminhada ajustada para inclinação. A travessia a pé ignora as restrições de veículos de mão única.

Horizonte de tempo

A principal restrição que você fornece ao serviço é o travelDuration (travel_duration). Isso define o horizonte de tempo para o cálculo.

• Duração mínima e máxima: a duração precisa ser de pelo menos "1s" (1 segundo). Zero ("0s"), durações negativas e durações de menos de 1 segundo (como "0.5s") retornam um erro 400 INVALID_ARGUMENT. A API oferece suporte a um tempo de viagem máximo de 3.600 segundos (1 hora) para os modos DRIVE e TWO_WHEELER e 7.200 segundos (2 horas) para os modos WALK e BICYCLE.
• Mínimo de polígonos: como a API converte os trechos de via alcançados em células de grade espacial, durações muito curtas retornam um pequeno polígono que cobre as células de grade ao redor da origem ajustada.
• Desempenho: o tempo de cálculo varia de acordo com a duração solicitada e o meio de transporte selecionado. Uma isócrona de uma hora de carro abrange uma área geográfica e uma rede de estradas significativamente maiores do que uma isócrona de uma hora a pé, o que resulta em maior latência para a solicitação de carro.
• Formatação: como a API usa google.protobuf.Duration, a duração precisa ser formatada como uma string que termina em "s" (por exemplo, "3600s"), em vez de um número inteiro.

Pontos de origem e ajuste de vias

É possível especificar o ponto de partida da isócrona de duas maneiras:

• Coordenadas (location): um par de latitude e longitude. Forneça latitude (em [-90, 90]) e longitude (em [-180, 180]). Se você omitir um deles, a API vai tratar como 0.0, o que coloca o ponto no equador ou no meridiano de Greenwich. Se você omitir ambos ({}) ou enviar (0, 0), a API vai retornar um erro 400 INVALID_ARGUMENT.
• IDs de lugar (place): um identificador exclusivo para um lugar específico no Google Maps. Quando você fornece um ID de lugar, o serviço resolve o lugar para a coordenada do centroide e ajusta esse ponto à via mais próxima. Use o formato de nome de recurso que começa com places/ (por exemplo, places/ChIJIQBpAG2ahYAR_6128GcTUEo). Um ID de lugar simples sem o prefixo places/ também é aceito. Para mais informações sobre IDs de lugar, consulte IDs de lugar.

Independentemente do método de entrada, a API não calcula os tempos de viagem do ponto físico exato se ele não estiver em uma via, como dentro de um parque ou de um edifício. Para lidar com essa situação, o serviço usa o ajuste à via. O ajuste de estradas tem os seguintes recursos:

• Ajuste inteligente: o serviço tenta ajustar o ponto de origem ao segmento de via transitável mais próximo.
• Reconhecimento de modo: a lógica de fixação considera seu travel_mode. Se você solicitar DRIVE ou TWO_WHEELER, a API vai ignorar os caminhos exclusivos para pedestres e procurar a rua mais próxima para veículos. Se você solicitar WALK, a API vai priorizar caminhos e calçadas para pedestres.
• Casos de falha: se a API não encontrar um trecho de via adequado dentro da distância máxima de ajuste do ponto de origem (cerca de 200 metros ou menos para WALK e BICYCLE), ela vai retornar um erro 404 NOT_FOUND. Características geográficas grandes (como parques, campi ou mirantes) podem ter um centroide de ID de lugar mais distante do que a distância de ajuste da via mais próxima que pode ser usada pelo modo de viagem. Nesses casos, transmita as coordenadas location explícitas de uma entrada de via.

Direção da viagem (entrada x saída)

É possível calcular a acessibilidade de entrada e saída usando o parâmetro travelDirection (travel_direction):

• FROM (saída): calcula a área acessível a partir do ponto de origem dentro do limite de tempo especificado. Isso é adequado para casos de uso como áreas de entrega ou cobertura de serviço.
• TO (entrada): calcula a área de onde você pode viajar até o ponto de origem dentro do limite de tempo especificado. Isso é adequado para determinar zonas de influência, como de onde os funcionários podem se deslocar para chegar a um escritório central.

Reconhecimento de tráfego

Controle como os dados de trânsito influenciam o polígono gerado com o parâmetro routingPreference (routing_preference):

• TRAFFIC_UNAWARE (padrão): usa limites de velocidade de fluxo livre e hierarquia de vias para gerar o polígono de isócrona. Isso produz uma forma determinística que não varia de acordo com a hora do dia. Esse parâmetro é ideal para análises gerais ou planejamento de cenários de referência.
• TRAFFIC_AWARE: calcula isócronas usando as condições de trânsito em tempo real no momento exato em que a solicitação é processada (carimbos de data/hora personalizados de partida ou chegada futuros ou históricos não são configuráveis na v1). Isso faz com que a área acessível diminua durante o congestionamento e aumente durante os horários de menor movimento. Em condições de fluxo livre ou fora do horário de pico, TRAFFIC_AWARE e TRAFFIC_UNAWARE podem retornar polígonos quase idênticos. Observação: as rotas com informações de trânsito só são compatíveis quando travelMode está definido como DRIVE ou TWO_WHEELER.

Suavização e fidelidade

É possível personalizar a aparência e a precisão dos polígonos de saída usando os parâmetros polygonFidelity (polygon_fidelity) e enableSmoothing (enable_smoothing). Embora essas opções sejam independentes, elas trabalham juntas para determinar a forma final.

• polygonFidelity: controla a resolução da célula da grade espacial usada para aproximar o limite alcançável:

  • LOW: usa as maiores células de grade (várias centenas de metros de diâmetro). Ideal para cobrir grandes áreas com menos vértices e sem lacunas internas, resultando em uma forma generalizada que pode superestimar a área acessível ao longo de corredores de estradas estreitas.
  • MEDIUM: precisão e contagem de vértices equilibradas.
  • HIGH: usa as menores células de grade (aproximadamente 100 a 150 metros de diâmetro). Resulta em um ajuste mais preciso à rede viária alcançada, mas pode produzir buracos internos onde a rede viária é esparsa.
  • POLYGON_FIDELITY_UNSPECIFIED: se não for especificado, o serviço vai selecionar a resolução automaticamente com base no modo e na duração do trajeto, usando células mais refinadas para durações curtas e para WALK, e células mais amplas para durações longas. Para comparar isócronas em diferentes durações ou modos de viagem, defina polygonFidelity explicitamente.

    

• enableSmoothing: controla se as bordas escalonadas das células da grade definidas pela fidelidade são arredondadas.

  • false (Bruto): o padrão. Retorna o limite alinhado à grade. As bordas aparecem escalonadas ao longo das células da grade. Ideal para precisão analítica, como testes rigorosos de ponto em polígono.
  • true (Suavizado): arredonda os cantos nítidos para exibição visual do mapa, preservando aproximadamente a área de cada anel. O limite não segue mais as células da grade.