Pronto!

Para começar a desenvolver, acesse nossa documentação do desenvolvedor.

Ativar a Google Maps Time Zone API

Para começar, orientaremos você pelo Console do Desenvolvedor do Google para realizar algumas atividades:

  1. Criar ou selecionar um projeto
  2. Ativar a Google Maps Time Zone API
  3. Criar chaves apropriadas
Continuar

Obter uma chave/autenticação

Todos os aplicativos Google Maps Time Zone API exigem autenticação.

  • Usuários da API padrão: Se estiver usando a API no plano padrão, você deve usar uma chave de API ativa no projeto que você escolher. Veja mais sobre chaves de API para a API padrão.

    Incluir uma chave na sua solicitação permite monitorar o uso de API do seu aplicativo no Google API Console, acessar uma boa cota diária gratuita e garante que a Google possa contatar você para falar sobre o seu aplicativo, se necessário.

  • Usuários do Premium Plan: Se estiver usando a API no Google Maps APIs Premium Plan, você tem duas opções de autenticação:
    • Usar uma chave de API configurada no projeto Google Maps APIs Premium Plan criado quando você comprou o Premium Plan.
        ou
    • Incluir um ID de cliente e uma assinatura digital em vez da chave de API.

    Veja a seção Google Maps APIs Premium Plan abaixo para saber mais sobre como escolher o melhor método de autenticação.

Autenticação da API padrão — chaves de API

Obter uma chave de API

Para começar a usar o Google Maps Time Zone API, clique no botão abaixo para ativá-lo automaticamente.

Obter uma chave

Como alternativa, siga as etapas a seguir para obter uma chave de API:

  1. Acesse o Google API Console.
  2. Crie ou selecione um projeto.
  3. Clique em Continue para ativar a API.
  4. Na página Credentials, obtenha uma chave de API (e defina as restrições dela).
    Observação: Se você já tem uma chave de API irrestrita ou uma com restrições a servidor, pode usá-la.
  5. Para evitar o roubo de cota, proteja sua chave de API seguindo estas práticas recomendadas.
  6. (Opcional) Ative a cobrança. Consulte Limites de uso para saber mais.


Também é possível procurar uma chave existente no Google API Console.

Para saber mais sobre como usar o Google API Console, consulte a Ajuda do API Console.

Tipos de restrição da chave de API

As Google Maps APIs estão disponíveis para aplicativos Android e iOS, navegadores e via serviços Web HTTP. APIs de qualquer plataforma podem usar uma chave de API genérica (irrestrita). Você tem a opção de adicionar uma restrição (por exemplo, endereço IP) à chave de API. Depois de aplicar a restrição, a chave só funcionará em plataformas compatíveis com esse tipo de restrição. Saiba mais sobre chaves e credenciais.

Especificar uma chave na solicitação

Para especificar uma chave em sua solicitação, inclua-a como o valor de um parâmetro key.

Por exemplo:

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

Autenticação para clientes do Google Maps APIs Premium Plan

As informações desta seção se aplicam somente ao novo Google Maps APIs Premium Plan, que foi disponibilizado em 6 de janeiro de 2016.

Tem uma licença antiga do Maps APIs for Work ou do Maps API for Business? Leia nosso guia de licenças do Maps APIs for Work. Para descobrir se você tem uma licença antiga: No Google Cloud Support Portal, clique em Maps: Usage Report, à esquerda. Se o ID na parte superior do relatório está no formato a seguir, você tem o novo Premium Plan:
gme-[company] & proj-[number] ([type])
Se não, você tem uma licença antiga.

Ao usar o Google Maps Time Zone API com uma licença do Google Maps APIs Premium Plan, você precisa autenticar o aplicativo com uma chave de API ou seu ID de cliente. Além disso, as solicitações que usam ID de cliente também exigem uma assinatura digital. Observação: Se você tem uma licença anterior do Maps API for Business, deve usar um ID de cliente, não uma chave de API.

