O Roads API retorna o limite de velocidade divulgado para um determinado trecho da estrada. No caso de segmentos de estrada com limites de velocidade variáveis, o limite de velocidade padrão do segmento é retornado.
A precisão dos dados de limite de velocidade retornados pelo Roads API não pode ser garantida. Os dados de limite de velocidade fornecidos não são em tempo real e podem ser estimados, imprecisos, incompletos e/ou desatualizados. Consulte os detalhes de cobertura para ver as regiões em que os dados de limite de velocidade estão disponíveis.
Solicitações
Uma solicitação de limites de velocidade precisa ser enviada por HTTPS com o seguinte formato:
https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEY
Uso 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 devem ser separados por vírgulas. Os pares de latitude/longitude precisam ser separados pelo caractere de barra vertical: "|". Quando você fornece o parâmetropath, a API primeiro ajusta o caminho para a via mais provável percorrida por um veículo, como a solicitaçãosnapToRoads, e determina o limite de velocidade para o segmento de estrada 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 trechos de estrada. Verifique se cada ID de lugar se refere a um trecho de via, e não a um tipo diferente de lugar. É possível passar até 100 IDs de lugar em cada solicitação. A API não realiza o ajuste de estrada nos IDs de local fornecidos. A resposta inclui um limite de velocidade para cada ID de local na solicitação. Você pode enviar 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 aplicativo. Seu aplicativo precisa se identificar toda vez que enviar uma solicitação para o Roads API incluindo uma chave de API em cada solicitação. Saiba como gerar uma chave.
Parâmetros opcionais
units: se os limites de velocidade serão retornados em quilômetros ou milhas por hora. Isso 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 estrada. Cada elemento consiste nos seguintes campos:placeId: um identificador exclusivo para um lugar. Todos os IDs de lugar retornados por Roads API corresponderão aos segmentos de estrada.speedLimit: o limite de velocidade para esse trecho de estrada.units: retornaKPHouMPH.
snappedPoints: uma matriz de pontos direcionados. Essa matriz estará presente apenas 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 a partir de0, então um ponto com umoriginalIndexde4será o valor ajustado da quinta latitude/longitude passada para o parâmetropath.placeId: um identificador exclusivo para um lugar. Todos os IDs de lugar retornados por Roads API corresponderão aos segmentos de estrada. 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 segmento de estrada mais próximo dos pares de latitude/longitude especificados em um caminho que cruza 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_KEY
Resposta
{
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 sobre esparsidade de pontos na resposta acima. Se você estiver solicitando limites de velocidade para os trechos de via mais próximos em pontos arbitrários, chame speedLimits com IDs de lugares recuperados do endpoint nearestRoads.
Exemplo de solicitação usando IDs de lugar
Em vez de usar pares de latitude/longitude, você pode transmitir os IDs de lugar dos segmentos de estrada. Recomendamos que você consiga IDs de lugares para trechos de via usando solicitações snapToRoads ou nearestRoads. Quando você passa os IDs de lugar, a API retorna o limite de velocidade do trecho de estrada representado por cada ID de local. A API não aplica qualquer ajuste de estrada aos IDs de lugar fornecidos.
O exemplo a seguir solicita os limites de velocidade de alguns segmentos de estrada 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_KEY
Resposta
{
"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 para o serviço de limite de velocidade, recomendamos a amostragem dos locais dos recursos em intervalos de 5 a 15 minutos (o valor exato depende da velocidade em que um recurso está viajando). Se um recurso é 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/todos os limites de velocidade estão ausentes?
A causa mais comum da falta de speedLimits é solicitar o limite de velocidade de um lugar que não é um segmento de estrada.
O exemplo acima usa a ponte Vasco da Gama para ilustrar conceitos. A ponte suporta a estrada E90 que cruza o Rio Tejo. A ponte em si tem o ID de local ChIJUzt97ZEwGQ0RM1JzQfqoDtU. O primeiro trecho da resposta acima faz parte da estrada E90 e tem o ID de local ChIJX12duJAwGQ0Ra0d4Oi4jOGE. Na solicitação de exemplo, se você substituir o ID de lugar da estrada pelo ID de lugar da ponte, na resposta haverá apenas dois limites de velocidade na matriz speedLimits, porque o ID de lugar da ponte não se refere a um segmento de estrada individual. Além disso, se nenhum dos IDs de local for para segmentos de estrada, a resposta não conterá limites de velocidade.
Ao fazer solicitações de limite de velocidade usando IDs de lugar, verifique se cada um deles se refere a um trecho de via, e não a um tipo diferente de lugar. IDs de lugares para segmentos individuais de vias são mais bem recuperados com solicitações snapToRoads ou nearestRoads, que podem retornar vários IDs de lugar de uma única chamada.