API de Elevation: Cómo obtener una clave de API

Nota: El plan Premium de Google Maps Platform ya no está disponible para registros o clientes nuevos.

Cómo elegir un método de autenticación

Para usar Google Maps Platform, debes autenticar las solicitudes con una clave de API o un ID de cliente y una firma digital.

El método de autenticación que puedes elegir depende de tu licencia:

  • Los clientes del plan Premium pueden usar una clave de API o un ID de cliente y una firma digital.
  • Los clientes con una licencia anterior deben usar un ID de cliente y una firma digital.

Cuando debas decidir el método de autenticación que utilizarás, ten en cuenta lo siguiente:

  • Autenticación con una clave de API (plan Premium)
    Si usas una clave de API para autenticar tu solicitud, puedes hacer lo siguiente:
    • Administrar todas tus API en la página API de Google Cloud Console
    • Acceder a los datos de uso en tiempo real y a 30 días de datos de uso históricos en la página API de Cloud Console
    • Agregar el parámetro channel a las solicitudes para poder ver informes de uso más detallados
    • Consultar los informes de uso con más de 30 días de datos en Google Cloud Console
  • Autenticación con un ID de cliente y una firma digital (plan Premium o licencia anterior)
    Si usas tu ID de cliente y tu firma digital para autenticar la solicitud, puedes hacer lo siguiente:
    • Agregar el parámetro channel a las solicitudes para poder ver informes de uso más detallados
    • Consultar los informes de uso con más de 30 días de datos en Cloud Console
    • Usar las herramientas de Maps Analytics para la API de Maps JavaScript

Obtén más información sobre los informes disponibles para los clientes del plan Premium.

Autenticación con una clave de API

Cómo obtener la clave de API

La clave de API es un identificador único que se utiliza para autenticar solicitudes asociadas con tu proyecto con fines de uso y facturación.

Para obtener una clave de API, haz lo siguiente:

  1. En Cloud Console, en la página del selector de proyectos, selecciona o crea un proyecto de Google Cloud para el que desees agregar una clave de API.

    Ir a la página del selector de proyectos

    Nota: Para tener acceso completo a las funciones de su plan, los clientes premium deben usar el proyecto asociado con su cuenta premium. Cuando compraste tu licencia, recibiste el nombre de tu elemento premium en el siguiente formato: gme-[company] > proj-[number] ([type]). Para asegurarte de utilizar el proyecto correcto, accede a la consola como propietario mediante console.cloud.google.com/project/number (reemplaza number por tu número de proyecto). Puedes encontrar el propietario del proyecto en tu carta de bienvenida.

  2. Ve a la página Google Maps Platform > Credenciales.

    Ir a la página Credenciales

  3. En la página Credenciales, haz clic en Crear credenciales > Clave de API.
    El diálogo Se creó la clave de API mostrará la clave de API que acabas de crear.
  4. Haz clic en Cerrar.
    La nueva clave de API aparecerá en la página Credenciales debajo de Claves de API.
    (Recuerda restringir la clave de API antes de utilizarla en producción).

Cómo agregar la clave de API a tu solicitud

Debes incluir una clave de API con cada solicitud de Google Maps Platform. En el siguiente ejemplo, reemplaza YOUR_API_KEY por tu clave de API.

https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034&key=YOUR_API_KEY

HTTPS es obligatorio para las solicitudes que usan una clave de API y se recomienda para las que usan un ID de cliente. También es obligatorio para las aplicaciones que incluyen datos sensibles de los usuarios (como su ubicación) en las solicitudes.

Cómo restringir las claves de API

La restricción de las claves de API agrega seguridad a tu aplicación, ya que garantiza que solo se realicen solicitudes autorizadas con tu clave de API. Te recomendamos enfáticamente que sigas las instrucciones si deseas configurar restricciones para tus claves de API. Para obtener más información, consulta Prácticas recomendadas sobre las claves de API.

Para restringir una clave de API, sigue estos pasos:

  1. Ve a la página Google Maps Platform > Credenciales.

    Ir a la página Credenciales

  2. Selecciona la clave de API para la que deseas establecer una restricción. Aparecerá la página de propiedades de la clave de API.
  3. En Restricciones de clave, establece las siguientes restricciones:
    • Restricciones de aplicaciones:
      1. Para aceptar las solicitudes de la lista de direcciones IP de servidor web que proporcionas, selecciona Direcciones IP (servidores web, trabajos cron, etc.) en la lista de Restricciones de aplicaciones.
      2. Especifica una dirección IPv4 o IPv6, o una subred con notación CIDR (p. ej., 192.168.0.0/22). Si necesitas ingresar otra entrada, aparecerá un cuadro nuevo cuando termines de agregar la entrada anterior.
    • Restricciones de API:
      1. Haz clic en Restringir clave.
      2. Selecciona Google Maps Platform en el menú desplegable Seleccionar API. Si Google Maps Platform no aparece en la lista, debes habilitarlo.
  4. Para finalizar los cambios, haz clic en Guardar.