Para escolher o método de autenticação, analise o seguinte:

  • Chave de API (disponível para clientes Google Maps APIs Premium Plan, mas não para detentores de uma licença anterior do Maps API for Business) — ao usar uma chave de API para autenticar solicitações, você pode:
  • ID de cliente — ao usar seu ID de cliente (em vez de uma chave de API) para autenticar solicitações, você pode:
    • Adicionar o parâmetro channel a solicitações para poder acessar relatórios de uso mais detalhados
    • Ver relatórios de uso com mais de 30 dias de dados no Google Cloud Support Portal
    • Usar a ferramenta Maps Analytics para a Maps JavaScript API

Obtenha mais informações sobre relatórios disponíveis para clientes do Premium Plan.

Usar uma chave de API

Para autenticar a API Time Zone usando uma chave de API, clique no botão abaixo para seguir para o Google API Console e acessar um guia do processo.

Importante: No menu suspenso Project, selecione o projeto criado quando você comprou o Premium Plan. O nome do projeto começa com Google Maps APIs for Business or Google Maps for Work or Google Maps.*

Obter uma chave

Como alternativa, siga as etapas a seguir para obter uma chave de API:

  1. Acesse o Google API Console.
  2. No menu suspenso Project, selecione o projeto do Google Maps Premium.*
  3. Clique em Continue.
  4. Na página Credentials, obtenha uma chave de API (e defina as restrições dela).
    Observação: Se você já tem uma chave de API irrestrita ou uma com restrições a servidor, pode usá-la.
  5. Para evitar o roubo de cota, proteja sua chave de API seguindo estas práticas recomendadas.

* Observação: no menu suspenso Project, você deve selecionar o projeto criado quando comprou o Premium Plan. O nome do projeto é iniciado por Google Maps APIs for Business or Google Maps for Work or Google Maps. Importante: Se você tem uma licença anterior do Maps API for Business, deve usar um ID de cliente, não uma chave de API.


Também é possível procurar uma chave existente no Google API Console.

Para saber mais sobre como usar o Google API Console, consulte a Ajuda do API Console.

Especificar uma chave na solicitação

Para especificar uma chave em sua solicitação, inclua-a como o valor de um parâmetro key.

Por exemplo:

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

Usar um ID de cliente

Para autenticar a API Time Zone usando um ID de cliente (em vez da chave de API), dois parâmetros de autenticação são obrigatórios: ID de cliente e assinatura digital única.

Se você usava uma chave de API para autenticação e está trocando por um ID de cliente, remova o parâmetro key das suas solicitações. Os Google Maps APIs Web Services não aceitarão solicitações feitas que tenham um ID de cliente e uma chave de API.

Seu ID de cliente e sua assinatura

Depois de comprar a licença do Google Maps APIs Premium Plan, você receberá um e-mail de boas-vindas do Google que contém seu ID de cliente e sua chave criptográfica privada.

  • Seu ID de cliente é usado para acessar os recursos especiais do Google Maps APIs Premium Plan. Todos os IDs de cliente começam com um prefixo gme-. Passe o seu ID de cliente como o valor do parâmetro client.

  • Uma assinatura digital única é gerada usando a sua chave criptográfica privada. Passe essa assinatura como o valor do parâmetro signature. Veja abaixo mais informações sobre como gerar a assinatura, na seção sobre assinaturas digitais.

    https://maps.googleapis.com/maps/api/timezone/json
      ?location=39.6034810,-119.6822510
      &timestamp=1331161200
      &client=YOUR_CLIENT_ID
      &signature=SIGNATURE

Se você perdeu seu ID de cliente ou sua chave criptográfica privada, é possível recuperá-la acessando o Google Cloud Support Portal e clicando em Maps: Manage Client ID nos links à esquerda da tela.

Parâmetro opcional para relatórios

Ao usar um ID de cliente para autenticação de API, o parâmetro opcional a seguir fica disponível para uso:

Assinaturas digitais

As solicitações à Time Zone API pelos clientes do Google Maps APIs Premium Plan exigem uma assinatura digital, gerada por meio do uso da chave criptográfica privada fornecida a você pelo e-mail de boas-vindas.

O processo de assinatura combina um URL e a chave usando um algoritmo criptográfico. A assinatura única gerada permite que os nossos servidores verifiquem se os sites que geram solicitações usando seu ID de cliente têm autorização para fazê-lo. A assinatura também é exclusiva por URL, garantindo que as solicitações que usam seu ID de cliente não possam ser modificadas sem exigir a geração de uma nova assinatura.

