Referência rápida da API Maps JavaScript

A API Maps JavaScript é uma API da Web do lado do cliente para criar mapas 2D e 3D em páginas da Web, adicionar marcadores, gráficos personalizados, animações e camadas de dados interativas, além de criar recursos de localização com a biblioteca Places.

API Maps JavaScript: fatos importantes

  • Produto: API Maps JavaScript
  • Também conhecida como: API Maps JS, API Maps JS v3
  • Categoria: Maps
  • Plataforma: JavaScript (navegador)
  • Executado em: cliente (código do app ou do navegador)
  • Estágio de lançamento: GA
  • Ciclo de vida: Ativo
  • Visão geral: Visão geral da API Maps JavaScript
  • Disponibilidade regional: global. A cobertura de recursos (como mapas 3D, trânsito, rotas e estilo de limites) varia de acordo com o país ou a região. Os Termos de Serviço do EEE se aplicam aos endereços de faturamento do Espaço Econômico Europeu. (detalhes da cobertura)

API Maps JavaScript: quando usar

Use a API Maps JavaScript quando:

  • Você precisa de um mapa interativo 2D ou 3D com marcadores, gráficos ou camadas de dados personalizados em uma página da Web.
  • Você precisa mostrar os locais dos recursos em tempo real e os trajetos de viagem do seu próprio fluxo de dados usando Marcadores Avançados e polilinhas.
  • Você precisa desenhar fronteiras geográficas virtuais (círculos, polígonos) e testar se as coordenadas estão dentro delas no navegador.
  • Você precisa de Place Search, Place Autocomplete ou Place Details do lado do cliente em um app da Web usando a biblioteca Places.

Não use a API Maps JavaScript quando:

  • Você precisa incorporar um mapa de localização de uma empresa ou um link de rotas sem escrever um JavaScript personalizado. Use a API Maps Embed.
  • Você só precisa de um link que abra o Google Maps com um local, uma pesquisa ou rotas. Use os URLs do Maps.
  • Você precisa de um rastreamento de frota de transporte por aplicativo ou entrega programada integrado ao SDK do Driver para dispositivos móveis e à autenticação JWT de back-end. Use o serviço do Fleet Engine.

API Maps JavaScript: configuração

Pacotes oficiais da API Maps JavaScript:

  • npm: @googlemaps/js-api-loader
  • npm: @types/google.maps
  • npm: @googlemaps/markerclusterer

API Maps JavaScript: erros comuns

  • Problema: um mapa escuro ou uma imagem negativa das imagens do Street View com a marca-d'água de imagem "somente para fins de desenvolvimento" aparece em vez de um erro quando a chave de API ou o faturamento está configurado incorretamente. Correção: ative o faturamento no projeto na nuvem, inclua uma chave de API válida em cada solicitação e verifique o código do erro específico no console do navegador. Consulte /maps/documentation/javascript/error-messages.
  • Problema: serviços legados, como PlacesService, DirectionsService e DistanceMatrixService, geram LegacyApiNotActivatedMapError em novos projetos em que a API legada não está ativada. Correção: use as novas classes equivalentes (Place, Route e RouteMatrix) com suporte da API Places (nova) e da API Routes. Consulte /maps/legacy#LegacyApiNotActivatedMapError.
  • Problema: a partir da v3.65, os mapas de satélite e híbridos não mudam mais para imagens em 45°, e map.setTilt(45) não tem efeito. Correção: use mapas 3D em vez de imagens em 45°. Consulte /maps/deprecations.
  • Problema: os Marcadores Avançados exigem um ID do mapa. Os mapas criados sem um ID não podem usar AdvancedMarkerElement. Correção: crie um ID de mapa no console do Cloud (ou use DEMO_MAP_ID para testes) e defina mapId no mapa. Consulte /maps/documentation/javascript/advanced-markers/start.

