Antes de começar: antes de começar a usar a API Elevation, você precisa de um projeto com uma conta de faturamento e a API Elevation ativada. Recomendamos ter vários proprietários de projetos e administradores de faturamento, para que você sempre tenha alguém com esses papéis disponíveis na sua equipe. Para saber mais, consulte Configurar no Console do Cloud.
Esse serviço também está disponível como parte da API Maps JavaScript do lado do cliente ou para uso do lado do servidor com o cliente Java, cliente Python, cliente Go e cliente Node.js para os serviços do Google Maps.
A API Elevation oferece uma interface simples para consultar dados no Google Earth sobre dados de elevação. Além disso, você pode solicitar dados de elevação de amostragem ao longo dos caminhos, calculando mudanças de elevação ao longo dos trajetos. Com a API Elevation, é possível desenvolver aplicativos de caminhada e ciclismo, aplicativos de posicionamento ou aplicativos de pesquisa de baixa resolução.
Os dados de elevação estão disponíveis para todos os locais na superfície terrestre, incluindo locais em profundidade no fundo do oceano, que retornam valores negativos. Nos casos em que o Google não tem medidas de elevação exatas no local exato solicitado, o serviço interpola e retorna um valor médio usando os quatro locais mais próximos. Os valores de elevação são expressos em relação ao nível do mar médio local (LMSL, na sigla em inglês).
A API Elevation é acessada por uma interface HTTP. Os usuários da API Maps JavaScript também podem acessar essa API diretamente usando o objeto ElevationService(). Consulte Serviço de elevação para mais informações.
Antes de começar
Este documento é destinado a desenvolvedores de sites e dispositivos móveis que querem usar dados de elevação em mapas fornecidos por uma das APIs da Plataforma Google Maps. Ele fornece uma introdução ao uso da API e a materiais de referência sobre os parâmetros disponíveis.
Antes de começar a desenvolver com a API Elevation, veja os requisitos de autenticação (você precisa de uma chave de API) e as informações de uso e faturamento da API (ative o faturamento no seu projeto).
Solicitações de elevação
As solicitações da API Elevation são construídas como uma string de URL. A API retorna dados de elevação para locais no planeta. Você especifica dados de local de duas maneiras:
- Como um conjunto de um ou mais locations.
- Como uma série de pontos conectados ao longo de um path.
Qualquer uma dessas abordagens usa coordenadas de latitude/longitude para identificar os locais ou vértices de caminho. Este documento descreve o formato necessário dos URLs da API Elevation e os parâmetros disponíveis.
A API Elevation retorna dados para consultas de ponto único da maior precisão possível. Consultas em lote que envolvem vários locais podem retornar dados com menos acurácia, especialmente se os locais forem distribuídos remotamente, já que há uma suavização dos dados.
Uma solicitação da API Elevation tem o seguinte formato:
https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
em que outputFormat pode ser um dos seguintes valores:
- json (recomendado), indica a saída em Notação de objetos JavaScript (JSON); ou
- xml, indica a saída em XML, encapsulada em um nó <ElevationResponse>.
Observação: os URLs precisam ser codificados corretamente para serem válidos e estão limitados a 8.192 caracteres para todos os serviços da Web. Esteja ciente desse limite ao criar seus URLs. Observe que navegadores, proxies e servidores diferentes também podem ter limites de caracteres de URL diferentes.
O HTTPS é obrigatório para solicitações que usam uma chave de API.
Parâmetros de solicitação
As solicitações para a API Elevation usam diferentes parâmetros com base no fato de a solicitação ser para locais discretos ou para um caminho ordenado. Para locais discretos, as solicitações de elevação retornam dados sobre os locais específicos transmitidos na solicitação. Para caminhos, as solicitações de elevação são amostradas ao longo do caminho fornecido.
Como é padrão em todos os URLs, os parâmetros são separados usando o caractere de"e"comercial (&). A lista de parâmetros e os possíveis valores estão indicados abaixo.
Todas as solicitações
- key: (obrigatório) a chave de API do seu aplicativo. Essa chave identifica o aplicativo para fins de gerenciamento de cotas. Saiba como criar uma chave.
Solicitações posicionais
- locations (obrigatório) define os locais na Terra de onde retornar dados de elevação. Esse parâmetro usa um único local como um par de {latitude,longitude} separado por vírgula (por exemplo, "40.714728,-73.998672") ou vários pares de latitude/longitude transmitidos como uma matriz ou como uma polilinha codificada. Há um limite de 512 pontos para esse parâmetro específico. Para mais informações, consulte Especificar locais abaixo.
Solicitações de caminho de amostra
- path (obrigatório) define um caminho no planeta sobre o qual retornar dados de elevação. Esse parâmetro define um conjunto de dois ou mais pares ordenados de {latitude,longitude} que definem um caminho ao longo da superfície terrestre. Esse parâmetro precisa ser usado em conjunto com o parâmetro samples descrito abaixo. Há um limite de 512 pontos para esse parâmetro específico. Para mais informações, consulte Especificar caminhos abaixo.
- samples (obrigatório) especifica o número de pontos de amostra ao longo de um caminho para o qual dados de elevação serão retornados. O parâmetro samples divide o path especificado em um conjunto ordenado de pontos equidistantes ao longo do caminho.
Especificar locais
As solicitações posicionais são indicadas pelo uso do parâmetro locations, que indica solicitações de elevação para os locais específicos transmitidos como valores de latitude/longitude.
O parâmetro locations pode ter os seguintes argumentos:
- Uma única coordenada: locations=40.714728,-73.998672
- Uma matriz de coordenadas separadas pelo caractere de barra vertical ('|'): locations=40.714728,-73.998672|-34.397,150.644
- Um conjunto de coordenadas codificadas usando o algoritmo de polilinha codificada: locations=enc:gfo}EtohhU
As strings de coordenadas de latitude e longitude são definidas por numerais separados por uma string de texto, Por exemplo, "40.714728,-73.998672" é um valor locations válido. Os valores de latitude e longitude precisam corresponder a um local válido no rosto da Terra. As latitudes podem assumir qualquer valor entre -90 e 90, enquanto os valores de longitude podem assumir qualquer valor entre -180 e 180. Se você especificar um valor inválido de latitude ou longitude, seu pedido será rejeitado como inválido.
Você pode transmitir até 512 coordenadas em uma matriz ou polilinha codificada enquanto ainda cria um URL válido. Ao transmitir várias coordenadas, a precisão dos dados retornados pode ter uma resolução menor do que ao solicitar dados de uma única coordenada. exceder 512 pontos ou coordenadas nos parâmetros 'locations' ou 'path' retorna uma resposta INVALID_REQUEST.
Como especificar caminhos
As solicitações de caminho de amostragem são indicadas pelo uso dos parâmetros path e samples, que indicam uma solicitação de dados de elevação ao longo de um caminho em intervalos especificados. Assim como acontece com as solicitações posicionais que usam o parâmetro locations, o parâmetro path especifica um conjunto de valores de latitude e longitude. No entanto, ao contrário de uma solicitação posicional, o path especifica um conjunto ordenado de vértices. Em vez de retornar dados de elevação apenas nos vértices, as solicitações de caminho são amostradas ao longo do comprimento do caminho, com base no número de samples especificado (incluindo os endpoints).
O parâmetro path pode usar um dos argumentos a seguir:
- Uma matriz de duas ou mais strings de texto de coordenadas separadas por vírgulas separadas por uma barra vertical ('|'): path=40.714728,-73.998672|-34.397,150.644
- Coordenadas codificadas usando o Algoritmo de polilinha codificada: path=enc:gfo}EtohhUxD@bAxJmGF
As strings de coordenadas de latitude e longitude são definidas por numerais separados por uma string de texto, Por exemplo, "40.714728,-73.998672|-34.397, 150.644" é um valor path válido. Os valores de latitude e longitude devem corresponder a um local válido no rosto da Terra. As latitudes podem assumir qualquer valor entre -90 e 90, enquanto os valores de longitude podem assumir qualquer valor entre -180 e 180. Se você especificar um valor inválido de latitude ou longitude, seu pedido será rejeitado como inválido.
Você pode transmitir até 512 coordenadas em uma matriz ou polilinha codificada enquanto ainda cria um URL válido. Ao transmitir várias coordenadas, a precisão dos dados retornados pode ser de resolução mais baixa do que ao solicitar dados para uma única coordenada. exceder 512 pontos ou coordenadas nos parâmetros 'locations' ou 'path' retorna uma resposta INVALID_REQUEST.
Respostas de elevação
Para cada solicitação válida, o Serviço de elevação retornará uma resposta de elevação no formato indicado no URL da solicitação.
- OK indicando que a solicitação API foi bem sucedida.
- DATA_NOT_AVAILABLE indicando que não há dados disponíveis para os locais de entrada.
- INVALID_REQUEST indicando que o pedido API foi malformado.
- OVER_DAILY_LIMIT indicando qualquer uma das seguintes opções:
- A chave API está faltando ou é inválida.
- O faturamento não foi habilitado em sua conta.
- Um limite de uso auto-imposto foi excedido.
- O método de pagamento fornecido não é mais válido (por exemplo, um cartão de crédito expirou).
- OVER_QUERY_LIMIT indicando que o solicitante excedeu a cota.
- REQUEST_DENIED indicando que a API não completou a solicitação.
- UNKNOWN_ERROR indicando um erro desconhecido.
Quando o código de status é diferente de OK, pode haver um campo adicional de error_message no objeto de resposta Elevation. Esse campo contém informações mais detalhadas sobre os motivos por trás do código de status fornecido.
Observação:não há garantia de que esse campo esteja sempre presente, e o conteúdo dele está sujeito a mudanças.
Exemplos de elevação posicional
O exemplo a seguir solicita a elevação de Denver, Colorado, a "Mile High City" no formato JSON:
https://maps.googleapis.com/maps/api/elevation/json
?locations=39.7391536%2C-104.9847034
&key=YOUR_API_KEY
{
"results":
[
{
"elevation": 1608.637939453125,
"location": { "lat": 39.7391536, "lng": -104.9847034 },
"resolution": 4.771975994110107,
},
],
"status": "OK",
}
O exemplo a seguir mostra várias respostas (para Denver, CO e Para o Vale da Morte, CA).
Esta solicitação demonstra o uso da sinalização JSON output:
https://maps.googleapis.com/maps/api/elevation/json
?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667
&key=YOUR_API_KEY
Esta solicitação demonstra o uso da sinalização output XML:
https://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY
Selecione as guias abaixo para ver as respostas JSON e XML de exemplo
{
"results":
[
{
"elevation": 1608.637939453125,
"location": { "lat": 39.7391536, "lng": -104.9847034 },
"resolution": 4.771975994110107,
},
{
"elevation": -52.79492568969727,
"location": { "lat": 36.455556, "lng": -116.866667 },
"resolution": 19.08790397644043,
},
],
"status": "OK",
}
Os exemplos a seguir solicitam dados de elevação ao longo de uma linha reta path de Mt. Whitney, CA a Badwater, CA, os pontos mais alto e mais baixo na parte continental dos Estados Unidos. Pedimos três samples, então isso incluirá os dois endpoints e o ponto médio.
https://maps.googleapis.com/maps/api/elevation/json
?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171
&samples=3
&key=YOUR_API_KEY
{
"results":
[
{
"elevation": 4411.94189453125,
"location": { "lat": 36.578581, "lng": -118.291994 },
"resolution": 19.08790397644043,
},
{
"elevation": 1372.8359375,
"location": { "lat": 36.41150289067028, "lng": -117.5602607523847 },
"resolution": 9.543951988220215,
},
{
"elevation": -84.51690673828125,
"location": { "lat": 36.23998, "lng": -116.83171 },
"resolution": 9.543951988220215,
},
],
"status": "OK",
}