Usar annotatePaths para receber anotações de caminho

Com o método annotatePaths, é possível receber anotações sobre atributos dinâmicos de tráfego nos caminhos solicitados. Essas anotações podem ser úteis para implementações de sistemas avançados de assistência ao motorista (ADAS).

Você pode receber anotações de caminho enviando uma solicitação com uma lista dos caminhos em que quer receber anotações e os tipos de anotações que quer nesses caminhos. A resposta contém os caminhos com os dados anotados solicitados anteriormente. Os caminhos na resposta são anotados como se o veículo estivesse percorrendo cada caminho no momento da solicitação.

Principais conceitos

As subseções a seguir descrevem os conceitos necessários para entender o método annotatePaths.

Caminhos e segmentos

Esse método anota dados em paths, que são uma sequência de segmentos conectados que um veículo pode percorrer.

O diagrama a seguir ilustra dois caminhos, cada um composto por três segmentos.

Diagrama ilustrando uma grade de vias, com dois caminhos compostos por três segmentos cada. Os caminhos começam com os mesmos dois segmentos, mas vão em direções diferentes no terceiro.

Figura 1. Um diagrama do Caminho 1, que consiste nos segmentos A, B e C, e Caminho 2, nos segmentos A, B e D.

Um caminho é limitado a 15 km de comprimento e é medido do início do primeiro trecho até o início do último. Se o início do último trecho começar a mais de 15 km do início do primeiro, ocorrerá um erro.

O início de um caminho é sempre o local presumido. Um veículo pode ter vários caminhos que terminam em locais diferentes, mas não podem começar em locais diferentes.

As anotações de segmento podem diferir dependendo do caminho do qual fazem parte. Mesmo que dois caminhos compartilhem alguns dos mesmos segmentos, as anotações deles podem variar.

Por exemplo, na Figura 1:

  • O caminho 1 consiste em:

    • Segmento A
    • Segmento B
    • Segmento C

  • O caminho 2 consiste em:

    • Segmento A
    • Segmento B
    • Segmento D

No caminho 1, o segmento B é seguido pelo segmento C e, no caminho 2, o mesmo segmento B é seguido por um segmento diferente, o segmento D.

O trecho B pode ter diferentes atributos dinâmicos retornados para o Caminho 1 e o Caminho 2, pois a conversão à direita no Caminho 2 pode gerar mais tráfego do que o caminho reto no Caminho 1.

Níveis de serviço

Nível de serviço é um termo usado de modo geral para descrever a categorização do fluxo de tráfego previsto com base na velocidade, densidade, congestionamento do veículo e outros parâmetros. É importante observar que os níveis de definições de serviço usados nesse método e descritos nesta documentação são reservados e exclusivos do método.

A lista a seguir descreve os níveis de serviço usados.

Nível de serviço Valor Descrição
LEVEL_OF_SERVICE_UNSPECIFIED 0 Valor padrão. Esse valor significa que não há um valor de tráfego previsto disponível.
LEVEL_OF_SERVICE_STOPPED 1 O trânsito está parado, e o veículo não está se movendo.
LEVEL_OF_SERVICE_STOP_AND_GO 2 O trânsito está parado, e o veículo está se movendo em baixa velocidade e para logo em seguida.
LEVEL_OF_SERVICE_SLOW 3 Há uma previsão de que o trânsito está lento e o veículo está se movendo lentamente, mas não há previsão de engarrafamentos.
LEVEL_OF_SERVICE_NORMAL 4 O trânsito está na velocidade normal e não há previsão de lentidão.

Receber anotações de caminho

É possível receber anotações de caminho enviando uma solicitação HTTP POST ao método annotatePaths (REST) ou chamando o método AnnotatePaths (gRPC).

As subseções a seguir descrevem os corpos de solicitação e resposta usados para solicitar e receber anotações de caminho e links para a referência REST.

Corpo da solicitação