Autenticación con un ID de cliente y una firma digital

Cuando compres tu licencia del plan Premium de Google Maps Platform, Google te enviará un correo electrónico de bienvenida con tu ID de cliente y tu clave criptográfica privada (que puedes usar para generar una firma digital única).

En el siguiente código de muestra, se ven los parámetros client y signature a los que debes pasarles tu ID de cliente y tu firma digital única.

    https://maps.googleapis.com/maps/api/elevation/json
      ?locations=39.7391536,-104.9847034
      &client=YOUR_CLIENT_ID
      &signature=SIGNATURE
  • Reemplaza YOUR_CLIENT_ID por el ID de cliente que aparece en tu correo electrónico de bienvenida.

    Tu ID de cliente comienza con los caracteres gme-.

  • Reemplaza SIGNATURE por tu firma digital única (consulta Cómo generar una firma digital).

Notas:

  • Como opción, puedes usar el parámetro channel cuando autentiques Google Maps Platform mediante un ID de cliente y una firma digital para recibir informes de uso detallados. Consulta la descripción general sobre los informes del plan Premium para obtener más información.
  • Si antes usabas una clave de API para la autenticación, pero ahora deseas usar un ID de cliente, debes quitar el parámetro key de tus solicitudes. Los servicios web de las API de Google Maps denegarán las solicitudes que se realicen con un ID de cliente y una clave de API.

Cómo generar una firma digital

Las solicitudes a la API de Elevation que realicen los clientes del plan Premium de Google Maps Platform requieren de una firma (signature) digital que puedes generar mediante la clave criptográfica privada que te proporcionamos en tu correo electrónico de bienvenida (consulta Más información sobre tu clave criptográfica privada).

Sigue los pasos que se indican a continuación a fin de generar una firma digital para tu solicitud.

  1. Crea la URL de la solicitud sin la firma y asegúrate de incluir el parámetro client. Ten en cuenta que cualquier carácter no estándar deberá estar codificado en formato URL:

    https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034&client=clientID

    Nota: Todos los servicios de Google deben contar con codificación de caracteres UTF-8 (que implícitamente incluye ASCII). Si tus aplicaciones funcionan con otros grupos de caracteres, asegúrate de que creen URL con caracteres UTF-8 y que los codifiquen en formato URL correctamente.

  2. Extrae la parte del dominio de la solicitud y deja solo la ruta de acceso y la consulta:

    /maps/api/elevation/json?locations=39.7391536,-104.9847034&client=clientID

  3. Recupera tu clave privada, que está codificada en un sistema Base64 modificado para URL, y firma la URL anterior con el algoritmo HMAC-SHA1. Es posible que debas decodificar esta clave a su formato binario original. Ten en cuenta que, en la mayoría de las bibliotecas criptográficas, la firma resultante estará en formato binario.

    Nota: El sistema Base64 modificado para URL reemplaza los caracteres + y / del sistema Base64 estándar por - y _ respectivamente, de modo que ya no es necesario codificar estas firmas de Base64 en formato URL.

  4. Codifica la firma binaria resultante mediante el sistema Base64 modificado para URL a fin de convertirla en un elemento que se pueda pasar dentro de una URL.

  5. Adjunta esta firma a la URL dentro de un parámetro signature:

    https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034&client=clientID&signature=base64signature

Notas:

  • La firma única permite a nuestros servidores verificar que los sitios que generen solicitudes con tu ID de cliente estén autorizados para hacerlo. La firma también es exclusiva de cada URL, lo que garantiza que las solicitudes que usen tu ID de cliente no se puedan modificar sin generar una firma nueva.
  • Si intentas acceder a la API de Elevation con una firma no válida, se mostrará el error HTTP 403 (Prohibido). A medida que conviertas tus aplicaciones para que usen firmas de URL, prueba las firmas a fin de asegurarte de que inicien una solicitud válida. Primero debes probar si la URL original es válida y si se generan las firmas correctas.
  • Si deseas ver muestras que ilustren diferentes maneras de implementar la firma de URL con código del servidor, consulta Código de muestra para la firma de URL.

Para firmar una URL ahora, ingresa tu URL y tu secreto de firma de URL a continuación. La URL debe tener el formato descrito en el paso 1 anterior y debe estar codificada en formato URL.

Código de muestra para la firma de URL

En las siguientes secciones, se muestra cómo implementar una firma de URL con un código del servidor. Siempre debes firmar las URL en el servidor para evitar exponer tu clave criptográfica a los usuarios.

Python

El siguiente ejemplo usa bibliotecas Python estándares para firmar una URL (descarga el código).

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

