9. Map Display API

Owned by Eduardo Nakamura (Unlicensed)
Last updated: Feb 06, 2023 by Willian Silva
5 min read

A Map Display API é um novo recurso para exibição de mapas em páginas web utilizando Javascript. Integrado com a biblioteca Leaflet, oferece uma camada de funções para executar tarefas, como desenhar rotas e pontos de interesse de forma facilitada, usando os mesmos formatos de dados adotados pelas APIs da Maplink Platform.

Com a Map Display API você pode:

  • Visualizar a rota processada pela Trip API.

  • Apresentar pontos e marcadores, linhas e polígonos customizados no mapa.

Primeiros passos

Importar a API Javascript

A API Javascript da Maplink está disponível publicamente na url https://maps.maplink.global, e pode ser incluída em qualquer página web facilmente com uma tag script:

<script src="https://maps.maplink.global"></script>

Criar objeto do mapa

Com a API já importada, tudo o que é necessário fazer para renderizar um mapa é definir um elemento div em sua página, e criar uma instância da classe MaplinkMap associada a este elemento.

O construtor da classe espera por dois argumentos obrigatórios: a chave de api da Maplink (client_id usada para autenticação das APIs), e o id do elemento div onde o mapa será renderizado.

<div id="map"></div> <script> const apiKey = "[api key da minha aplicação]"; const maplink = new MaplinkMap(apiKey, "map"); </script>

Um terceiro argumento de configurações pode ser passado opcionalmente na construção do mapa. Este argumento deve ser um objeto, onde cada propriedade corresponde a uma definição de configuração. As opções disponíveis são:

  • renderType - Aceita os valores string "pbf" e "png". Seleciona o formato em que os tiles do mapa serão enviados pelo servidor. Por padrão, o formato é o protobuf (pbf), que utiliza recurso de aceleração gráfica do navegador por meio da API WebGL. Em ambientes sem suporte a WebGL, é necessário que seja configurada a opção png, ou o mapa não poderá ser renderizado.

  • center - Objeto de coordenada, definindo o ponto central na renderização inicial do mapa.

  • zoom - Número que define o nível de zoom inicial. Este valor é repassado diretamente para a instância do leaflet associada ao mapa. Mais informações podem ser encontradas no link: Zoom levels - Leaflet .

Formatos comuns de parâmetros

Coordenadas geográficas

Todos os métodos da api que recebem como parâmetro coordenadas geográficas aceitam dois formatos distintos:

  • Maplink Platform - Objeto contendo as propriedades de latitude e longitude. Este formato é compatível com os retornos das APIs da Maplink Platform, como a Trip e a Planning, visando facilitar a integração com elas. Exemplo:

maplink.marker({latitude: -23.986437,longitude: -46.308303});

  • Leaflet - Array contendo os valores de latitude e longitude, respectivamente. É o formato padrão de coordenadas do Leaflet. Exemplo:

Configurações opcionais

Os métodos que possuem configurações opcionais, como definições de cor e tamanho de formas geométricas, sempre terão o argumento options. O valor esperado para este argumento é um objeto cujas propriedades representam as definições de configuração.

Recursos

Marcadores

Um marcador é simplesmente um ponto destacado no mapa, que pode ser usado para mostrar pontos de interesse (POIs) ou simplesmente paradas de uma rota, por exemplo.

Para criar um marcador simples, basta usar o método marker, passando um objeto que representa sua coordenada:

O resultado do código acima será similar ao da imagem:

 

Balão de texto (Popup)

Se desejar associar ao marcador um balão de texto, contendo sua descrição, é possível passar como segundo argumento um objeto de configurações contendo a propriedade popup. Esta propriedade aceita uma string, que pode conter formatação html:

Ícone customizado

É possível também definir ícones customizados para seus marcadores, ao invés de usar o ícone padrão da Maplink. Para tal, primeiro deve-se criar um objeto de ícone usando o método icon. Ele recebe três parâmetros, na ordem:

  • uma string, obrigatória, com o caminho para imagem do ícone, cujo formato deve ser preferencialmente png;

  • uma string, opcional, com o caminho para imagem da sombra a ser projetada pelo ícone;

  • um objeto, opcional, com propriedades de tamanho (size) e posicionamento (anchor) do ícone, de sua sombra, e dos balões de texto.

Um exemplo de definição completa de ícone com sua sombra ficaria assim:

Sendo a sombra um atributo opcional dos ícones, é possível omiti-la. O exemplo acima sem sua sombra ficaria desta forma:

Com o ícone criado, basta passá-lo na propriedade icon do objeto de configurações do método marker.

O método icon é um “wrapper” da função de mesmo nome do Leaflet, assim, para saber mais sobre as configurações de ícones customizados, acesse sua documentação em Leaflet - a JavaScript library . Ícones criados diretamente através do Leaflet podem ser passados normalmente para o método marker.

 

Linhas

Linhas podem ser desenhadas no mapa, geralmente com o propósito de ilustrar rotas entre dois ou mais pontos. O método line permite criar facilmente uma linha, passando como argumento um array de objetos de coordenada:

O resultado do código acima deve ser similar ao da imagem:

Quando não é passado nenhum tipo de configuração, alguns valores padrão serão utilizados, como por exemplo a cor da linha. O segundo argumento do método aceita um objeto de configuração, que pode conter as propriedades:

  • color: uma string de definição da cor da linha, aceita os mesmos valores de propriedades de cor de CSS, como nome de cor ou código hexadecimal. O valor padrão é "red".

  • fitBounds: um valor booleano, define se a linha deve ser enquadrada na renderização inicial do mapa. O valor padrão é true.

Segue como ficaria o exemplo anterior de linha com a definição de sua cor:

Acesso ao Leaflet

Para utilizar recursos ou parâmetros do Leaflet que ainda não possuem equivalentes em nossa API Javascript, é possível acessar diretamente o Leaflet e seu objeto de mapa pelas propriedades L e map, respectivamente.

O exemplo abaixo utiliza a função circle do Leaflet, para desenhar um círculo:

Para checar todas as funcionalidades que o Leaflet oferece, consulte a documentação em Leaflet JavaScript library. A versão utilizada em nossa API atualmente é a 1.7.

 

 

Parâmetros e Exemplos