Práticas recomendadas para usar a API Street View Static

Uma coleção de interfaces HTTP, as APIs da Web estáticas da Plataforma Google Maps geram imagens para incorporação direta na sua página da Web.

Os serviços da Web da Plataforma Google Maps são um conjunto de interfaces HTTP que fornecem dados geográficos para seus aplicativos de mapas.

Este guia descreve algumas práticas comuns úteis para configurar solicitações de imagem e serviços da Web e processar respostas de serviços. Para mais informações sobre a API Street View Static, consulte o guia para desenvolvedores.

A API Street View Static funciona como uma API estática da Web, enquanto o serviço de metadados funciona como um serviço da Web. Para mais informações sobre o serviço de metadados, consulte Metadados de imagens do Street View.

O que é uma API Static Web?

Com as APIs estáticas da Web da Plataforma Google Maps, é possível incorporar uma imagem do Google Maps à sua página da Web sem precisar de JavaScript ou carregamento dinâmico de páginas. As APIs da Web estáticas criam uma imagem com base em parâmetros de URL enviados usando uma solicitação HTTPS padrão.

Uma solicitação típica da API Street View Static tem o seguinte formato:

  https://www.googleapis.com/streetview/z/x/y?parameters

O que é um serviço da Web?

Os serviços da Web da Plataforma Google Maps são uma interface para solicitar dados da API Maps de serviços externos e usar esses dados nos seus aplicativos do Maps. Esses serviços foram criados para serem usados com um mapa, de acordo com as Restrições de licença nos Termos de Serviço da Plataforma Google Maps.

Os serviços da Web das APIs do Google Maps usam solicitações HTTP ou HTTPS para URLs específicos, transmitindo parâmetros de URL ou dados POST no formato JSON como argumentos para os serviços. Em geral, esses serviços retornam dados no corpo da resposta como JSON para análise ou processamento pelo seu aplicativo.

Uma solicitação de metadados da API Street View Static tem o seguinte formato:

https://maps.googleapis.com/maps/api/streetview/parameters

Acesso a SSL e 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 sensíveis 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 converter 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:

Ao criar um URL válido, você precisa garantir que ele contenha apenas os caracteres mostrados na tabela. 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:

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 16.384 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 de caracteres raramente é alcançado. No entanto, alguns serviços têm diversos parâmetros que podem resultar em URLs longos.

Uso adequado das APIs do Google

Clientes de API mal projetados podem colocar cargas pesadas na Internet e nos servidores. Esta seção contém práticas recomendadas para clientes de API. Seguir essas práticas recomendadas pode ajudar a evitar que seu aplicativo seja bloqueado por abuso inadvertido das APIs.

Espera exponencial

Em casos raros, algo pode dar errado com sua solicitação. Você pode receber um código de resposta HTTP 4xx ou 5xx, ou a conexão TCP pode falhar em algum lugar entre seu cliente e o servidor do Google. Muitas vezes, vale a pena tentar de novo, porque a solicitação de acompanhamento pode ser concluída quando a original falhou. No entanto, é importante não fazer solicitações repetidas aos servidores do Google. Esse comportamento em loop pode sobrecarregar a rede entre seu cliente e o Google, causando problemas para muitas partes.

Uma melhor abordagem é tentar novamente com intervalos maiores entre as tentativas. O atraso geralmente aumenta por um fator multiplicativo a cada tentativa, uma abordagem conhecida como espera exponencial.

Por exemplo, considere um aplicativo que faz esta solicitação para a API Time Zone:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

O exemplo em Python a seguir mostra como fazer a solicitação com espera exponencial:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined in the following code isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If the request didn't produce an IOError, parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors can't be fixed by a retry, such as
                # INVALID_REQUEST or ZERO_RESULTS. Don't retry these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay on each retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

Verifique se não há um código de nova tentativa mais alto na cadeia de chamadas do aplicativo que leva a solicitações repetidas em rápida sucessão.

Solicitações sincronizadas

Um grande número de solicitações sincronizadas para as APIs do Google pode parecer um ataque distribuído de negação de serviço (DDoS) à infraestrutura do Google e ser tratado de acordo. Para evitar esse problema, verifique se as solicitações de API não estão sincronizadas entre os clientes.

Por exemplo, considere um aplicativo que mostra a hora no fuso horário atual. Esse aplicativo provavelmente define um alarme no sistema operacional do cliente para ativá-lo no início do minuto e atualizar a hora mostrada. Não faça chamadas de API no aplicativo como parte do processamento associado a esse alarme.

Fazer chamadas de API em resposta a um alarme fixo é ruim porque resulta na sincronização das chamadas com o início do minuto, mesmo entre diferentes dispositivos, em vez de serem distribuídas uniformemente ao longo do tempo. Um aplicativo mal projetado que faz isso gera um pico de tráfego 60 vezes maior que os níveis normais no início de cada minuto.

Em vez disso, você pode projetar o aplicativo para ter um segundo alarme definido para um horário escolhido aleatoriamente. Quando esse segundo alarme é acionado, o aplicativo chama as APIs necessárias e armazena os resultados. Quando o aplicativo atualiza a tela no início do minuto, ele usa resultados armazenados anteriormente em vez de chamar a API novamente. Com essa abordagem, as chamadas de API são distribuídas de maneira uniforme ao longo do tempo. Além disso, as chamadas de API não atrasam a renderização quando a tela é atualizada.

Além do início do minuto, não segmentar outros horários comuns de sincronização, como o início de uma hora e o início de cada dia à meia-noite.

Como processar respostas

Como o formato exato das respostas individuais a uma solicitação de serviço da Web não é garantido (alguns elementos podem estar faltando ou em vários locais), não suponha que o formato retornado para uma determinada resposta seja o mesmo para consultas diferentes. Em vez disso, processe a resposta e selecione os valores adequados usando expressões.

Esta seção discute como extrair esses valores dinamicamente das respostas do serviço da Web.

Os serviços da Web do Google Maps fornecem respostas compreensíveis, mas não fáceis de usar. Ao fazer uma consulta, em vez de mostrar um conjunto de dados, você provavelmente quer extrair alguns valores específicos. Em geral, analise as respostas do serviço da Web e extraia apenas os valores que interessam.

O esquema de análise usado depende de você estar retornando a saída em JSON. As respostas JSON, já na forma de objetos JavaScript, podem ser processadas no próprio JavaScript no cliente.