Sua chave criptográfica privada

A chave criptográfica de assinatura de URL privada será emitida com seu ID de cliente e é uma “chave secreta compartilhada” entre você e a Google. Essa chave de assinatura é somente sua e é exclusiva para o seu ID de cliente. Por isso, mantenha-a confidencial. Essa chave não deve ser passada dentro de solicitações, armazenada em sites nem postada em fórum público. Qualquer pessoa que tiver em mãos essa chave de assinatura pode fazer solicitações usando a sua identidade.

Observação: Essa chave criptográfica de assinatura privada não é igual às chaves de API emitidas pelo Google API Console.

Caso tenha perdido sua chave criptográfica privada, acesse o Google Cloud Support Portal e clique em Maps: Manage Client ID para recuperá-la.

Gerar uma assinatura digital

Tentar acessar a API Time Zone com uma assinatura inválida resultará em um erro HTTP 403 (acesso negado). Ao converter aplicativos para usar a assinatura de URL, não deixe de testar as assinaturas para garantir que eles iniciem uma solicitação válida. Mas antes, você deve verificar se o URL original é válido e se você gerou as assinaturas corretas.

Siga estas etapas para criar uma assinatura digital para sua solicitação:

  1. Gere o URL da solicitação sem a assinatura, sem esquecer de incluir o parâmetro client. Observe que todo caractere não padrão precisará ser codificado para URL:

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

    Observação: todos os serviços do Google exigem a codificação de caracteres UTF-8 (que inclui ASCII implicitamente). Se seus aplicativos operarem usando outros conjuntos de caracteres, gere os URLs usando UTF-8 e codifique-os para URL.

  2. Remova a parte do domínio da solicitação, deixando apenas o caminho e a consulta:

    /maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&client=clientID

  3. Recupere sua chave privada, que é codificada em Base64 modificado para URLs, e assine o URL acima usando o algoritmo HMAC-SHA1. Pode ser necessário decodificar essa chave no formato binário original dela. Observe que, na maioria das bibliotecas criptográficas, a assinatura gerada estará em formato binário.

    Observação: a Base64 modificada para URLs substitui os caracteres + e / da Base64 padrão por - e _, respectivamente, para que essas assinaturas Base64 não precisem mais de codificação para URL.

  4. Codifique a assinatura binária resultante usando a Base64 modificada para URLs para convertê-la em algo que possa ser passado em um URL.

  5. Vincule essa assinatura ao URL dentro de um parâmetro signature:

    https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&client=clientID&signature=base64signature

Para ver exemplos de formas de se implementar assinatura de URL usando código no servidor, veja Exemplo de código para assinatura de URL.

Para assinar um URL agora, insira o URL e o segredo de assinatura de URL abaixo. O URL deve ter o formato descrito na etapa 1 acima e ser codificado para URL.

Exemplo de código para assinatura de URL

As seções a seguir mostram como implementar a assinatura de URL usando código de servidor. URLs devem ser sempre assinados no servidor para evitar a exposição da sua chave criptográfica para os usuários.

Python

O exemplo abaixo usa bibliotecas Python padrão para assinar um URL. (Faça o download do código.)

#!/usr/bin/python
# -*- coding: utf-8 -*-
""" Signs a URL using a URL signing secret """

import hashlib
import hmac
import base64
import urlparse

def sign_url(input_url=None, secret=None):
  """ Sign a request URL with a URL signing secret.

      Usage:
      from urlsigner import sign_url

      signed_url = sign_url(input_url=my_url, secret=SECRET)

      Args:
      input_url - The URL to sign
      secret    - Your URL signing secret

      Returns:
      The signed request URL
  """

  if not input_url or not secret:
    raise Exception("Both input_url and secret are required")

  url = urlparse.urlparse(input_url)

  # We only need to sign the path+query part of the string
  url_to_sign = url.path + "?" + url.query

  # Decode the private key into its binary format
  # We need to decode the URL-encoded private key
  decoded_key = base64.urlsafe_b64decode(secret)

  # Create a signature using the private key and the URL-encoded
  # string using HMAC SHA1. This signature will be binary.
  signature = hmac.new(decoded_key, url_to_sign, hashlib.sha1)

  # Encode the binary signature into base64 for use within a URL
  encoded_signature = base64.urlsafe_b64encode(signature.digest())

  original_url = url.scheme + "://" + url.netloc + url.path + "?" + url.query

  # Return signed URL
  return original_url + "&signature=" + encoded_signature

