Directions API – API-Schlüssel abrufen

Hinweis: Du kannst dich nicht mehr für die Google Maps Platform-Premiumoption registrieren. Auch für Neukunden ist sie nicht mehr verfügbar.

Authentifizierungsmethode auswählen

Wenn du die Google Maps Platform verwenden möchtest, musst du Anfragen mit einem API-Schlüssel oder einer Client-ID und einer digitalen Signatur authentifizieren.

Die Authentifizierungsmethode, die du auswählen kannst, richtet sich nach deiner Lizenz:

  • Kunden mit der Premiumoption können einen API-Schlüssel oder eine Client-ID und eine digitale Signatur verwenden.
  • Kunden mit einer älteren Lizenz müssen eine Client-ID und digitale Signatur verwenden.

Berücksichtige bitte Folgendes, wenn du entscheidest, welche Authentifizierungsmethode du verwenden möchtest:

  • Authentifizierung mit einem API-Schlüssel (Premiumoption)
    Wenn du einen API-Schlüssel zum Authentifizieren von Anfragen verwendest, kannst du…
    • …alle APIs in der Google Cloud Console auf der Seite „APIs“ verwalten,
    • …in der Cloud Console auf der Seite „APIs“ auf Echtzeitnutzungsdaten und Daten zum Nutzungsverlauf für bis zu 30 Tage zugreifen,
    • …den Parameter channel zu Anfragen hinzufügen, um ausführlichere Nutzungsberichte zu sehen,
    • …Nutzungsberichte mit Daten für mehr als 30 Tage in der Google Cloud Console aufrufen.
  • Authentifizierung mit einer Client-ID und einer digitalen Signatur (Premiumoption oder ältere Lizenz)
    Wenn du deine Client-ID und digitale Signatur zum Authentifizieren von Anfragen verwendest, kannst du…
    • …den Parameter channel zu Anfragen hinzufügen, um ausführlichere Nutzungsberichte zu sehen,
    • …Nutzungsberichte mit Daten für mehr als 30 Tage in der Google Cloud Console aufrufen
    • …Maps Analytics-Tools für die Maps JavaScript API verwenden.

Weitere Informationen zu Berichten, die für Nutzer mit der Premiumoption verfügbar sind

Authentifizierung mit einem API-Schlüssel

API-Schlüssel abrufen

Der API-Schlüssel ist eine eindeutige ID. Damit werden die mit deinem Projekt verknüpften Anfragen zu Verwendungs- und Abrechnungszwecken authentifiziert.

So rufst du einen API-Schlüssel ab:

  1. Wähle in der Cloud Console auf der Seite für die Projektauswahl ein Google Cloud-Projekt aus, für das du einen API-Schlüssel hinzufügen möchtest, oder erstelle ein neues Projekt.

    Zur Projektauswahl

    Hinweis: Nutzer mit dem Premium Plan sollten das Projekt auswählen, das mit ihrem Premium-Konto verknüpft ist. Nur so können sie alle Funktionen des Premium Plan umfassend nutzen. Als du deine Lizenz erworben hast, wurde dir der Name des entsprechenden Projekts in folgendem Format mitgeteilt: gme-[company] > proj-[number] ([type]). Stelle sicher, dass du auf das richtige Projekt zugreifst. Melde dich dazu in der Console unter console.cloud.google.com/project/number als Projektinhaber an und ersetze dabei number durch deine Projektnummer. Den Projektinhaber findest du in deinem Begrüßungsschreiben.

  2. Rufe Google Maps Platform > Anmeldedaten auf.

    Zur Seite „Anmeldedaten“

  3. Klicke auf der Seite Anmeldedaten auf Anmeldedaten erstellen > API-Schlüssel.
    Im Dialogfeld API-Schlüssel erstellt wird der neu erstellte API-Schlüssel angezeigt.
  4. Klicke auf Schließen.
    Der neue API-Schlüssel wird auf der Seite Anmeldedaten unter API-Schlüssel aufgeführt.
    Du musst den API-Schlüssel einschränken, bevor du ihn in der Produktionsumgebung verwendest.

