Práticas recomendadas para usar a API Maps Static

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

As APIs da Web estáticas da Plataforma Google Maps são um conjunto de interfaces HTTP para serviços do Google que geram imagens que podem ser incorporadas diretamente na sua página da Web.

Neste guia, descrevemos algumas práticas comuns que são úteis para configurar suas solicitações de imagens e processar serviços. Consulte o guia do desenvolvedor para ver a documentação completa da API Maps Static.

O que é uma API Static Web?

Com as APIs da Web estáticas da Plataforma Google Maps, você pode incorporar uma imagem da sua página da Web sem precisar do JavaScript ou de qualquer carregamento dinâmico de página. As APIs criam uma imagem com base nos parâmetros de URL enviados por uma solicitação HTTP padrão e permitem exibir o resultado na sua página da Web.

Uma solicitação típica da API Maps Static geralmente tem o seguinte formato:

https://maps.googleapis.com/maps/api/staticmap?parameters

Observação: todos os aplicativos da API Maps Static exigem autenticação. Veja mais informações sobre as credenciais de autenticação.

Acesso SSL/TLS

O HTTPS é obrigatório para todas as solicitações da Plataforma Google Maps que usam chaves de API ou contêm dados do usuário. As solicitações feitas por HTTP que contêm dados confidenciais podem ser rejeitadas.

Criar um URL válido

Você pode achar que um URL "válido" é imediatamente identificável, mas não funciona assim. Um URL inserido em uma barra de endereço de um navegador, por exemplo, pode conter caracteres especiais (por exemplo, "上海+中國"). O navegador precisa converter internamente esses caracteres em uma codificação diferente antes de transmiti-los. Da mesma forma, qualquer código que gere ou aceite entrada UTF-8 pode tratar URLs com caracteres UTF-8 como "válidos", mas também precisa converter esses caracteres antes de enviá-los a um servidor da Web. Esse processo é chamado de codificação de URL ou codificação por cento.

Caracteres especiais

É necessário traduzir caracteres especiais porque todos os URLs precisam estar em conformidade com a sintaxe especificada pela especificação do localizador uniforme de recursos (URI, na sigla em inglês). Efetivamente, isso significa que os URLs devem conter apenas um subconjunto especial de caracteres ASCII: os familiares símbolos alfanuméricos e alguns caracteres reservados para uso como caracteres de controle em URLs. Esta tabela resume esses caracteres:

Resumo de caracteres válidos para URLs
ConjuntoCaracteresUso em URLs
Alfanuméricos a b c d e f g h i j k k l m n o p q r s t u v x y z A B C D E F G H I J K L M N N P P R S T U V X Y Z 0 1 2 3 4 5 5 5 Strings de texto, uso do esquema (http), porta (8080) etc.
Não reservados - _ . ~ Strings de texto
Reservados ! * ' ( ) ; : @ & = + $ , / ? % # [ ] Caracteres de controle e/ou strings de texto

Ao criar um URL válido, você precisa garantir que ele contenha apenas os caracteres mostrados na tabela Resumo de caracteres de URL válidos. Conformar um URL ao uso desse conjunto de caracteres geralmente causa dois problemas, um de omissão e um de substituição.

  • Caracteres que você quer processar existem fora desse conjunto. Por exemplo, os caracteres de idiomas estrangeiros como 上海+中國 precisam ser codificados como mostrado acima. Por convenção popular, os espaços (que não são permitidos nos URLs) também são geralmente representados pelo caractere do sinal de adição ('+').
  • Caracteres existem no conjunto acima como caracteres reservados, mas precisam ser usados literalmente. Por exemplo, ? é usado em URLs para indicar o início da string de consulta. Se você quiser usar a string "? and the Mysterions", codifique o caractere '?'.

Todos os caracteres que precisam ser codificados para serem adicionados a URLs são codificados por meio do uso de um '%' e um valor hexadecimal de dois caracteres correspondente ao seu caractere UTF-8. Por exemplo, 上海+中國 em UTF-8 seria codificado como %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B para uso em URLs. A string ? and the Mysterians seria codificada em um URL como %3F+and+the+Mysterians ou %3F%20and%20the%20Mysterians.

Caracteres comuns que precisam de codificação

Alguns caracteres comuns que precisam ser codificados:

Caractere inválido Valor codificado
Espaço %20
" %22
< %3C
> %3E
# %23
% %25
| %7C

Converter um URL recebido de uma entrada do usuário pode ser complicado. Por exemplo, um usuário pode inserir um endereço como "5th&Main St". Geralmente, você precisa criar o URL das partes dele, tratando quaisquer entradas do usuário como caracteres literais.

Além disso, os URLs estão limitados a 8.192 caracteres para todos os serviços da Web da Plataforma Google Maps e APIs estáticas da Web. Para a maioria dos serviços, esse limite raramente é atingido. No entanto, alguns serviços têm diversos parâmetros que podem resultar em URLs longos.