Geocoding API: API キーの取得

注: 新規のお申し込み時または新規のお客様は、Google Maps Platform プレミアム プランをご利用いただけません。

認証方式の選択

Geocoding API を使用するには、API キーとデジタル署名、またはクライアント ID とデジタル署名を使用してリクエストを認証する必要があります。

どちらの方式で認証するかは、お客様がご利用のラインセスによって決まります。

  • プレミアム プランをご利用の場合は、API キーまたはクライアント ID とデジタル署名を使用できます。
  • 以前のライセンスをご利用の場合は、クライアント ID とデジタル署名を使用する必要があります。

ご利用のライセンス(プレミアム プランまたは以前のライセンス)を確認する方法
現在お持ちのライセンスを確認するには:
> Google Cloud サポート ポータルで、左側の [Maps: Usage Report] をクリックします。
> レポート上部の ID の形式を確認します。
   gme-[company] & proj-[number] ([type])
上記の形式の場合、プレミアム プランをご利用中です。
上記の形式でない場合、以前のライセンス(Maps API for Work または Maps API for Business)をご利用中です。

使用する認証方式を決定する際は、以下の点を考慮してください。

  • API キーによる認証(プレミアム プラン)
    API キーを使用してリクエストを認証する場合:
  • クライアント ID とデジタル署名による認証(プレミアム プランまたは以前のライセンス)
    クライアント ID とデジタル署名を使用してリクエストを認証する場合:
    • リクエストに channel パラメータを追加し、より詳細な使用状況レポートを表示できます。
    • Google Cloud サポート ポータルで、30 日以上のデータが反映された使用状況レポートを表示できます。
    • Maps JavaScript API で Maps Analytics ツールを使用できます。

プレミアム プランのお客様が利用できるレポートをご確認ください。

API キーを使用した認証

API キーの取得

API キーは、使用量を正確に集計して課金できるよう、プロジェクトに関連付けられたリクエストであることを認証する一意の識別子です。

API キーを取得するには:

  1. GCP Console の [プロジェクトの選択] ページで、API キーを追加する Google Cloud プロジェクトを選択または作成します。

    [プロジェクトの選択] ページに移動

    注: プレミアム プランのすべての機能をご利用になるには、お客様のプレミアム アカウントに関連付けられたプロジェクトを使用する必要があります。ライセンスの購入時に、gme-[company] & proj-[number] ([type]) の形式のプレミアム アセット名がお客様に通知されています。適切なプロジェクトにアクセスするため、console.cloud.google.com/project/numbernumber はお客様のプロジェクト番号)を使用し、プロジェクト オーナーとして Cloud Console にログインしてください。プロジェクト オーナーはウェルカム レターに記載されています。

  2. [API とサービス] > [認証情報] を選択します。

    [認証情報] ページに移動

  3. [認証情報] ページで、[認証情報を作成] > [API キー] をクリックします。
    [API キーを作成しました] ダイアログで、新しく作成された API キーが表示されます。
  4. [閉じる] をクリックします。
    新しい API キーは、[認証情報] ページの [API キー] に表示されます。
    (本番環境で使用する前に、忘れずに API キーの使用を制限してください)。

リクエストへの API キーの追加

すべての Geocoding API リクエストに API キーを追加する必要があります。次の例では、YOUR_API_KEY を API キーに置き換えます。

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

API キーの制限

API キーを制限し、許可したリクエストでのみ API キーが使用されるようにすることで、アプリケーションのセキュリティが向上します。以下の手順に沿って API キーの制限を設定することを強くおすすめします。詳しくは、API キーに関する推奨事項をご覧ください。