if __name__ == "__main__":
  input_url = raw_input("URL to Sign: ")
  secret = raw_input("URL signing secret: ")
  print "Signed URL: " + sign_url(input_url, secret)

Java

O exemplo abaixo usa a classe java.util.Base64 disponível desde o JDK 1.8. Versões mais antigas podem precisar usar o Apache Commons ou similar. (Faça o download do código.)

import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.net.URI;
import java.net.URISyntaxException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;  // JDK 1.8 only - older versions may need to use Apache Commons or similar.
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;

public class UrlSigner {

  // Note: Generally, you should store your private key someplace safe
  // and read them into your code

  private static String keyString = "YOUR_PRIVATE_KEY";
  
  // The URL shown in these examples is a static URL which should already
  // be URL-encoded. In practice, you will likely have code
  // which assembles your URL from user or web service input
  // and plugs those values into its parameters.
  private static String urlString = "YOUR_URL_TO_SIGN";

  // This variable stores the binary key, which is computed from the string (Base64) key
  private static byte[] key;
  
  public static void main(String[] args) throws IOException,
    InvalidKeyException, NoSuchAlgorithmException, URISyntaxException {
    
    BufferedReader input = new BufferedReader(new InputStreamReader(System.in));
    
    String inputUrl, inputKey = null;

    // For testing purposes, allow user input for the URL.
    // If no input is entered, use the static URL defined above.    
    System.out.println("Enter the URL (must be URL-encoded) to sign: ");
    inputUrl = input.readLine();
    if (inputUrl.equals("")) {
      inputUrl = urlString;
    }
    
    // Convert the string to a URL so we can parse it
    URL url = new URL(inputUrl);
 
    // For testing purposes, allow user input for the private key.
    // If no input is entered, use the static key defined above.   
    System.out.println("Enter the Private key to sign the URL: ");
    inputKey = input.readLine();
    if (inputKey.equals("")) {
      inputKey = keyString;
    }
    
    UrlSigner signer = new UrlSigner(inputKey);
    String request = signer.signRequest(url.getPath(),url.getQuery());
    
    System.out.println("Signed URL :" + url.getProtocol() + "://" + url.getHost() + request);
  }
  
  public UrlSigner(String keyString) throws IOException {
    // Convert the key from 'web safe' base 64 to binary
    keyString = keyString.replace('-', '+');
    keyString = keyString.replace('_', '/');
    System.out.println("Key: " + keyString);
    // Base64 is JDK 1.8 only - older versions may need to use Apache Commons or similar.
    this.key = Base64.getDecoder().decode(keyString);
  }

  public String signRequest(String path, String query) throws NoSuchAlgorithmException,
    InvalidKeyException, UnsupportedEncodingException, URISyntaxException {
    
    // Retrieve the proper URL components to sign
    String resource = path + '?' + query;
    
    // Get an HMAC-SHA1 signing key from the raw key bytes
    SecretKeySpec sha1Key = new SecretKeySpec(key, "HmacSHA1");

    // Get an HMAC-SHA1 Mac instance and initialize it with the HMAC-SHA1 key
    Mac mac = Mac.getInstance("HmacSHA1");
    mac.init(sha1Key);

    // compute the binary signature for the request
    byte[] sigBytes = mac.doFinal(resource.getBytes());

    // base 64 encode the binary signature
    // Base64 is JDK 1.8 only - older versions may need to use Apache Commons or similar.
    String signature = Base64.getEncoder().encodeToString(sigBytes);
    
    // convert the signature to 'web safe' base 64
    signature = signature.replace('+', '-');
    signature = signature.replace('/', '_');
    
    return resource + "&signature=" + signature;
  }
}

C#