API-Schlüssel für Anfrage angeben

Für jede Anfrage an die Google Maps Platform muss ein API-Schlüssel angegeben werden. Ersetze YOUR_API_KEY im folgenden Beispiel durch deinen API-Schlüssel.

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&key=YOUR_API_KEY

HTTPS ist für Anfragen erforderlich, die einen API-Schlüssel verwenden, und wird empfohlen für Anfragen, die eine Client-ID enthalten. HTTPS ist auch für Anwendungen mit sensiblen Nutzerdaten in Anfragen notwendig, etwa dem Standort des Nutzers.

API-Schlüssel einschränken

Wenn du API-Schlüssel einschränkst, wird deine App sicherer und es wird dafür gesorgt, dass nur autorisierte Anfragen gesendet werden. Wir empfehlen dringend, die Einschränkungen für deine API-Schlüssel zu befolgen. Weitere Informationen findest du unter Best Practices für die API-Sicherheit.

So schränkst du einen API-Schlüssel ein:

  1. Rufe Google Maps Platform > Anmeldedaten auf.

    Zur Seite „Anmeldedaten“

  2. Wähle den API-Schlüssel aus, für den du eine Einschränkung festlegen möchtest. Die Seite mit den Eigenschaften des API-Schlüssels wird angezeigt.
  3. Nimm unter Schlüsseleinschränkungen folgende Einstellungen vor:
    • App-Einschränkungen:
      1. Wenn du Anfragen von den Webserver-IP-Adressen zulassen möchtest, die du selbst bereitgestellt hast, wähle unter Anwendungseinschränkungen die Option IP-Adressen (Webserver, Cronjobs usw.) aus.
      2. Gib eine IPv4- oder IPv6-Adresse oder ein Subnetz in CIDR-Notation an (z. B. 192.168.0.0/22). Sobald du einen Eintrag fertiggestellt hast, wird ein neues Feld angezeigt. Dort kannst du einen weiteren Eintrag eingeben.
    • API-Einschränkungen:
      1. Klicke auf Schlüssel einschränken.
      2. Klicke im Drop-down-Menü APIs auswählen auf Google Maps Platform. Wenn die Google Maps Platform nicht aufgeführt ist, musst du sie aktivieren.
  4. Klicke abschließend auf Speichern.

Authentifizierung mit einer Client-ID und digitalen Signatur

Nachdem du die Google Maps Platform-Premiumoption erworben hast, erhältst du eine Begrüßungs-E-Mail mit deiner Client-ID und deinem privaten kryptografischen Schlüssel. Den Schlüssel kannst du verwenden, um eine eindeutige digitale Signatur zu erstellen.

Im Beispielcode unten siehst du die Parameter client und signature, an die du deine Client-ID und eindeutige digitale Signatur übergeben musst.

    https://maps.googleapis.com/maps/api/directions/json
      ?origin=Toronto
      &destination=Montreal
      &client=gme-YOUR_CLIENT_ID
      &signature=YOUR_URL_SIGNATURE
  • Ersetze YOUR_CLIENT_ID durch die Client-ID aus der Begrüßungs-E-Mail.

    Die Client-ID beginnt mit gme-.

  • Ersetze SIGNATURE durch deine eindeutige digitale Signatur (siehe Digitale Signatur generieren).

Hinweise:

  • Wenn du Anfragen an die Google Maps Platform mit einer Client-ID und digitalen Signatur authentifizierst, kannst du optional den Parameter channel verwenden, um detaillierte Nutzungsberichte zu erhalten. Weitere Informationen findest du unter Premiumoption – Berichte.
  • Wenn du zuvor einen API-Schlüssel für die Authentifizierung verwendet hast und auf eine Client-ID umstellst, musst du den Parameter key aus deinen Anfragen entfernen. Anfragen, die mit einer Client-ID und einem API-Schlüssel gesendet werden, werden von den Google Maps APIs-Webdiensten abgelehnt.