O corpo da solicitação do método annotatePaths contém o seguinte:

  • Paths: a rota solicitada (conjunto de caminhos) a ser anotada com dados do atributo dinâmico. Todos os caminhos nesse trajeto devem ter o mesmo trecho inicial, ou seja, aquele em que o veículo está. Supõe-se que o veículo esteja no início do primeiro trecho. Se os caminhos não começarem no mesmo trecho, um erro será retornado.
    • Path: um caminho em que os atributos dinâmicos estão sendo solicitados.
    • Segments: uma lista ordenada de segmentos que forma o caminho.
  • AnnotationOptions: as anotações solicitadas para os caminhos de entrada.
    • includeLevelOfService: um campo booleano. Quando definido como verdadeiro, os segmentos na resposta são anotados com os valores de tráfego previstos. Consulte a seção Níveis de serviço deste documento para mais informações.

Requisitos de solicitação

O corpo da solicitação para o método annotatePaths precisa seguir os próximos requisitos:

  • Os caminhos precisam começar com o mesmo segmento.
  • Os caminhos precisam ter menos de 15 km, sendo que o último trecho não começa a mais de 15 km do início do primeiro trecho.
  • A solicitação precisa ter 10 caminhos ou menos.

Exemplo de solicitação

O exemplo a seguir mostra um corpo de solicitação do método annotatePaths. Neste exemplo, você está enviando um caminho composto de três segmentos, especificando que você quer incluir o nível das anotações de serviço.

paths {
  segments {
    place_id: "ChIJqZ402gQVkFQRcM9QM5EHX1A"
    polyline {
      encoded_polyline: "ojxaHfkviVuAjA_@l@y@jC"
    }
  }
  segments {
    place_id: "ChIJg_9y5AQVkFQRKL3E7_fPM_o"
    polyline {
      encoded_polyline: "_pxaHlsviVg@bB"
    }
  }
  segments {
    place_id: "ChIJle5mqwUVkFQRuhQhpqFyxRM"
    polyline {
      encoded_polyline: "gqxaHpvviV_EtM"
    }
  }
}
annotation_options {
  include_level_of_service: true
}

Corpo da resposta

O corpo da resposta do método annotatePaths contém o seguinte:

  • annotatedPaths: caminhos da entrada anotados com atributos solicitados.
    • AnnotatedPath: uma cópia de um caminho de entrada retornado com atributos previstos.
    • annotatedSegments: uma lista ordenada de segmentos que forma o caminho principal, anotada com atributos solicitados.
      • AnnotatedSegment: um segmento que cria um caminho, anotado com atributos de dados dinâmicos.
      • Segment: um segmento que pertence a um caminho.
        • placeId: o ID do lugar desse trecho da via que pode ser o mesmo valor do campo placeId do objeto DirectionalSegment.
      • SegmentSpanAttributes: atributos atribuídos ao segmento. Esses atributos podem variar de acordo com o caminho em que o segmento se encontra. Um período pode cobrir todo o segmento. Os períodos dos atributos vão estar em ordem de ida do local do veículo até o fim do caminho.
        • SegmentSpan: descreve em que parte do segmento as anotações se aplicam.
        • LevelOfService: o nível de tráfego previsto para o período do segmento, definido pelas velocidades de trânsito esperadas nesse trecho quando o veículo chega no início do trecho. Consulte a seção Níveis de serviço deste documento para mais informações.

Exemplo de resposta

O exemplo a seguir mostra um corpo de solicitação do método annotatePaths. Nesse exemplo, você recebe o nível de anotações de serviço no caminho solicitado na Solicitação de amostra.

annotated_paths {
  annotated_segments {
    segment {
      place_id: "ChIJqZ402gQVkFQRcM9QM5EHX1A"
    }
    segment_span_attributes {
      segment_span {
        start_meters: 0
        end_meters: 142
      }
      level_of_service: LEVEL_OF_SERVICE_NORMAL
    }
  }
  annotated_segments {
    segment {
      place_id: "ChIJg_9y5AQVkFQRKL3E7_fPM_o"
    }
    segment_span_attributes {
      segment_span {
        start_meters: 0
        end_meters: 44
      }
      level_of_service: LEVEL_OF_SERVICE_NORMAL
    }
  }
  annotated_segments {
    segment {
      place_id: "ChIJle5mqwUVkFQRuhQhpqFyxRM"
    }
    segment_span_attributes {
      segment_span {
        start_meters: 0
        end_meters: 206
      }
      level_of_service: LEVEL_OF_SERVICE_NORMAL
    }
  }
}