API キーを制限するには:

  1. GCP Console の [プロジェクトの選択] ページで、API キーを追加する Google Cloud プロジェクトを選択または作成します。

    [プロジェクトの選択] ページに移動

  2. [API とサービス] > [認証情報] を選択します。

    [認証情報] ページに移動

  3. 制限を設定する API キーを選択します。選択した API キーのプロパティ ページが表示されます。
  4. [キーの制限] で、次の制限を設定します。
    • アプリケーションの制限:
      1. 指定したウェブサーバー IP アドレスからのリクエストを受け入れるには、[アプリケーションの制限] のリストで [IP アドレス(ウェブサーバー、cron ジョブなど)] を選択します。
      2. IPv4 アドレスまたは IPv6 アドレスを 1 つ指定するか、CIDR 表記を使用してサブネットを指定します(例: 192.168.0.0/22)。エントリを追加して [完了] をクリックすると、新しいボックスが表示されます。必要であれば、このボックスに別のエントリを入力します。
    • API の制限:
      1. [キーを制限] をクリックします。
      2. [API の選択] プルダウンで [Geocoding API] を選択します。
        (Geocoding API がリストに表示されない場合は、この API を有効にする必要があります)
  5. 変更が完了したら、[保存] をクリックします。

クライアント ID とデジタル署名を使用した認証

Google Maps Platform プレミアム プラン ライセンスを購入すると、クライアント ID と秘密の暗号鍵が記載されたウェルカム メールが Google から届きます(これらの情報を使用して、一意のデジタル署名を生成します)。

次のサンプルコードに示すように、client パラメータと signature パラメータを使用して、クライアント ID と一意のデジタル署名を渡す必要があります。

    https://maps.googleapis.com/maps/api/geocode/json
      ?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA
      &client=YOUR_CLIENT_ID
      &signature=SIGNATURE
  • YOUR_CLIENT_ID は、ウェルカム メールに記載されているクライアント ID に置き換えます。

    クライアント ID は「gme-」という文字列で始まります。

  • SIGNATURE を一意のデジタル署名に置き換えます(デジタル署名を生成するをご覧ください)。

注:

  • クライアント ID とデジタル署名で Geocoding API を認証する際、必要であれば、channel パラメータを使用して詳細な使用状況レポートを取得することもできます。詳しくは、プレミアム プランのレポートをご覧ください。
  • これまで API キーを使用してリクエストを認証しており、今後はクライアント ID による認証に切り替える場合は、リクエストから key パラメータを削除する必要があります。Google Maps API ウェブサービスでは、クライアント ID と API キーを両方使用しているリクエストは拒否されます

デジタル署名の生成

Google Maps Platform プレミアム プランのお客様が Geocoding API をリクエストするには、デジタル signature が必要です。これは、ウェルカム メールに記載されている秘密暗号鍵を使って生成できます(秘密暗号鍵の詳細をご確認ください)。

以下の手順に沿って、リクエストに必要なデジタル署名を生成します。

  1. 署名なしでリクエスト URL を作成します。必ず client パラメータを追加してください。標準以外の文字は URL エンコードする必要があります。

    https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&client=clientID

    注: すべての Google サービスで、(暗黙的に ASCII を含む)UTF-8 文字エンコードを使用する必要があります。アプリケーションで他の文字セットを使用する場合は、UTF-8 に基づいて URL を作成し、適切に URL エンコードされるようにしてください。

  2. パスとクエリのみを残して、リクエストのドメイン部分を削除します。

    /maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&client=clientID

  3. URL 用修正 Base64 でエンコードされた秘密鍵を取得し、HMAC-SHA1 アルゴリズムを使用して上記の URL に署名します。場合によっては、この鍵を元のバイナリ形式にデコードする必要があります。ほとんどの暗号ライブラリでは、署名がバイナリ形式で生成されます。

    注: URL 用修正 Base64 では、標準 Base64 の + 文字と / 文字がそれぞれ -_ に置き換えられます。したがって、これらの Base64 署名を URL エンコードする必要がありません。

  4. 生成されたバイナリ署名を URL 用修正 Base64 でエンコードし、URL に指定して渡せるように変換します。

  5. この署名を URL の signature パラメータに追加します。

    https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&client=clientID&signature=base64signature