Digitale Signatur generieren

Nutzer der Google Maps Platform-Premiumoption benötigen eine digitale signature, um Anfragen an die Directions API zu stellen. Die Signatur kannst du mit dem privaten kryptografischen Schlüssel erstellen, den du in deiner Begrüßungs-E-Mail erhalten hast (siehe Weitere Informationen zu Ihrem privaten kryptografischen Schlüssel).

So generierst du eine digitale Signatur für deine Anfrage:

  1. Erstelle die Anfrage-URL ohne Signatur, aber mit dem Parameter client. Dabei müssen alle Sonderzeichen prozentcodiert werden:

    https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&client=clientID

    Hinweis: Für alle Google-Dienste muss die UTF-8-Zeichencodierung verwendet werden. Das schließt ASCII-Zeichen implizit ein. Falls deine Anwendungen andere Zeichensätze verwenden, müssen die URLs mit UTF-8-Codierung erstellt und ordnungsgemäß prozentcodiert werden.

  2. Entferne den Domainabschnitt der Anfrage, sodass nur Pfad und Abfrage übrig bleiben:

    /maps/api/directions/json?origin=Toronto&destination=Montreal&client=clientID

  3. Rufe deinen privaten Schlüssel ab, der mit einem modifizierten Base64-Verfahren für URLs codiert ist, und signiere die URL oben mit dem HMAC-SHA1-Algorithmus. Eventuell muss der Schlüssel in sein ursprüngliches Binärformat decodiert werden. In den meisten kryptografischen Bibliotheken liegt die resultierende Signatur im Binärformat vor.

    Hinweis: Beim modifizierten Base64-Verfahren für URLs werden die Zeichen + und / des Base64-Standardverfahrens durch - und _ ersetzt. Daher müssen diese Base64-Signaturen nicht mehr prozentcodiert werden.

  4. Codiere die resultierende binäre Signatur mit dem modifizierten Base64-Verfahren für URLs und konvertiere die Signatur so, dass sie in einer URL weitergegeben werden kann.

  5. Füge diese Signatur innerhalb eines signature-Parameters an die URL an:

    https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&client=clientID&signature=base64signature

Hinweise:

  • Anhand der eindeutigen Signatur können unsere Server verifizieren, ob Websites, die Anfragen mit Ihrer Client-ID erstellen, dazu auch autorisiert sind. Darüber hinaus ist die Signatur für jede URL eindeutig. So wird sichergestellt, dass Anfragen, die Ihre Client-ID verwenden, nicht geändert werden können, ohne dass eine neue Signatur generiert werden muss.
  • Wird versucht, mit einer ungültigen Signatur auf die Directions API zuzugreifen, wird der Fehler „HTTP 403 (Forbidden)“ zurückgegeben. Wenn du deine Anwendungen auf die Verwendung der URL-Signatur umstellst, solltest du unbedingt deine Signaturen testen. So lässt sich sicherstellen, dass damit gültige Anfragen gestartet werden. Teste dabei zuerst, ob die ursprüngliche URL gültig ist und ob du die richtigen Signaturen generierst.
  • Beispiele für Möglichkeiten zur Implementierung der URL-Signatur mit serverseitigem Code findest du unter Beispielcode für URL-Signaturen.

Um jetzt eine URL zu signieren, gib nachfolgend deine URL und deinen geheimen URL-Schlüssel ein. Die URL muss das in Schritt 1 oben beschriebene Format haben und prozentcodiert sein.

Beispielcode für URL-Signaturen

In den folgenden Abschnitten findest du Möglichkeiten zur Implementierung der URL-Signatur mit serverseitigem Code. URLs müssen immer serverseitig signiert werden, damit der kryptografische Schlüssel nicht für Nutzer sichtbar ist.