import hashlib
import hmac
import base64
import urllib.parse as 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, str.encode(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.decode()

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

Java

El siguiente ejemplo usa la clase java.util.Base64 disponible desde JDK 1.8. Es posible que las versiones anteriores necesiten usar Apache Commons o similares (descarga el 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;
  }
}

Node.js

El siguiente ejemplo usa módulos de Node nativos para firmar una URL (descarga el código).

'use strict'

const crypto = require('crypto');
const url = require('url');

/**
 * Convert from 'web safe' base64 to true base64.
 *
 * @param  {string} safeEncodedString The code you want to translate
 *                                    from a web safe form.
 * @return {string}
 */
function removeWebSafe(safeEncodedString) {
  return safeEncodedString.replace(/-/g, '+').replace(/_/g, '/');
}

/**
 * Convert from true base64 to 'web safe' base64
 *
 * @param  {string} encodedString The code you want to translate to a
 *                                web safe form.
 * @return {string}
 */
function makeWebSafe(encodedString) {
  return encodedString.replace(/\+/g, '-').replace(/\//g, '_');
}

/**
 * Takes a base64 code and decodes it.
 *
 * @param  {string} code The encoded data.
 * @return {string}
 */
function decodeBase64Hash(code) {
  // "new Buffer(...)" is deprecated. Use Buffer.from if it exists.
  return Buffer.from ? Buffer.from(code, 'base64') : new Buffer(code, 'base64');
}

/**
 * Takes a key and signs the data with it.
 *
 * @param  {string} key  Your unique secret key.
 * @param  {string} data The url to sign.
 * @return {string}
 */
function encodeBase64Hash(key, data) {
  return crypto.createHmac('sha1', key).update(data).digest('base64');
}

/**
 * Sign a URL using a secret key.
 *
 * @param  {string} path   The url you want to sign.
 * @param  {string} secret Your unique secret key.
 * @return {string}
 */
function sign(path, secret) {
  const uri = url.parse(path);
  const safeSecret = decodeBase64Hash(removeWebSafe(secret));
  const hashedSignature = makeWebSafe(encodeBase64Hash(safeSecret, uri.path));
  return url.format(uri) + '&signature=' + hashedSignature;
}

C#

El siguiente ejemplo usa la biblioteca System.Security.Cryptography predeterminada para firmar una solicitud de URL. Ten en cuenta que debemos convertir la codificación Base64 predeterminada para implementar una versión compatible con URL (descarga el 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));
    }
  }
}

Si deseas realizar pruebas, puedes probar la URL y la clave privada que aparecen a continuación para verificar que generen la firma correcta. Ten en cuenta que esta clave privada solo sirve para realizar pruebas y no recibirá la validación de ninguno de los servicios de Google.

  • URL: https://maps.googleapis.com/maps/api/geocode/json?address=New+York&client=clientID
  • Clave privada: vNIXE0xscrmjlyV-12Nj_BvUPaw=
  • Parte de la URL que se debe firmar: /maps/api/geocode/json?address=New+York&client=clientID
  • Firma: chaRF2hTJKOScPr-RQCEhZbSzIE=
  • URL firmada completa: https://maps.googleapis.com/maps/api/geocode/json?address=New+York&client=clientID&signature=chaRF2hTJKOScPr-RQCEhZbSzIE=

Ejemplos en otros lenguajes

Encontrarás ejemplos que incluyen más lenguajes en el proyecto de firmas de URL.

Más información sobre tu clave criptográfica privada

Tu clave criptográfica privada para firmas de URL se generará con tu ID de cliente y es una "clave secreta compartida" entre tú y Google. Esta clave para firmas es solo tuya y exclusiva de tu ID de cliente. Por esta razón, debes asegurarte de que esté protegida. Esta clave no debe pasarse en ninguna solicitud, almacenarse en sitios web ni publicarse en foros públicos. Si alguien la obtiene, podría realizar solicitudes falsas con tu identidad.

Nota: Esta clave criptográfica privada para firmas no es igual a las claves de API que emite Google Cloud Console.

Si perdiste tu clave criptográfica privada, accede a Cloud Console y haz clic en Maps: Administrar ID de cliente para recuperarla.

Cómo solucionar problemas de autenticación

Si tu solicitud no tiene el formato correcto o proporciona una firma no válida, Google Maps Platform muestra un error HTTP 403 (Forbidden).

Para solucionar problemas relacionados con URL individuales, puedes usar la herramienta URL Signing Debugger. Este depurador te permitirá validar rápidamente una URL y la firma que generó tu aplicación.

Como alternativa, si los clientes del plan premium desean solucionar problemas de URL individuales, pueden acceder a Cloud Console y seleccionar Recursos > Herramientas en línea del plan premium de Google Maps Platform > URL Signing Debugger para API de imagen y servicio web.