Vá mais longe com o MapKit

Olá, sou o Alex. Sou engenheiro da equipe MapKit. O Mapas da Apple permite navegar e explorar lugares ao redor do mundo diretamente do dispositivo. Há muito o que descobrir, de marcos históricos a cafés aconchegantes, lojas locais e trilhas de caminhadas. Vou apresentar as atualizações do MapKit e do MapKit JS que permitem levar mapas para seus apps e sites. Começarei com o PlaceDescriptor, um novo jeito de encontrar e referenciar lugares. Depois, vou falar sobre geocodificação e como usá-la para exibir informações sobre um lugar. Por fim, vou ajudar a levar as pessoas ao seu destino com nossas APIs Directions e Look Around. Vou começar com a busca e a referência de lugares. Ano passado, apresentamos um identificador para referenciar os lugares representados por itens de mapa no framework MapKit e pelo Place no MapKit JS. As referências são únicas e continuam válidas ao longo do tempo. Quando a equipe Maps atualiza os dados de um lugar, como o URL do site, um app que usa o Place ID pode mostrar as informações atualizadas. Como os identificadores são únicos, o app pode usá-los como chaves em suas estruturas de dados. Os identificadores podem ser salvos e compartilhados. A Apple mantém o controle dos dados, e você pode consultá-los quando quiser. Os identificadores de lugar ainda são a melhor opção para armazenar uma referência a um lugar encontrado com o MapKit. Mas há casos em que podem não ser a melhor opção. Às vezes, você quer acessar os dados detalhados do MapKit para um lugar, mesmo sem ter um identificador. Por exemplo, se você tem uma API Web ou um CRM que fornece o nome e o endereço de todos os pontos comerciais. Ou talvez você tenha o nome e as coordenadas de um lugar específico. Nesses casos, você quer encontrar um lugar exato e único. APIs como a de busca local, que retornam vários resultados, não são a melhor opção. Outras vezes, quero passar referências de lugares usando códigos que não são meus. Talvez eu queira oferecer lugares usando um framework. Com o App Intents, posso receber um lugar como parâmetro de intenção, retornar um lugar como resultado da intenção ou incluir um lugar como propriedade nas entidades do app. Nesses casos, você pode estar interagindo com outros apps que não usam o MapKit. Posso passar uma representação geográfica, como CLLocation, mas não para encontrar um lugar de interesse detalhado, como acontece com um identificador do MapKit. Para esses casos, estamos apresentando um novo tipo: PlaceDescriptor. Está em um novo framework: GeoToolbox. O PlaceDescriptor permite fornecer informações que descrevem um lugar de modo estruturado.

Um PlaceDescriptor pode ser usado pelo MapKit ou por outros provedores de serviços de mapas para encontrar dados sobre esse lugar. Um PlaceDescriptor tem três informações principais: uma string chamada commonName. Ao criar seu PlaceDescriptor, forneça nomes conhecidos, como Museu Guggenheim ou Ópera de Sydney. Esse campo não é destinado a dados privados, como “Casa da mãe”, e incluí-lo não ajuda o MapKit a encontrar seu lugar.

PlaceDescriptor também tem uma matriz de representações. Essas representações são formatos comuns que qualquer app ou framework que lida com informações geográficas deve entender.

Há três tipos de PlaceRepresentations para escolher. O primeiro é uma string de endereço, como você escreveria em um envelope. Fornecer a versão mais completa possível do endereço aumenta as chances de o MapKit encontrar seu lugar. O próximo é uma coordenada, para locais em um ponto fixo e definido, como um marco ou um comércio. Por fim, uma deviceLocation, que usa CLLocation. É adequado para uso com dados de GPS recebidos e pode incluir valores extras como precisão, data/hora, direção ou velocidade. A matriz de representações deve conter pelo menos uma representação e estar ordenada por precedência decrescente. Se um PlaceDescriptor vem de um app de contatos, uma coordenada pode ter sido obtida com base no endereço desse lugar. Nesse caso, o endereço vem primeiro, pois é a fonte original da informação, e a coordenada fica em segundo. Por fim, PlaceDescriptor tem uma matriz de representações auxiliares. Essas representações podem não ser utilizadas por todos os apps e não são obrigatórias. A matriz supportingRepresentations pode estar vazia. Falaremos mais sobre o que pode estar nas supportingRepresentations. Para demonstrar o PlaceDescriptor e todas as outras novas APIs que estão por vir, vou apresentar um app de exemplo. É para entusiastas de fontes encontrarem fontes em locais distantes no mundo todo. Quero começar reunindo fontes em Dublin que seriam legais de visitar e colocá-las em um mapa.

