O Roads API retorna o limite de velocidade estabelecido para um determinado trecho de via. No caso de trechos de via com limites de velocidade variáveis, o limite de velocidade padrão do trecho é retornado.
A precisão dos dados de limites de velocidade retornados pelo Roads API não pode ser garantida. Os dados sobre limites de velocidade fornecidos não são apresentados em tempo real e podem ser estimados, imprecisos, incompletos e/ou desatualizados. Confira os detalhes da cobertura para conferir 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 no 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 precisam 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 à via mais provável percorrida por um veículo (como acontece na solicitaçãosnapToRoads) e, em seguida, determina o limite de velocidade para o 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 trechos de via. Cada ID de lugar precisa se referir a um trecho de via, e não a um tipo diferente de lugar. É possível transmitir até 100 IDs de lugar em cada solicitação. A API não realiza o ajuste de vias nos IDs de lugar fornecidos. A resposta inclui um limite de velocidade para cada ID de lugar 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 ao Roads API incluindo uma chave de API em cada solicitação. Saiba como receber 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 campos abaixo:placeId: identificador exclusivo de um local. Todos os IDs de lugar retornados pelo Roads API correspondem a trechos de via.speedLimit: o limite de velocidade para o trecho de via.units: retornaKPHouMPH.
snappedPoints: uma matriz 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 valor delatitudeelongitude.originalIndex: um número inteiro que indica o valor correspondente na solicitação original. Cada valor da solicitação precisa ser mapeado para um valor ajustado na resposta. Esses valores são indexados a partir de0. Portanto, um ponto com umoriginalIndexde4será o valor ajustado da quinta latitude/longitude passada ao parâmetropath.placeId: identificador exclusivo de um local. Todos os IDs de lugar retornados pelo Roads API correspondem a trechos de via. OplaceIdpode ser transmitido em uma solicitação de limites de velocidade para determinar o limite nesse trecho da via.
warning_message: uma string que contém um aviso visível ao usuário.
Exemplo de solicitação usando um caminho
Essa solicitação mostra o limite de velocidade de cada trecho de via 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ê está solicitando limites de velocidade para os trechos 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 de lugar dos trechos de via. Recomendamos que você consiga IDs de lugar para trechos de via usando solicitações snapToRoads ou nearestRoads. Quando você transmite IDs de lugares, a API retorna o limite de velocidade do trecho de via representado por cada um deles. A API não aplica nenhum ajuste de vias aos IDs de lugar fornecidos.
O exemplo a seguir solicita os limites de velocidade para alguns dos trechos de 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_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 que você faça uma amostragem 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 estiver fixo, uma única amostra de local será 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 estão faltando?
A causa mais comum da ausência de speedLimits é solicitar o limite de velocidade de um lugar que não seja um trecho de via.
O exemplo acima usa a ponte Vasco da Gama para ilustrar conceitos. Ela suporta a estrada E90 que cruza o Rio Tejo. Ela tem o ID de lugar ChIJUzt97ZEwGQ0RM1JzQfqoDtU. O primeiro trecho de via na resposta acima faz parte da estrada E90 e tem o ID de lugar ChIJX12duJAwGQ0Ra0d4Oi4jOGE. Na solicitação de exemplo, se você substituir o ID de lugar da via pelo ID da ponte, haverá na resposta apenas dois limites de velocidade na matriz speedLimits, porque o ID de lugar da ponte não se refere a um trecho de via individual. Além disso, se nenhum dos IDs de lugar for para trechos de via, a resposta não vai ter 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, não a um tipo diferente de lugar. Para recuperar os IDs de lugares de trechos de via individuais, use solicitações snapToRoads ou nearestRoads, que retornam vários IDs de lugar de uma única chamada.