O exemplo abaixo usa a biblioteca System.Security.Cryptography padrão para assinar uma solicitação de URL. Observe que é preciso converter a codificação Base64 padrão para implementar uma versão compatível com URL. (Faça o download do código.)

using System;
using System.Collections.Generic;
using System.Security.Cryptography;
using System.Text;
using System.Text.RegularExpressions;
using System.Web;

namespace SignUrl {

  public struct GoogleSignedUrl {

    public static string Sign(string url, string keyString) {
      ASCIIEncoding encoding = new ASCIIEncoding();

      // converting key to bytes will throw an exception, need to replace '-' and '_' characters first.
      string usablePrivateKey = keyString.Replace("-", "+").Replace("_", "/");
      byte[] privateKeyBytes = Convert.FromBase64String(usablePrivateKey);

      Uri uri = new Uri(url);
      byte[] encodedPathAndQueryBytes = encoding.GetBytes(uri.LocalPath + uri.Query);

      // compute the hash
      HMACSHA1 algorithm = new HMACSHA1(privateKeyBytes);
      byte[] hash = algorithm.ComputeHash(encodedPathAndQueryBytes);

      // convert the bytes to string and make url-safe by replacing '+' and '/' characters
      string signature = Convert.ToBase64String(hash).Replace("+", "-").Replace("/", "_");
            
      // Add the signature to the existing URI.
      return uri.Scheme+"://"+uri.Host+uri.LocalPath + uri.Query +"&signature=" + signature;
    }
  }

  class Program {

    static void Main() {
    
      // Note: Generally, you should store your private key someplace safe
      // and read them into your code

      const string keyString = "YOUR_PRIVATE_KEY";
  
      // The URL shown in these examples is a static URL which should already
      // be URL-encoded. In practice, you will likely have code
      // which assembles your URL from user or web service input
      // and plugs those values into its parameters.
      const  string urlString = "YOUR_URL_TO_SIGN";
      
      string inputUrl = null;
      string inputKey = null;
    
      Console.WriteLine("Enter the URL (must be URL-encoded) to sign: ");
      inputUrl = Console.ReadLine();
      if (inputUrl.Length == 0) {
        inputUrl = urlString;
      }     
    
      Console.WriteLine("Enter the Private key to sign the URL: ");
      inputKey = Console.ReadLine();
      if (inputKey.Length == 0) {
        inputKey = keyString;
      }
      
      Console.WriteLine(GoogleSignedUrl.Sign(inputUrl,inputKey));
    }
  }
}

Para fins de teste, você pode testar o URL e a chave privada a seguir para ver se a assinatura correta é gerada. Observe que esta chave privada serve exclusivamente para testes e não será validada por nenhum serviço Google.

  • URL: https://maps.googleapis.com/maps/api/geocode/json?address=New+York&client=clientID
  • Chave privada: vNIXE0xscrmjlyV-12Nj_BvUPaw=
  • Parte do URL a assinar: /maps/api/geocode/json?address=New+York&client=clientID
  • Assinatura: chaRF2hTJKOScPr-RQCEhZbSzIE=
  • URL totalmente assinado: https://maps.googleapis.com/maps/api/geocode/json?address=New+York&client=clientID&signature=chaRF2hTJKOScPr-RQCEhZbSzIE=

Exemplos em outras linguagens

Há exemplos que tratam de outras linguagens no projeto url-signing.

Solucionar problemas de autenticação

Se sua solicitação for inválida ou fornecer uma assinatura inválida, o Google Maps Time Zone API retornará um erro HTTP 403 (Forbidden).

Para solucionar os problemas de URLs individuais, use o depurador de assinaturas de URL. Ele permite que você valide rapidamente o URL e a assinatura gerada por seu aplicativo.

Como alternativa, os clientes do Google Maps APIs Premium Plan podem resolver problemas de URLs específicos acessando o Google Cloud Support Portal e selecionando Resources > Google Maps APIs Premium Plan online tools > URL Signing Debugger for Web Service and Image APIs.

Enviar comentários sobre…

Google Maps Time Zone API
Google Maps Time Zone API
Precisa de ajuda? Acesse nossa página de suporte.