Desde o lançamento do MapKit para SwiftUI, consigo criar um marcador simples no mapa com uma coordenada, mas quero aproveitar os dados detalhados do Mapas da Apple sobre minhas fontes junto com todas as outras APIs do MapKit no app, mesmo sem ter um Place ID. Uma ótima chance para usar o PlaceDescriptor. Vamos criar um PlaceDescriptor para referenciar esta fonte. Primeiro, importe a GeoToolbox. Sei que há uma fonte nessas coordenadas. Ao criar meu PlaceDescriptor, vou incluir uma representação de coordenadas com elas. Sei que se chama Anna Livia Fountain, então darei esse nome. Isso é tudo de que preciso para criar um PlaceDescriptor válido. Posso importar o MapKit e criar uma solicitação de item de mapa com meu PlaceDescriptor. Depois de criar minha solicitação, posso executá-la para obter um MKMapItem para o lugar. MapItem é o tipo principal para lugares no MapKit, e posso usá-lo com vários tipos de APIs.

Por exemplo, posso usar o MapItem em um mapa. O marcador exibe o nome, as cores e os ícones que o Mapas da Apple tem para esse lugar.

Vamos adicionar um segundo local ao mapa, desta vez usando um endereço para criar meu descritor. É só informar a versão mais completa do endereço que tenho para esta fonte. Então posso criar um PlaceDescriptor com isso e o nome da fonte. Uso MKMapItemRequest como antes e adiciono ao mapa junto com minha outra fonte. É muito fácil. Mostrei o poder de usar PlaceDescriptor para encontrar um local por nome e po PlaceRepresentations de coordenadas e endereço. Ainda há uma propriedade de nível superior do PlaceDescriptor que você pode usar. Há um único tipo de representação de suporte: identificadores de serviço. Uma representação de identificador de serviço é um dicionário em que a chave é o identificador do pacote de um serviço de mapas, e o valor é o identificador que representa seu local nesse serviço.

Se eu souber o identificador de lugar do MapKit para um local, posso criar um dicionário em que a chave é com.apple.mapKit e o valor é o identificador. Crio uma representação serviceIdentifiers e passo-a para o parâmetro supportingRepresentations do inicializador do PlaceDescriptor. Se eu souber o identificador de um local de outro provedor de serviço de mapas, posso fornecê-lo aqui. O MapKit não usa outros identificadores, mas fornecê-los pode ser útil em situações como App Intents, em que você pode enviar um PlaceDescriptor para outro app que talvez não use o MapKit. Forneça quantos identificadores quiser. Na API do MapKit, os identificadores de serviço são sempre manipulados corretamente. Se presente, a MKMapItemRequest usará os identificadores do MapKit do seu PlaceDescriptor para buscar o local. Se não houver identificador do MapKit ou o uso do identificador fornecido falhar, as outras representações do PlaceDescriptor serão usadas para encontrar o local. Da mesma forma, se você criar um PlaceDescriptor com um MapItem obtido de outra forma, ele será preenchido com todas as representações necessárias, incluindo o identificador. Vou usar PlaceDescriptor e MKMapItemRequest para adicionar ao meu app as outras fontes de Dublin que conheço. MapItems solicitados com PlaceDescriptor podem ser usados em todas as APIs do MapKit para mostrar dados no mapa, como os obtidos por identificador ou MKLocalSearch.

Por exemplo, cartões de lugar. Ao exibir o cartão de um lugar solicitado pelo PlaceDescriptor, é possível mostrar dados atualizados, como o horário de funcionamento, além de um link para o Mapas. Um cartão de lugar é exibido quando alguém seleciona uma fonte no app com só uma linha de código. Cartões de lugar são um modo fácil de mostrar informações úteis sobre um local no app. Confira “Liberar o poder dos lugares com o MapKit” da WWDC2024 para saber mais.