Python

Im Beispiel unten werden Python-Standardbibliotheken verwendet, um eine URL zu signieren. Hier kannst du den Code herunterladen.

#!/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

Im Beispiel unten wird die Klasse java.util.Base64 verwendet, die seit JDK 1.8 verfügbar ist. Für ältere Versionen muss möglicherweise Apache Commons o. ä. verwendet werden. Hier kannst du den Code herunterladen.

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

Im Beispiel unten werden native Node.js-Module verwendet, um eine URL zu signieren. Hier kannst du den Code herunterladen.

'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#

Im Beispiel unten wird die Standardbibliothek System.Security.Cryptography verwendet, um eine URL-Anfrage zu signieren. Wir müssen die Base64-Standardcodierung konvertieren, um eine URL-sichere Version zu implementieren. Hier kannst du den Code herunterladen.

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));
    }
  }
}

Du kannst die URL und den privaten Schlüssel unten testen, um zu prüfen, ob die richtige Signatur generiert wird. Dieser private Schlüssel dient ausschließlich zu Testzwecken und wird von keinem Google-Dienst validiert.

  • URL: https://maps.googleapis.com/maps/api/geocode/json?address=New+York&client=clientID
  • Privater Schlüssel: vNIXE0xscrmjlyV-12Nj_BvUPaw=
  • Zu signierender URL-Abschnitt: /maps/api/geocode/json?address=New+York&client=clientID
  • Unterschrift: chaRF2hTJKOScPr-RQCEhZbSzIE=
  • Vollständige signierte URL: https://maps.googleapis.com/maps/api/geocode/json?address=New+York&client=clientID&signature=chaRF2hTJKOScPr-RQCEhZbSzIE=

Beispiele in weiteren Sprachen

Beispiele für weitere Sprachen findest du hier.

Weitere Informationen zu deinem privaten kryptografischen Schlüssel

Dein privater kryptografischer URL-Signaturschlüssel wird zusammen mit deiner Client-ID ausgegeben. Dabei handelt es sich um einen „gemeinsamen Secret-Schlüssel“, den du mit Google teilst. Dieser Signaturschlüssel gehört nur dir und ist deiner Client-ID eindeutig zugeordnet. Halte ihn also bitte geheim. Er darf nicht in Anfragen übergeben, auf Websites gespeichert oder in öffentlichen Foren gepostet werden. Sollten Dritte Zugriff auf deinen Signaturschlüssel erhalten, können sie deine Identität verwenden, um Anfragen zu senden.

Hinweis: Dieser private kryptografische Signaturschlüssel ist nicht mit den API-Schlüsseln identisch, die von der Google Cloud Console ausgegeben werden.

Wenn du deinen privaten kryptografischen Schlüssel verloren hast, kannst du dich in der Cloud Console anmelden und auf Maps: Manage Client ID (Maps: Client-ID verwalten) klicken, um ihn abzurufen.

Authentifizierungsprobleme beheben

Falls die Anfrage nicht richtig formatiert ist oder eine ungültige Signatur enthält, wird von der Google Maps Platform der Fehler HTTP 403 (Forbidden) zurückgegeben.

Wenn du Fehler für einzelne URLs beheben musst, kannst du den URL Signing Debugger verwenden. Mit ihm lässt sich eine URL und eine von deiner Anwendung generierte Signatur schnell validieren.

Nutzer mit Premiumoption, die Fehler für einzelne URLs beheben müssen, haben außerdem die Möglichkeit, sich in der Cloud Console anzumelden und dort Resources > Google Maps Platform Premium Plan online tools > URL Signing Debugger for Web Service and Image APIs (Ressourcen > Onlinetools der Google Maps Platform-Premiumoption > URL-Signaturdebugger für Web Service und Image APIs) auszuwählen.