O Roads API retorna o limite de velocidade determinado para um determinado trecho da via. No caso de trechos de via com limites de velocidade variáveis, o limite de velocidade padrão do trecho é retornado.
Não é possível garantir a precisão dos dados de limite de velocidade retornados pelo Roads API. Os dados de limite de velocidade fornecidos não são em tempo real e podem ser estimados, imprecisos, incompletos ou desatualizados. Consulte os detalhes da cobertura para saber em quais regiões os dados de limite de velocidade estão disponíveis.
Solicitações
Envie solicitações de limites de velocidade usando HTTPS, da seguinte forma:
https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEYUso de parâmetros
Parâmetros obrigatórios
- Um parâmetro
pathouplaceId.path: uma lista de até 100 pares de latitude/longitude que representam um caminho. Os valores de latitude e longitude precisam ser separados por vírgulas. Os pares de latitude/longitude precisam ser separados pelo caractere de barra vertical: "|". Ao fornecer o parâmetropath, a API primeiro ajusta o caminho à via mais provável percorrida por um veículo (como faz para a solicitaçãosnapToRoads) e depois determina o limite de velocidade do trecho de via relevante. Se você não quiser que a API ajuste o caminho, transmita um parâmetroplaceId, conforme explicado abaixo. O exemplo a seguir mostra o parâmetropathcom três pares de latitude/longitude:path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796.placeId: os IDs de lugar que representam um ou mais segmentos de via. Verifique se cada ID de lugar se refere a um trecho de via e não a um tipo diferente de lugar. É possível transmitir até 100 IDs de lugar com cada solicitação. A API não faz o ajuste de rota nos IDs de lugar fornecidos. A resposta inclui um limite de velocidade para cada ID de lugar na solicitação. Envie uma solicitaçãosnapToRoadsounearestRoadspara encontrar os IDs de lugar relevantes e fornecê-los como entrada para a solicitaçãospeedLimits. O exemplo a seguir mostra o parâmetroplaceIdcom dois IDs de lugar:placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
key: a chave de API do seu aplicativo. Seu aplicativo precisa se identificar sempre que enviar uma solicitação para o Roads API, incluindo uma chave de API em cada solicitação. Saiba como conseguir uma chave.
Parâmetros opcionais
units: se os limites de velocidade devem ser retornados em quilômetros ou milhas por hora. Pode ser definido comoKPHouMPH. O padrão éKPH.
Respostas
Os seguintes elementos podem estar presentes em uma resposta speedLimits:
speedLimits: uma matriz de metadados de vias. Cada elemento consiste nos seguintes campos:placeId: um identificador exclusivo de um lugar. Todos os IDs de lugar retornados pelo Roads API corresponderão a trechos de vias.speedLimit: o limite de velocidade para esse trecho da via.units: retornaKPHouMPH.
snappedPoints: um array de pontos ajustados. Essa matriz só estará presente se a solicitação contiver um parâmetropath. Cada ponto consiste nos seguintes campos:location: contém um valorlatitudeelongitude.originalIndex: um número inteiro que indica o valor correspondente na solicitação original. Cada valor na solicitação precisa ser mapeado para um valor ajustado na resposta. Esses valores são indexados de0. Portanto, um ponto com umoriginalIndexde4será o valor ajustado da 5ª latitude/longitude transmitida ao parâmetropath.placeId: um identificador exclusivo de um lugar. Todos os IDs de lugar retornados pelo Roads API corresponderão a trechos de vias. OplaceIdpode ser transmitido em uma solicitação de limites de velocidade para determinar o limite de velocidade ao longo desse trecho da via.
warning_message: uma string que contém um aviso visível para o usuário.
Exemplo de solicitação usando um caminho
Essa solicitação recebe o limite de velocidade de cada trecho da via mais próximo dos pares de latitude/longitude especificados em um caminho que atravessa a ponte Vasco da Gama em Lisboa, Portugal.
Solicitação
https://roads.googleapis.com/v1/speedLimits?path=38.75807927603043,-9.03741754643809|38.6896537,-9.1770515|41.1399289,-8.6094075&key=YOUR_API_KEYResposta
{
speedLimits:
[
{
placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE",
speedLimit: 105,
units: "KPH"
},
{
placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU",
speedLimit: 70,
units: "KPH"
},
{
placeId: "ChIJJ4vQRudkJA0RpednU70A-5M",
speedLimit: 55,
units: "KPH"
}
],
snappedPoints:
[
{
location:
{
latitude: 38.75807927603043,
longitude: -9.037417546438084
},
originalIndex: 0,
placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE"
},
{
location:
{
latitude: 38.689653701836896,
longitude: -9.177051486847693
},
originalIndex: 1,
placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU"
},
{
location:
{
latitude: 41.13993011767777,
longitude: -8.609400794783655
},
originalIndex: 2,
placeId: "ChIJJ4vQRudkJA0RpednU70A-5M"
}
],
warningMessage: "Input path is too sparse. You should provide a path where consecutive points are closer to each other. Refer to the 'path' parameter in Google Roads API documentation."
}Observe a mensagem de aviso para a escassez de pontos na resposta acima. Se você
estiver solicitando limites de velocidade para os segmentos de via mais próximos em pontos arbitrários,
chame speedLimits com IDs de lugar recuperados do endpoint
nearestRoads.
Exemplo de solicitação usando IDs de lugares
Em vez de usar pares de latitude/longitude, você pode transmitir os IDs dos segmentos de via. Recomendamos que você obtenha IDs de lugar para trechos de vias usando solicitações snapToRoads ou nearestRoads. Quando você transmite IDs de lugar, a API retorna o limite de velocidade para o trecho da via representado por cada ID. A API não aplica o ajuste de vias aos IDs de lugar fornecidos.
O exemplo a seguir solicita os limites de velocidade de alguns trechos da via que cruzam a ponte Vasco da Gama em Lisboa, Portugal.
Solicitação
https://roads.googleapis.com/v1/speedLimits?placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU&placeId=ChIJJ4vQRudkJA0RpednU70A-5M&key=YOUR_API_KEYResposta
{
"speedLimits": [
{
placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE",
speedLimit: 105,
units: "KPH"
},
{
placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU",
speedLimit: 70,
units: "KPH"
},
{
placeId: "ChIJJ4vQRudkJA0RpednU70A-5M",
speedLimit: 55,
units: "KPH"
}
]
}Recomendações de uso
Para minimizar o volume de chamadas ao serviço de limite de velocidade, recomendamos fazer uma amostra dos locais dos seus recursos em intervalos de 5 a 15 minutos. O valor exato depende da velocidade em que um recurso está viajando. Se um recurso está fixo, uma única amostra de local é suficiente (não é necessário fazer várias chamadas).
Para minimizar a latência geral, recomendamos chamar o serviço de limite de velocidade depois de acumular alguns dados, em vez de chamar a API sempre que a localização de um recurso para dispositivo móvel for recebida.
Por que alguns ou todos os limites de velocidade não aparecem?
A causa mais comum da falta de speedLimits é a solicitação do limite de velocidade de um lugar que não é um trecho da via.
O exemplo acima usa a ponte Vasco da Gama para ilustrar conceitos. Ela sustenta a rodovia E90 que atravessa o Rio Tejo. A ponte tem um ID de lugar ChIJUzt97ZEwGQ0RM1JzQfqoDtU. O primeiro trecho da via na resposta acima faz parte da rodovia E90 e tem um ID de lugar ChIJX12duJAwGQ0Ra0d4Oi4jOGE. No exemplo de solicitação, se você substituir o ID do lugar da via pelo ID do lugar da ponte, na resposta haverá apenas dois limites de velocidade na matriz speedLimits, porque o ID do lugar da ponte não se refere a um segmento de via individual. Além disso, se nenhum dos IDs de lugar for de trechos de via, a resposta não vai conter limites de velocidade.
Ao fazer solicitações de limite de velocidade usando IDs de lugar, verifique se cada ID se refere a um trecho de via e não a um tipo diferente de lugar. Os IDs de lugar para segmentos de via individuais são melhor recuperados usando solicitações snapToRoads ou nearestRoads, que podem retornar vários IDs de lugar de uma única chamada.