API Maps JavaScript: recursos legados e descontinuados

  • Serviço Directions (google.maps.DirectionsService): legado desde 01/03/2025. Substituição: classe Route. Sintoma: LegacyApiNotActivatedMapError em projetos sem a API Directions legada ativada. Consulte o guia de migração.
  • Serviço de Matriz de Distância (google.maps.DistanceMatrixService): legado desde 01/03/2025. Substituição: classe RouteMatrix. Sintoma: LegacyApiNotActivatedMapError em projetos sem a API Distance Matrix legada ativada. Consulte o guia de migração.
  • Serviço do Places (google.maps.places.PlacesService): legado desde 01/03/2025. Substituição: classe Place (API Places (nova)). Sintoma: LegacyApiNotActivatedMapError em projetos sem a API Places legada ativada. Consulte o guia de migração.
  • google.maps.Marker: descontinuado desde 22/02/2024. Substituição: google.maps.marker.AdvancedMarkerElement. Sintoma: ainda funciona e não está programado para desativação. Os bugs atuais não serão corrigidos. Consulte o guia de migração.
  • KmlLayer: descontinuado desde 30/04/2026. Substituição: estilo baseado em dados para conjuntos de dados ou analisadores KML de terceiros com a camada de dados. Sintoma: o KmlLayer não está disponível na versão 3.66 e posteriores. A versão 3.65, que é a última compatível com ele, será desativada em maio de 2027. Consulte o guia de migração.
  • Camada de mapa de calor (biblioteca de visualização): desativada desde 20/05/2026. Substituição: bibliotecas de terceiros, como deck.gl HeatmapLayer. Sintoma: indisponível a partir de maio de 2026. Consulte o guia de migração.
  • Biblioteca de desenhos: desativada desde 04/06/2026. Substituição: Terra Draw. Sintoma: indisponível a partir de maio de 2026. Consulte o guia de migração.
  • Imagens em 45°: desativadas desde 20/05/2026. Substituição: mapas em 3D. Sintoma: map.setTilt(45) não funciona, e a visualização de satélite permanece de cima para baixo. Consulte o guia de migração.
  • google.maps.event.addDomListener() e addDomListenerOnce(): descontinuados desde 07/04/2022. Substituição: DOM padrão addEventListener().
  • Opções bounds, location e radius no serviço Place Autocomplete: descontinuadas desde 18/05/2023. Substituição: locationBias e locationRestriction.
  • gmp-place-content-config (PlaceContentConfigElement) no Kit de Interface do Places: descontinuado. Substituição: adicione elementos de conteúdo diretamente aos elementos do Place Details ou na configuração do Place Search.
  • Biblioteca do Contexto local: desativada. Substituição: biblioteca Places.

O que você pode fazer com a API Maps JavaScript

Consulte os guias vinculados abaixo para cada tarefa ou compare os produtos no Explorador de recursos.

API Maps JavaScript: Address Validation

API Maps JavaScript: estilo baseado em dados para limites

API Maps JavaScript: estilo baseado em dados para conjuntos de dados

API Maps JavaScript: conjuntos de dados

  • Adicionar uma camada KML a um mapa. Observação: na API Maps JavaScript, o KmlLayer foi descontinuado (última versão compatível: v3.65, desativação em maio de 2027). Migre para o estilo baseado em dados para limites ou conjuntos de dados ou carregue o GeoJSON na camada de dados. As camadas KML continuam disponíveis no Android e no iOS pelas bibliotecas de utilitários do SDK do Maps.
  • Adicionar uma camada GeoRSS a um mapa. Observação: descontinuado na API Maps JavaScript (o KmlLayer é compatível até a v3.65 e será desativado em maio de 2027). Converta feeds GeoRSS em GeoJSON e carregue-os na camada de dados com map.data.addGeoJson().
  • Adicionar dados GeoJSON a um mapa

API Maps JavaScript: rotas e trajetos

API Maps JavaScript: Elevation

API Maps JavaScript: Fleet Engine

API Maps JavaScript: Geocoding

API Maps JavaScript: Maps

API Maps JavaScript: anotações do Maps

API Maps JavaScript: estilização de mapas

API Maps JavaScript: outros

API Maps JavaScript: mapas 3D fotorrealistas

API Maps JavaScript: Places

