Carregar a API Maps JavaScript

Neste guia, mostramos como carregar a API Maps JavaScript. Existem três maneiras de fazer isso:

Usar a API Dynamic Library Import (recomendado)
Usar o pacote js-api-loader do NPM
Usar a tag legada de carregamento do script

Usar a API Dynamic Library Import

Para carregar a API Maps JavaScript, adicione um carregador bootstrap inline ao código do aplicativo, como mostrado no snippet a seguir:

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

Também é possível incluir o código do carregador bootstrap diretamente no código JavaScript.

Para carregar bibliotecas em tempo de execução, use o operador await para chamar importLibrary() em uma função async, como mostrado no exemplo de código abaixo:

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();index.ts

JavaScript

let map;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();index.js

Parâmetros obrigatórios

key: sua chave de API. A API Maps JavaScript só é carregada quando uma chave de API válida é definida.

Parâmetros opcionais

v: a versão da API Maps JavaScript que será carregada.
libraries: uma lista separada por vírgulas de outras bibliotecas da API Maps JavaScript que serão carregadas. Em geral, não é recomendável especificar um conjunto fixo de bibliotecas, mas talvez seja útil para desenvolvedores interessados em ajustar o comportamento de armazenamento em cache no próprio site.
language: o idioma que será usado. Isso afeta os nomes de controles, notificações de direitos autorais, rotas de carro e etiquetas de controle, além das respostas às solicitações de serviço. Consulte a lista de idiomas compatíveis.
region: o código da região a ser usado. Esse parâmetro muda o comportamento do mapa com base em um determinado país ou território.
solutionChannel: a Plataforma Google Maps oferece muitos tipos de exemplo de código para que você comece a usar o produto rapidamente. O Google inclui o parâmetro de consulta solutionChannel nas chamadas de API no exemplo de código para acompanhar a implementação dos exemplos mais complexos e melhorar a qualidade da solução.
authReferrerPolicy: os clientes do Maps JS podem configurar restrições de referenciadores HTTP no console do Cloud e assim limitar os URLs com permissão para usar uma chave de API. Por padrão, essas restrições são configuradas para que apenas alguns caminhos possam usar uma chave de API. Se qualquer URL no mesmo domínio ou origem puder usar a chave de API, defina o parâmetro authReferrerPolicy: "origin" para limitar a quantidade de dados enviados ao autorizar solicitações da API Maps JavaScript. Quando esse parâmetro for especificado, só vai ser possível carregar a API Maps JavaScript se as restrições de referenciadores HTTP estiverem ativadas e uma delas corresponder ao domínio do site atual sem um caminho definido.

Usar o pacote js-api-loader do NPM

O pacote @googlemaps/js-api-loader (link em inglês) está disponível para carregamento usando o gerenciador de pacotes do NPM. Instale-o com o seguinte comando:

npm install @googlemaps/js-api-loader

Esse pacote pode ser importado para o aplicativo com:

import { Loader } from "@googlemaps/js-api-loader"

O carregador expõe uma interface de callback e promessa. Confira a seguir o uso do método de promessa padrão load().

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.js

Confira um exemplo com js-api-loader.

Usar a tag legada de carregamento do script

Essa tag ainda é compatível. Esta seção oferece suporte a integrações usando a tag legada de carregamento do script. O Google recomenda migrar para a API Dynamic Library Loading.

Adicionar uma tag de script

Para carregar a API Maps JavaScript inline em um arquivo HTML, adicione uma tag script, como mostrado abaixo.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>

Parâmetros de URL referentes à tag legada de carregamento do script

Nesta seção, abordamos todos os parâmetros que podem ser especificados na string de consulta referente ao URL de carregamento do script ao carregar a API Maps JavaScript. Alguns parâmetros são obrigatórios, outros são opcionais. Como é padrão em URLs, todos os parâmetros são separados usando o caractere E comercial (&).

O URL de exemplo a seguir tem marcadores de posição para todos os parâmetros possíveis:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&solution_channel="SOLUTION_IDENTIFIER"
&auth_referrer_policy="AUTH_REFERRER_POLICY"

O URL no exemplo de tag script a seguir carrega a API Maps JavaScript:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>

Parâmetros obrigatórios (legados)

Estes são os parâmetros obrigatórios ao carregar a API Maps JavaScript.

key: sua chave de API. A API Maps JavaScript só é carregada quando uma chave de API válida é especificada.
callback: o nome de uma função global que será chamada após o carregamento completo da API Maps JavaScript.

Parâmetros opcionais (legados)

Use estes parâmetros para solicitar uma versão específica da API Maps JavaScript, carregar outras bibliotecas, localizar seu mapa ou especificar a política sobre verificação do referenciador HTTP.

v: a versão da API Maps JavaScript a ser usada.
libraries: uma lista separada por vírgulas de outras bibliotecas da API Maps JavaScript a serem carregadas.
language: o idioma a ser usado. Esse parâmetro afeta os nomes de controles, notificações de direitos autorais, rotas de carro e rótulos de controle, além das respostas às solicitações de serviço. Consulte a lista de idiomas compatíveis.
region: o código da região a ser usado. Esse parâmetro muda o comportamento do mapa com base em um determinado país ou território.
solution_channel: a Plataforma Google Maps oferece muitos tipos de exemplo de código para que você comece a usar o produto rapidamente. O Google inclui o parâmetro de consulta solution_channel nas chamadas de API no exemplo de código para acompanhar a implementação dos exemplos mais complexos e melhorar a qualidade da solução.

Observação: esse parâmetro de consulta é para uso do Google. Consulte o parâmetro de soluções da Plataforma Google Maps para mais informações.
auth_referrer_policy: os clientes do Maps JS podem configurar restrições de referenciadores HTTP no console do Cloud e assim limitar os URLs com permissão para usar uma determinada chave de API. Por padrão, essas restrições são configuradas para que apenas alguns caminhos possam usar uma chave de API. Se qualquer URL no mesmo domínio ou origem puder usar a chave de API, defina auth_referrer_policy=origin para limitar a quantidade de dados enviados ao autorizar solicitações da API Maps JavaScript. Disponível a partir da versão 3.46. Quando esse parâmetro for especificado, só vai ser possível carregar a API Maps JavaScript se as restrições de referenciadores HTTP estiverem ativadas e uma delas corresponder ao domínio do site atual sem um caminho definido.

Migrar para a API Dynamic Library Import

Nesta seção, abordamos as etapas necessárias para migrar a integração e usar a API Dynamic Library Import.

Etapas de migração

Primeiro, substitua a tag legada de carregamento do script pela tag inline do carregador bootstrap

Antes

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>

Depois

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

Em seguida, atualize o código do aplicativo:

Mude a função initMap() para ser assíncrona.
Chame importLibrary() para carregar e acessar as bibliotecas necessárias.

Antes

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;

Depois

let map;
// initMap is now async
async function initMap() {
    // Request libraries when needed, not in the script tag.
    const { Map } = await google.maps.importLibrary("maps");
    // Short namespaces can be used.
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}

initMap();