Este ano, os cartões de lugar no MapKit JS também oferecem um link universal para o Mapas. Em dispositivos com o app Mapas instalado, os links abrem lá. Para dispositivos sem o app Mapas, o cartão de lugar direciona para maps.apple.com, que foi lançado no ano passado em versão beta pública. Ao vincular seus apps e sites ao Mapas, até mesmo em plataformas de terceiros, você pode usar o Mapas na Web para explorar mais. Com o lançamento do iOS 18.4, atualizamos o modo como o Mapas lida com URLs, permitindo criar links universais com confiança. Por exemplo, este URL para fazer uma busca. Os parâmetros estão mais consistentes, simples e fáceis de ler.

Também foram adicionados vários parâmetros para vincular ainda mais recursos no Mapas. Confira “Adotar URLs de mapas unificados”, disponível nos materiais deste vídeo, para adotar links universais do Mapas no seu app.

Certo, encontrei meus lugares. Vou mostrar como usar geocodificação e representações de endereço para exibir mais informações sobre os lugares no seu app.

Se você não tiver familiaridade, geocodificação direta é o processo de pegar um endereço e encontrar a sua coordenada. Um exemplo disso é tocar em um endereço no app Contatos, que leva você para um mapa.

Geocodificação reversa é o oposto. Você fornece uma coordenada e um endereço é retornado. Por exemplo, quando você marca um local no app Mapas, as informações de endereço para aquele ponto são exibidas.

No iOS 18 e anteriores, você usava o CoreLocation para realizar as tarefas de geocodificação. Este ano, vamos descontinuar o CLGeocoder, descontinuar parcialmente o CLPlacemark e trazer a geocodificação para o MapKit.

No meu app, também quero registrar as fontes que encontrei e das quais tirei fotos maravilhosas. As fotos incluem uma localização geográfica, com as coordenadas de onde foram tiradas, mas sem informação adicional, como um nome. Ou seja, não posso usar o PlaceDescriptor para encontrar o local. Só tenho coordenadas. Vou usar a geocodificação reversa no MapKit para encontrar mais contexto para exibir ao lado das fotos.

Vamos fazer a geocodificação reversa da primeira foto.

Vou começar com as coordenadas de onde a foto foi tirada. Vou criar uma MKReverseGeocodingRequest com essa localização. Ao contrário da MKMapItemRequest com PlaceDescriptor, que mostrei antes, o inicializador da MKReverseGeocodingRequest retorna um opcional. Se você fornecer uma CLLocation com coordenadas inválidas, o MapKit não conseguirá realizar a solicitação. Quando a solicitação retorna, recebo uma matriz de itens de mapa. Nas solicitações de geocodificação, essa matriz deve conter apenas uma entrada. Vou escolher a primeira. Como este item de mapa veio de uma API de geocodificação, ele não conterá informações detalhadas sobre um ponto de interesse. Este mapItem contém apenas informações sobre o ponto do endereço. Agora que tenho meu mapItem, posso exibir o endereço.

Vou usar a solicitação MKReverseGeocoding para obter o endereço das outras fotos e exibi-los em uma lista. Meu app está começando a tomar forma, mas o endereço completo pode ser detalhado demais para esta tela. Vou analisar as outras opções que tenho. O MKMapItem oferece duas propriedades opcionais para acessar informações de endereço.

Primeiro, MKAddress. Você pode gerar seu MKAddress criando seu próprio MKMapItem. O MapKit também fornece um MKAddress ao retornar MapItems de APIs como geocodificação, busca local e resolução de PlaceDescriptor. Segundo, MKAddressRepresentations, que não tem um inicializador. As representações de endereço só estão disponíveis em itens de mapa retornados pelas APIs do MapKit.

Vou explicar o MKAddress primeiro. Ele tem duas propriedades de texto: fullAddress e shortAddress.

fullAddress é a versão mais completa de um endereço postal ou administrativo, enquanto shortAddress fornece apenas as partes mais essenciais.

