Práticas recomendadas para usar os serviços da Web da API Geolocation

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

Este guia descreve algumas práticas comuns úteis para configurar sua serviço da Web solicitações e processamento de respostas de serviço. Consulte o Guia para desenvolvedores para conferir a documentação completa da API de geolocalização.

O que é um serviço 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 os dados nos aplicativos do Google Maps. Esses serviços são projetada para ser usada em conjunto com um mapa, conforme a Restrições da licença nos Termos de Serviço da Plataforma Google Maps.

Os serviços Web das APIs do Google Maps usam solicitações HTTP(S) para URLs específicos, transmitindo parâmetros de URL e/ou Dados POST no formato JSON como argumentos para os serviços. Geralmente, esses serviços retornam dados na corpo da resposta como JSON para análise e/ou processamento pelo aplicativo.

Solicitações de geolocalização são enviadas usando POST para o seguinte URL:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

Observação: todos os aplicativos da API Geolocation exigem autenticação. Saiba mais 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 informações de dados. As solicitações feitas por HTTP que contêm dados sensíveis podem ser rejeitadas.

Uso adequado das Google APIs

Clientes de API mal projetados podem colocar mais carga do que o necessário na Internet e nos servidores do Google. Esta seção contém algumas das melhores práticas para cliente das APIs. Seguindo estas práticas recomendadas podem ajudar você a evitar que seu aplicativo seja bloqueado por abuso acidental de as APIs.

Retirada exponencial

Em casos raros, algo pode dar errado ao atender à sua solicitação. é possível que você receba uma solicitação HTTP 4XX ou 5XX ou a conexão TCP pode falhar em algum ponto entre o cliente e a rede do servidor. Muitas vezes, vale a pena tentar a solicitação novamente a solicitação de acompanhamento poderá ser bem-sucedida quando o original falhar. No entanto, é importante não simplesmente repetidamente fazendo solicitações aos servidores do Google. Esse comportamento de loop pode sobrecarregar entre o cliente e o Google, o que causa problemas para muitas partes.

Uma melhor abordagem é tentar novamente com intervalos maiores entre as tentativas. Normalmente, o o atraso é aumentado por um fator multiplicativo a cada tentativa, uma abordagem conhecida como Espera exponencial.

Por exemplo, considere um aplicativo que quer fazer a solicitação 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 de Python a seguir mostra como fazer a solicitação com retirada exponencial:

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

# The maps_key defined below 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 we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying 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 each time we retry.


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

Você também deve tomar cuidado para que não haja um código de repetição mais alto na chamada do aplicativo que resulta em solicitações repetidas em rápida sucessão.

Solicitações sincronizadas

Um grande número de solicitações sincronizadas para as APIs do Google podem parecer de negação de serviço (DDoS) na infraestrutura do Google e deve ser tratado de forma adequada. Para evite isso, verifique se as solicitações da API não estão entre clientes.

Por exemplo, considere um aplicativo que exibe a hora do fuso horário atual. Este aplicativo provavelmente definirá um alarme no sistema operacional do cliente, despertando-o às início do minuto para que o horário exibido possa ser atualizado. O aplicativo precisa não fará chamadas de API como parte do processamento associado a esse alarme.

Fazer chamadas de API em resposta a um alarme fixo é ruim, porque faz com que essas chamadas sejam sincronizados com o início do minuto, mesmo entre dispositivos diferentes, em vez de serem distribuídos de maneira uniforme ao longo do tempo. Um aplicativo mal projetado que faça isso produzirá um pico de tráfego 60 vezes maior do que o nível normal no início de cada minuto.

Em vez disso, um bom possível design é ter um segundo alarme definido a um horário escolhido aleatoriamente. Quando esse segundo alarme dispara, o aplicativo chama as APIs de que precisa e armazena a resultados. Quando o aplicativo deseja atualizar sua tela no início do minuto, ele usa resultados já armazenados em vez de chamar a API novamente. Com essa abordagem, as chamadas de API são distribuídos uniformemente com o tempo. Além disso, as chamadas de API não atrasam a renderização quando a tela que estão sendo atualizados.

Além do início do minuto, há outros momentos de sincronização comuns com os quais é preciso ter cuidado não segmentar são no início de uma hora e o início de cada dia à meia-noite.

Como processar respostas

Observação: como o formato exato de respostas individuais com um a solicitação de serviço da Web não for garantida (alguns elementos podem estar ausentes ou em diversos locais), você nunca deve presumir que o formato retornado para qualquer resposta será o mesmo para consultas diferentes. Em vez disso, você deve processar a resposta e selecionar valores apropriados usando expressions.

Esta seção discute como extrair esses valores das respostas dos serviços web de forma dinâmica.

Os serviços Web do Google Maps fornecem respostas que são fáceis de entender, mas não exatamente fáceis de usar. Ao realizar uma consulta, em vez de exibir um conjunto de dados, você provavelmente quer extrair algumas valores. Geralmente, convém analisar respostas da Web serviço e extrair apenas os valores que lhe interessam.

O esquema de análise usado depende se você está retornando em JSON. respostas JSON, já na forma de Objetos JavaScript, podem ser processados no próprio JavaScript no cliente.