Criar uma viagem e receber um token de viagem

Para iniciar uma sessão de navegação guiada com segurança para um motorista, seu back-end precisa criar uma viagem e receber um token de viagem autenticado da API Navigation Connect.

No Navigation Connect, uma viagem representa uma sessão de navegação para um único destino. Para criar uma viagem e receber o token de viagem autenticado (authToken) necessário para autorizar a sessão, envie uma mensagem CreateTripRequest para o método CreateTrip. Transmita o token de viagem para seu app para dispositivos móveis e inclua no URL de inicialização do Google Maps ou do Waze.

Este guia descreve como concluir esse processo gerando um ID de viagem exclusivo e enviando sua solicitação de API.

Construir uma mensagem CreateTripRequest

Para criar uma viagem e receber um token, siga estas etapas para construir e enviar uma mensagem CreateTripRequest:

  1. Autenticar: use o Application Default Credentials (ADC) para conseguir um token de acesso e autorizar sua solicitação. Para mais detalhes, consulte Criar um token OAuth.
  2. Gerar um ID de viagem: crie um ID de viagem exclusivo (tripId) no formato UUIDv4 para identificar a viagem no seu servidor.
  3. Construa o payload: crie um payload JSON que inclua os IDs do app e as configurações de configuração.
  4. Chame o método CreateTrip: envie uma solicitação POST à API com o token de acesso no cabeçalho e o payload no corpo.

O exemplo a seguir mostra como criar uma viagem enviando uma mensagem CreateTripRequest:

#!/bin/bash

# Authenticate with ADC
access_token="$(gcloud auth application-default login --impersonate-service-account=SERVICE_ACCOUNT_EMAIL)"

# Generate a unique Trip ID
trip_id="$(uuidgen)"

# Construct the payload
payload=$(cat <<EOF
{
  "androidAppId": "ANDROID_APP_ID",
  "iosAppId": "IOS_APP_ID",
  "config": {
    "enablePubsub": true
  }
}
EOF
)

# Call the CreateTrip method to request a trip token
curl -X POST "https://navigationconnect.googleapis.com/v1/projects/PROJECT_ID/trips?tripId=${trip_id}" \
-H "Authorization: Bearer ${access_token}" \
-H "Content-Type: application/json" \
-d "${payload}"

Configurações opcionais

É possível personalizar os dados da viagem ajustando as seguintes configurações na mensagem CreateTripRequest:

Recurso Tipo Descrição
Relatórios de trajeto restante (somente no Waze) boolean

Para receber a polilinha da rota ativa e as condições de trânsito em tempo real, defina config.enableRemainingRouteReporting como true.
Frequência de atualização da viagem boolean

Por padrão, o Navigation Connect atualiza os dados da viagem a cada 60 segundos. Para ativar atualizações de alta frequência (a cada 5 segundos), defina config.enableHighFrequencyUpdates como true.
Geração de eventos do Google Cloud Pub/Sub boolean

Para ativar a geração de eventos de viagem usando o Google Cloud Pub/Sub, defina config.enablePubsub como true. Esse recurso fica desativado por padrão.
Máscara de campo do Google Cloud Pub/Sub FieldMask

Para gerenciar tamanhos de payload e reduzir a carga de processamento do back-end ou os custos de uso do Google Cloud Pub/Sub, use config.pubsubFieldMask para excluir campos pesados (como execution.remainingRoute) do fluxo de eventos. Para mais informações sobre o tamanho do payload dos dados restantes da rota, consulte Processar os dados restantes da rota.

Receber o token da viagem na resposta

O método CreateTrip retorna uma resposta que contém o token de viagem autenticado. Para autorizar a sessão de navegação, extraia esse token da resposta e transmita-o ao seu app para dispositivos móveis para incluir no URL de inicialização.

O exemplo de código a seguir mostra uma resposta de exemplo:

{
    "name": "projects/PROJECT_NUMBER/trips/TRIP_ID",
  "authToken": {
    "token": "BASE64_ENCODED_TRIP_TOKEN",
    "expireTime": "2026-03-06T11:09:47.476942Z"
  },
  "state": "NEW",
  "execution": {
    "traveledDistanceMeters": 0,
    "stopAddedInRoute": false
  },
  "createTime": "2026-03-05T23:09:50.768959Z",
  "updateTime": "2026-03-05T23:09:50.768959Z"
}

Essa resposta inclui os seguintes valores:

  • PROJECT_NUMBER: um identificador numérico exclusivo para seu projeto. Ele é diferente do ID alfanumérico do projeto, mas representa o mesmo projeto do Google Cloud.
  • TRIP_ID: o ID da viagem gerado pelo seu back-end no formato UUIDv4.
  • BASE64_ENCODED_TRIP_TOKEN: o token de viagem autenticado (authToken.token) retornado pelo método CreateTrip. Transmita esse token para seu app para dispositivos móveis e inicie a navegação guiada rastreada no Google Maps ou no Waze.

A seguir

Use o token de viagem para iniciar o Google Maps ou o Waze.

Abra o Google Maps ou o Waze.