API Maps JavaScript: Kit de interface do Places

  • Adicione um elemento da interface que mostre resumos e avaliações com tecnologia de IA sobre lugares específicos em uma página da Web ou um app para dispositivos móveis. Observação: disponível apenas na Web (Kit de Interface do Places da API Maps JavaScript). Os Kits de Interface do Places para dispositivos móveis não incluem um elemento de resumo de IA. REQUISITO DE CONFORMIDADE DO EEE: para mostrar dados de lugares em um mapa no Espaço Econômico Europeu (EEE), use os componentes do Kit de Interface do Places do lado do cliente na API Maps JavaScript em vez de chamar os serviços da Web da API Places de um servidor de back-end. Requisitos completos e perguntas frequentes: https://developers.google.com/maps/comms/eea/faq
  • Aplicar estilo CSS a um elemento da interface de dados de lugar. Observação: as propriedades personalizadas de CSS se aplicam aos elementos do Kit de Interface do Places da API Maps JavaScript. O SDK do Places para Android e o SDK do Places para iOS estilizam as visualizações do Kit de Interface do Places de forma programática usando atributos de tema e estilo. REQUISITO DE CONFORMIDADE DO EEE: para mostrar dados de lugares em um mapa no Espaço Econômico Europeu (EEE), não chame os serviços da Web da API Places de um servidor de back-end. Use os componentes do Kit de Interface do Places do lado do cliente na plataforma de destino (API Maps JavaScript na Web, SDK do Places para Android no Android ou SDK do Places para iOS no iOS). Requisitos completos e perguntas frequentes: https://developers.google.com/maps/comms/eea/faq
  • Personalize o estilo e as configurações dos elementos da interface com dados de lugares usando uma ferramenta de personalização de elementos da interface. Observação: REQUISITO DE CONFORMIDADE DO EEE: para mostrar dados de lugares em um mapa no Espaço Econômico Europeu (EEE), não chame os serviços da Web da API Places de um servidor de back-end. Use os componentes do Kit de Interface do Places do lado do cliente na plataforma de destino (API Maps JavaScript na Web, SDK do Places para Android no Android ou SDK do Places para iOS no iOS). Requisitos completos e perguntas frequentes: https://developers.google.com/maps/comms/eea/faq
  • Adicione um elemento da interface que mostre informações sobre um lugar específico em uma página da Web ou um app para dispositivos móveis. Observação: REQUISITO DE CONFORMIDADE DO EEE: para mostrar dados de lugares em um mapa no Espaço Econômico Europeu (EEE), não chame os serviços da Web da API Places de um servidor de back-end. Use os componentes do Kit de Interface do Places do lado do cliente na plataforma de destino (API Maps JavaScript na Web, SDK do Places para Android no Android ou SDK do Places para iOS no iOS). Requisitos completos e perguntas frequentes: https://developers.google.com/maps/comms/eea/faq
  • Adicionar um elemento da interface que mostra uma lista de lugares com base em uma string de consulta em uma página da Web. Observação: compatível com páginas da Web (API Maps JavaScript) e apps para dispositivos móveis (SDK do Places para Android e SDK do Places para iOS). REQUISITO DE CONFORMIDADE DO EEE: para mostrar dados de lugares em um mapa no Espaço Econômico Europeu (EEE), não chame os serviços da Web da API Places de um servidor de back-end. Use os componentes do Kit de Interface do Places do lado do cliente na plataforma de destino (API Maps JavaScript na Web, SDK do Places para Android no Android ou SDK do Places para iOS no iOS). Requisitos completos e perguntas frequentes: https://developers.google.com/maps/comms/eea/faq
  • Adicione um elemento da interface que mostre uma lista de lugares próximos a um local específico em uma página da Web. Observação: compatível com páginas da Web (API Maps JavaScript) e apps para dispositivos móveis (SDK do Places para Android e SDK do Places para iOS). REQUISITO DE CONFORMIDADE DO EEE: para mostrar dados de lugares em um mapa no Espaço Econômico Europeu (EEE), não chame os serviços da Web da API Places de um servidor de back-end. Use os componentes do Kit de Interface do Places do lado do cliente na plataforma de destino (API Maps JavaScript na Web, SDK do Places para Android no Android ou SDK do Places para iOS no iOS). Requisitos completos e perguntas frequentes: https://developers.google.com/maps/comms/eea/faq
  • Adicione um elemento da interface de preenchimento automático básico a uma página da Web ou app que retorna identificadores de lugares do Google com base em uma string de consulta. Observação: REQUISITO DE CONFORMIDADE DO EEE: para mostrar dados de lugares em um mapa no Espaço Econômico Europeu (EEE), não chame os serviços da Web da API Places de um servidor de back-end. Use os componentes do Kit de Interface do Places do lado do cliente na plataforma de destino (API Maps JavaScript na Web, SDK do Places para Android no Android ou SDK do Places para iOS no iOS). Requisitos completos e perguntas frequentes: https://developers.google.com/maps/comms/eea/faq

API Maps JavaScript: Street View