Em alguns casos, o endereço fornecido pode ser breve. Uma geocodificação reversa para coordenadas no meio do oceano pode resultar em uma linha.

Ao gerar um MapItem personalizado, a propriedade address é usada nos cartões de lugar do MapKit, permitindo exibir suas próprias informações de endereço.

MKAddress oferece versões simples de um endereço e MKAddressRepresentations traz formas avançadas de exibir informações de endereço no seu app. Se quiser mostrar uma lista de endereços completos, que estão todos no mesmo país, pode optar por omitir a região na interface do app. Para isso, você pode usar fullAddress(includingRegion: false). Ou talvez você queira listar a cidade junto com contexto adicional sobre sua localização. Você pode exibir o estado ou a província, como Los Angeles, Califórnia. Ou incluir o país, como Paris, França. O MapKit escolhe a opção correta para o seu endereço, considerando as informações de localidade e região do dispositivo que solicita o item de mapa. Agora, com as diferentes representações de endereço disponíveis para meu app, vou escolher cityWithContext para tornar as informações de endereço exibidas com minhas fotos mais concisas. Estou mostrando o nível certo de detalhes para meu app e está ficando ótimo.

A API para geocodificação direta é parecida com a reversa. Com a MKGeocodingRequest, posso obter um MapItem, desta vez para o meu endereço. Isso facilita o acesso às coordenadas ou a adição ao mapa. Ele também inclui todas as opções que discutimos sobre informações de endereço, permitindo obter várias representações para exibir meu endereço, que eu não tinha antes da solicitação de geocodificação.

Agora que encontrei meus lugares e exibi algumas informações sobre eles, vou mostrar as APIs do MapKit que ajudam a navegar até eles. O MapKit tem uma API Directions que pode encontrar rotas entre uma origem e um destino usando vários meios de transporte, como a pé ou de carro. A API Directions oferece estimativas de tempo e distância, e informações detalhadas sobre as etapas a serem seguidas durante o trajeto.

Na visualização do mapa de Dublin, quero planejar os itinerários para as fontes que selecionei. Vou ativar a seleção com uma vinculação de item de mapa no inicializador. Posso calcular a rota quando o item selecionado for alterado. Para saber mais sobre como lidar com seleção no mapa, confira “Conhecer o MapKit para SwiftUI” da WWDC 2023.

Para obter minha rota, crio uma solicitação de itinerários. Defino a localização atual do dispositivo como origem e o item de mapa selecionado como destino. Depois, crio um objeto de itinerários. Por fim, calculo minha rota. Vou garantir o tratamento de erros e, em seguida, processar a resposta. O que vem na resposta de uma solicitação de itinerários?

Retornamos a origem e o destino que correspondem à sua rota. Eles podem ser um pouco diferentes do que você forneceu na sua solicitação. Os itinerários de carro podem considerar estacionamento, e itinerários a pé podem levar você até a porta de um prédio.

Também incluímos uma matriz com uma ou mais rotas que atendem à sua solicitação.

As rotas contêm muitas informações úteis, incluindo um nome localizado para usar como título, uma série de avisos relevantes, como fechamentos de estrada, a distância em metros, o tempo estimado para percorrer a rota e a geometria da rota, adequada para desenhar no mapa.

Estou feliz em compartilhar que este ano adicionamos suporte para itinerários de bicicleta ao MapKit. Para meu app, pedalar é a forma perfeita de conhecer as fontes de Dublin. Basta modificar uma propriedade na minha solicitação de itinerários. Quero mostrar uma rota de bicicleta possível, então vou usar a primeira rota da resposta. Vou adicioná-la ao meu mapa usando MapPolyline. É fácil mostrar itinerários.

As rotas de bicicleta com o MapKit são eficientes. Elas aproveitam caminhos e trilhas inacessíveis para carros e evitam certas ruas inadequadas para bicicletas. Obtenha itinerários de bicicleta e tempos estimados de chegada com o MapKit JS. Assim como no Swift, basta adicionar uma linha de configuração à solicitação de itinerários para especificar bicicleta como tipo de transporte.

