Ciclistas que planejam uma rota se importam com um número mais do que com qualquer outro: quanta subida está envolvida. Sessenta e poucos quilômetros planos e sessenta e poucos quilômetros de morro são pedais completamente diferentes, e um app de ciclismo feito para planejamento de rotas precisava de um jeito de mostrar essa diferença antes de alguém se comprometer com o pedal, e não depois de já estar na terceira subida e arrependido.
O app já tinha as rotas como uma sequência de coordenadas, geradas pelo seu próprio motor de roteamento a partir de um ponto de partida e de chegada. O que faltava era a altitude em cada um desses pontos. O /v1/elevation resolveu isso diretamente: você envia uma lista de coordenadas, seja um único ponto ou uma longa sequência ao longo de uma rota, e ele retorna a altitude do terreno para cada uma. Uma rota com duzentos pontos ao longo do percurso voltava como duzentos valores de altitude, ainda na ordem em que foram enviados, prontos para serem plotados como um perfil em relação à distância percorrida.
Essa lista, plotada em relação à distância acumulada, é o gráfico de subidas que os ciclistas realmente querem ver: onde estão os morros, quão íngreme parece a aproximação em comparação com os pontos vizinhos e onde ficam os trechos planos. O app a usava para calcular o ganho total de altitude de uma rota, um único número que acabou importando mais para os ciclistas decidirem se encarariam uma rota do que a distância total.
Como uma rota podia ter de algumas dezenas a algumas centenas de pontos, dependendo do comprimento, e como uma requisição de altitude em lote conta cada ponto como um item cobrado, o app ajustou quantos pontos amostrava por rota em vez de pedir a altitude na maior resolução possível para cada pedal. Uma rota suave amostrada a cada poucas centenas de metros produzia um perfil tão útil quanto um amostrado a cada dez metros, com uma fração do volume de requisições, e a diferença era invisível para um ciclista olhando o gráfico resultante.
O app também permitia que o ciclista consultasse um único ponto sob demanda, tocando em qualquer lugar do mapa para ver a altitude naquele ponto exato, o que usava o mesmo endpoint com uma requisição de um ponto em vez de uma rota completa. Tanto o caso de ponto único quanto o caso em lote passam pela mesma chamada, o que manteve o código do app simples: uma função que aceita uma lista de coordenadas e retorna uma lista correspondente de altitudes, usada tanto para um toque rápido quanto para o planejamento de uma rota completa.
O tráfego acompanhava quantas rotas os ciclistas planejavam, e não quantos pedais eles realmente faziam, já que uma rota salva só precisava ter o perfil calculado uma vez. Para um app com uma base de usuários ativa, mas não gigantesca, isso manteve as consultas de altitude bem dentro da cota diária gratuita, com o crédito pré-pago como o próximo passo natural caso um novo recurso popular causasse um pico no planejamento de rotas.
A altitude é um dos poucos endpoints em que é fácil dar um exemplo real: um pedal pelo litoral mostra valores de altitude perto do nível do mar nos primeiros pontos e valores crescentes à medida que a rota sobe para o interior, um gráfico que faz sentido para o ciclista num relance. Detalhes sobre o formato da requisição e os limites de pontos estão em /docs/elevation-lookup/.