注:

  • この一意の署名により、お客様のクライアント ID を使用してリクエストを生成するサイトは、いずれも許可されたサイトであることがわかります。また、署名は URL ごとに異なるため、クライアント ID を使用するリクエストを変更するには、必ず新しい署名を生成する必要があります。
  • 無効な署名を使用して Geocoding API にアクセスしようとすると、HTTP 403(Forbidden)エラーが発生します。URL 署名を使用するようにアプリケーションを変更するときは、署名をテストして、有効なリクエストが送信されることを確認してください。まず、元の URL が有効かどうかをテストし、さらに正しい署名が生成されるかどうかテストします。
  • サーバー側のコードを使用して URL 署名を実装する方法については、URL 署名のサンプルコードをご覧ください。

今すぐ URL に署名するには、以下に URL と URL 署名シークレットを入力します。入力する URL は、手順 1 で説明した形式に従い、さらに URL エンコードされている必要があります。

URL 署名のサンプルコード

以下のセクションでは、サーバー側のコードを使用して URL 署名を実装する方法を説明します。暗号鍵をユーザーに知られないようにするため、URL は常にサーバー側で署名してください。

Python

次の例では、標準の Python ライブラリを使用して URL に署名しています (サンプルコードをダウンロード)。

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

次の例では、JDK 1.8 以降で利用可能な java.util.Base64 クラスを使用します。これより古いバージョンでは、Apache Commons などを使用する必要があります(サンプルコードをダウンロード)。

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

次の例では、ネイティブの Node モジュールを使用して URL に署名します(サンプルコードをダウンロード)。

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

次の例では、デフォルトの System.Security.Cryptography ライブラリを使用して URL リクエストに署名します。URL セーフ バージョンを実装するには、デフォルトの Base64 エンコーディングを変換する必要があります(サンプルコードをダウンロード)。

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

次の URL と秘密鍵をテストして、正しい署名が生成されるかどうかを確認できます。この秘密鍵はテスト専用です。いずれの Google サービスでも検証されません。

  • URL: https://maps.googleapis.com/maps/api/geocode/json?address=New+York&client=clientID
  • 秘密鍵: vNIXE0xscrmjlyV-12Nj_BvUPaw=
  • 署名する URL 部分: /maps/api/geocode/json?address=New+York&client=clientID
  • 署名: chaRF2hTJKOScPr-RQCEhZbSzIE=
  • 署名された完全な URL: https://maps.googleapis.com/maps/api/geocode/json?address=New+York&client=clientID&signature=chaRF2hTJKOScPr-RQCEhZbSzIE=

その他の言語のサンプルコード

その他の言語のサンプルコードは、URL 署名プロジェクトで入手できます。

秘密暗号鍵について

URL の署名で必要となる秘密暗号鍵はクライアント ID を使用して発行され、お客様と Google が共有する「秘密鍵」です。この署名鍵はお客様だけのものであり、お客様のクライアント ID に関連付けられています。そのため、署名鍵は厳重に保管する必要があります。この鍵をリクエストに追加して送信したり、ウェブサイトに保存したり、公開フォーラムに投稿したりしないでください。この署名鍵が第三者に知られると、お客様の ID を利用してリクエストが偽装される可能性があります。

注: この秘密の暗号署名鍵は、Google Cloud Platform Console で発行される API キーと同じではありません

秘密暗号鍵を紛失した場合は、Google Cloud サポート ポータルにログインし、 [Maps: Manage Client ID] をクリックして取得してください。

認証の問題のトラブルシューティング

リクエストの形式が正しくない場合や、署名が無効な場合は、Geocoding API から HTTP 403 (Forbidden) エラーが返されます。

URL を個別にトラブルシューティングするときは、URL Signing Debugger を使用すると便利です。これを使用すると、URL やアプリケーションによって生成された署名をすばやく検証できます。

プレミアム プランのお客様が個々の URL をトラブルシューティングするには、Google Cloud サポート ポータルにログインし、[リソース] > [Google Maps Platform プレミアム プランのオンライン ツール] > [ウェブサービスおよびイメージ API 向け URL Signing Debugger] を選択する方法もあります。