Também estou contente em compartilhar que agora você pode obter itinerários com o MapKit no watchOS! Mais de 20 APIs do MapKit chegaram ao Apple Watch com o SDK mais recente do watchOS.

Agora que tenho uma boa rota de bicicleta para o meu tour das fontes, eu sentiria mais segurança pedalando se pudesse conferir o trajeto antes de sair. Ao ativar o recurso Olhe ao redor do Mapas, posso obter imagens interativas em 360 graus no nível da rua e pré-visualizar ruas, ciclovias, estacionamentos e pontos de referência.

O Olhe ao redor foi lançado para apps MapKit no iOS 16, incluindo APIs para verificar se há imagens em uma localização, pré-visualizar imagens do Olhe ao redor e exibi-las em tela cheia. Para saber mais, confira a sessão “Novidades no MapKit” da WWDC 2022.

Este ano, o Olhe ao redor chega ao MapKit JS para que você possa ativá-lo no seu site ou aplicativo Web. Há dois tipos de visualizações do Olhe ao redor para adicionar. O primeiro é o Olhe ao redor interativo, que permite incorporar uma visualização navegável pelo usuário dentro da própria interface. O segundo é a prévia. Isso fornece um instantâneo estático da imagem no local desejado. Clicar na pré-visualização inicia uma experiência interativa em tela cheia. Para adicionar uma visualização interativa do Olhe ao redor ao meu site, preciso de um objeto Place. Posso usar uma API do MapKit JS que retorne um Place, como placeLookup, search ou geocoding. Como tenho um identificador, vou usar placeLookup. Em seguida, crio um objeto Look Around, passando o elemento DOM contêiner, o objeto Place e, por fim, um dicionário de opções. O LookAroundView é compatível com três opções. A primeira é openDialog. Quando essa opção é true, a LookAroundView cobre toda a janela do navegador. A segunda é showsDialogControl. Quando essa opção é true, um botão aparece na LookAroundView permitindo entrar e sair da experiência em tela cheia. Por fim, showsCloseControl. Quando é true, inclui um botão que fecha a visualização de Olhe ao redor. O MapKit JS emitirá vários eventos relacionados à LookAroundView. Adicione ouvintes de eventos para responder ou substituir comportamentos padrão. Quando o usuário toca no botão para fechar, um evento close é disparado. Use esse callback para executar animações ou mudanças de estado que façam sentido no seu app.

Se você não cancelar a ação padrão desse evento, a visualização de lookAround será removida do DOM. Outros eventos a serem manipulados incluem: O evento Load, que é disparado quando a visualização é totalmente carregada. O evento Error, que é disparado quando ocorre algum problema. Quando as imagens não estão disponíveis ou quando o navegador não é capaz de exibir a visualização. O MapKit JS fornece uma interface de erro, mas você pode ter sua própria experiência de erro ou fallback. Por fim, o lookAround dispara eventos readystatechange, que podem ser usados para monitorar o ciclo de vida da visualização. O ready state muda quando a visualização está carregando, termina de carregar, ocorre um erro ou é removida do DOM. Além da LookAroundView, você pode usar a API Look Around Preview para ter uma experiência mais simples. As prévia do Olhe ao redor não são interativas. Não é possível mover a visualização. Clicar na prévia do Olhe ao redor inicia uma experiência em tela cheia. O LookAround com o MapKit JS vai aprimorar seus sites. E isso encerra nossa sessão. Foi uma fonte de conhecimento. Mostrei como encontrar lugares, exibir informações e navegar por locais ao redor do mundo usando o MapKit e o MapKit JS.

Antes de encerrar, vou deixar uma tarefa para você. Use o PlaceDescriptor para encontrar lugares com ou sem identificador e para enviar referências de lugares para outros apps. Atualize os links para o Mapas usando o novo formato unificado de URLs.

Migre seus apps do CoreLocation para as APIs do MapKit para geocodificação e aproveite nossas representações de endereços. E adicione itinerários para bicicleta e o Olhe ao redor ao seu app para ajudar as pessoas a chegar ao seu destino.

Agradeço por assistir e aprender sobre o MapKit comigo.