Geocoding API ウェブサービスを使用する際のベスト プラクティス

Google Maps Platform ウェブサービスは、地図アプリケーションに地理データを提供する Google サービスへの HTTP インターフェースのコレクションです。

このガイドでは、ウェブサービス リクエストのセットアップとサービス レスポンスの処理に役立つ一般的なプラクティスについて説明します。Geocoding API のドキュメントについて詳しくは、デベロッパー ガイドをご覧ください。

ウェブサービスとは

Google Maps Platform ウェブサービスは、外部サービスから Maps API データをリクエストし、そのデータをマップ アプリケーション内で使用するためのインターフェースです。これらのサービスは、Google Maps Platform 利用規約のライセンス制限に基づき、地図と組み合わせて使用するように設計されています。

Maps API ウェブサービスは、特定の URL に対して HTTP(S) リクエストを使用し、URL パラメータや JSON 形式の POST データを引数としてサービスに渡します。一般に、これらのサービスは、アプリケーションで解析や処理を行うために、データを JSON または XML としてレスポンス本文で返します。

Geocoding API の一般的なリクエストは、通常、次のような形式になります。

https://maps.googleapis.com/maps/api/geocode/output?parameters

ここで、output はレスポンスの形式（通常は json または xml）を示します。

注: Geocoding API アプリケーションはすべて認証が必要です。認証情報の詳細を確認する。

SSL/TLS アクセス

API キーを使用する、またはユーザーデータが含まれるすべての Google Maps Platform リクエストで HTTPS を使用する必要があります。HTTP 経由で送信された、機密データを含むリクエストは拒否される場合があります。

有効な URL の作成

「有効」な URL とは何か、説明の必要はないと考えられるかもしれませんが、それほど単純なことではありません。ブラウザのアドレスバーに入力される URL には特殊文字（"上海+中國" など）が含まれている場合があります。このような特殊文字は、ブラウザで別のエンコードに内部的に変換してから送信する必要があります。同様に、UTF-8 入力を生成または受け付けるコードでは、UTF-8 の文字が使用された URL を「有効」な URL として扱うことがありますが、それらの文字はウェブサーバーに送信する前に変換する必要があります。このプロセスは、URL エンコードまたはパーセント エンコードと呼ばれます。

特殊文字

すべての URL は URI（Uniform Resource Identifier）仕様で規定されている構文に従う必要があるため、特殊文字を変換する必要があります。つまり、URL には、ASCII 文字の特別なサブセット（よく使用される英数記号および URL 内で制御文字として使用される予約文字）のみを含める必要があります。次の表は、こうした特殊記号をまとめたものです。

有効な URL を作成するときは、有効な URL 文字の概要表に記載されている文字のみを使用する必要があります。しかし、URL での使用がこの文字セットだけに制限された場合、通常は 2 つの問題が発生します。1 つは省略、もう 1 つは置き換えです。

• 処理する文字が上記のセットに含まれない場合。たとえば、「上海+中國」のような英語以外の文字は、上記の文字を使用してエンコードする必要があります。一般的な命名規則では、URL 内で使用できないスペースもプラス記号 '+' を使用して表します。
• 上記のセットに予約文字として含まれる文字を、リテラル文字として使用する必要がある場合。たとえば、「?」は URL 内でクエリ文字列の先頭を示すために使用されます。文字列「?　and the Mysterions」を使用する場合は、文字 '?' をエンコードする必要があります。

URL エンコードが必要なすべての文字を、'%' と、UTF-8 文字に対応する 2 文字の 16 進数値を使用してエンコードします。たとえば、UTF-8 の「上海+中國」は、「%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B」として URL エンコードされます。文字列「? and the Mysterians」は、「%3F+and+the+Mysterians」または「%3F%20and%20the%20Mysterians」として URL エンコードされます。

エンコードが必要な一般的な文字

エンコードする必要がある一般的な文字は次のとおりです。

ユーザー入力から受け取った URL の変換には、場合によって注意が必要です。たとえば、ユーザーが住所を「5th&Main St.」と入力することも考えられます。通常は、ユーザー入力をリテラル文字として処理して、URL をパーツから作成する必要があります。

また、URL は、すべての Google Maps Platform ウェブサービスと Static Web API で 16, 384 文字に制限されています。ほとんどのサービスでは、この文字制限に達することはめったにありません。ただし、複数のパラメータを持つ特定のサービスでは、URL が長くなる可能性があります。

Google API の適切な使用

API クライアントの設計に問題があると、インターネットと Google のサーバーの両方に必要以上の負荷がかかる可能性があります。このセクションでは、API のクライアントに関するベスト プラクティスについて説明します。これらのベスト プラクティスに従うことで、誤って API を悪用してアプリケーションがブロックされないようにすることができます。

エラーの対処と再試行

Geocoding API の UNKNOWN_ERROR または OVER_QUERY_LIMIT レスポンス コードについては、エラーと再試行の管理をご覧ください。

指数関数的バックオフ

まれに、リクエストの処理で問題が発生する場合があります。HTTP レスポンス コードが 4XX または 5XX になったり、TCP 接続がクライアントと Google サーバーの間のどこかで失敗したりすることがあります。元のリクエストが失敗したときにフォローアップ リクエストが成功する場合があるため、リクエストを再試行する価値はよくあります。ただし、Google のサーバーへのリクエストを繰り返し繰り返すだけではないことが重要です。このループ動作は、クライアントと Google の間のネットワークに過負荷をかけ、多くの人に問題を引き起こします。

より良いアプローチは、試行間の遅延を増やして再試行することです。通常、遅延は試行ごとに乗算係数で増加します。これは指数バックオフと呼ばれるアプローチです。

たとえば、Time Zone API に次のリクエストを送信するアプリケーションについて考えてみましょう。

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

次の Python の例では、指数関数的バックオフを使用してリクエストを実行する方法を示しています。

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

また、アプリケーション呼び出しチェーンの上位に再試行コードがあると、リクエストが連続して繰り返されないように注意する必要があります。

同期されたリクエスト

Google の API に対して同期された多数のリクエストは、Google のインフラストラクチャに対する分散型サービス拒否（DDoS）攻撃のように見え、それに応じて処理されます。これを回避するには、API リクエストがクライアント間で同期されないようにする必要があります。

たとえば、現在のタイムゾーンで時刻を表示するアプリケーションについて考えてみましょう。このアプリケーションは、表示される時刻を更新できるように、毎分 0 秒にスリープ解除するクライアント オペレーティング システムでアラームを設定します。アプリケーションで、このアラームに関連付けられた処理の一部として API 呼び出しを行うことはありません。

固定アラームに応じて API 呼び出しを行うことは、時間の経過とともに均等に分散されずに、異なるデバイス間でも毎分 0 秒に同期されるため、適切ではありません。設計が不適切なアプリケーションでは、この処理を行っていると、毎分 1 分の開始時に通常の 60 倍のレベルでトラフィックが急増します。

代わりに、ランダムに選択された時刻に 2 つ目のアラームを設定することが、良い設計の一つです。この 2 回目のアラームが発生すると、アプリは必要な API を呼び出し、結果を保存します。アプリケーションが毎分 0 時に表示を更新する場合、API を再度呼び出すのではなく、以前に保存された結果を使用します。この方法では、API 呼び出しは時間とともに均等に分散されます。さらに、API 呼び出しによって、ディスプレイの更新時にレンダリングが遅延することはありません。

毎分 000 時間以外の一般的な同期時刻は、毎時間 1 時間の開始時刻や毎日の深夜 0 時をターゲットとしないように注意する必要があります。

レスポンスの処理

このセクションでは、これらの値をウェブサービス レスポンスから動的に抽出する方法について説明します。

Google マップ ウェブサービスで提供されるレスポンスはわかりやすいものですが、必ずしも使いやすいわけではありません。クエリを実行するときに、データセットを表示するのではなく、特定の値を抽出することをおすすめします。通常は、ウェブサービスからのレスポンスを解析し、必要な値のみを抽出します。

使用する解析スキームは、出力を XML と JSON のどちらで返すかによって異なります。JSON レスポンスは、すでに JavaScript オブジェクトの形式で、クライアントの JavaScript 内で処理できます。 XML レスポンスは、XML プロセッサと XML クエリ言語を使用して、XML 形式内の要素に対処して処理する必要があります。次の例では、XML 処理ライブラリで一般的にサポートされている XPath を使用しています。

XPath による XML の処理

XML は、データ交換に使用される比較的成熟した構造化情報形式です。XML は JSON ほど軽量ではありませんが、より多くの言語サポートと堅牢なツールを提供します。たとえば、Java で XML を処理するコードは、javax.xml パッケージに組み込まれています。

XML レスポンスを処理する際は、要素が XML マークアップ内の絶対位置にあることを前提とするのではなく、適切なクエリ言語を使用して XML ドキュメント内のノードを選択する必要があります。XPath は、XML ドキュメント内のノードと要素を一意に記述するための言語構文です。XPath 式を使用すると、XML レスポンス ドキュメント内の特定のコンテンツを識別できます。

XPath 式

XPath にある程度の知識があると、堅牢な解析スキームの開発に大いに役立ちます。このセクションでは、XML ドキュメント内の要素を XPath でアドレス指定する方法に焦点を当てます。これにより、複数の要素に対処し、複雑なクエリを作成できます。

XPath では、ディレクトリ パスに使用される構文と同様の構文を使用して、式を使用して XML ドキュメント内の要素を選択します。これらの式は、XML ドキュメント ツリー（DOM に似た階層ツリー）内の要素を識別します。通常、XPath 式は貪欲であり、指定された条件に一致するすべてのノードに一致することを示します。

以下の抽象 XML を使用して、例を示します。

<WebServiceResponse>
 <status>OK</status>
 <result>
  <type>sample</type>
  <name>Sample XML</name>
  <location>
   <lat>37.4217550</lat>
   <lng>-122.0846330</lng>
  </location>
 </result>
 <result>
  <message>The secret message</message>
 </result>
</WebServiceResponse>

式でのノード選択

XPath では、ノードを選択します。ルートノードにはドキュメント全体が含まれます。このノードを選択するには、特別な式「/」を使用します。ルートノードは XML ドキュメントのトップレベル ノードではありません。実際には、このトップレベル要素の 1 レベル上に存在し、その要素を含みます。

要素ノードは、XML ドキュメント ツリー内のさまざまな要素を表します。たとえば、<WebServiceResponse> 要素は、上記のサンプル サービスで返されるトップレベル要素を表します。先頭に「/」文字があるかどうかで、絶対パスまたは相対パスで個々のノードを選択します。

• 絶対パス: 式「/WebServiceResponse/result」は、<WebServiceResponse> ノードの子である <result> ノードをすべて選択します。（これらの要素は両方ともルートノード「/」の子孫です）。
• 現在のコンテキストからの相対パス: 式「result」は、現在のコンテキスト内のすべての <result> 要素と一致します。通常、ウェブサービスの結果を 1 つの式で処理するため、コンテキストを気にする必要はありません。

どちらの式も、ダブルスラッシュで示されるワイルドカード パス（「//」）を追加することで拡張できます。このワイルドカードは、中間パスに 0 個以上の要素が一致することを示します。たとえば、XPath 式「//formatted_address」は、現在のドキュメント内でその名前のすべてのノードに一致します。式 //viewport//lat は、親として <viewport> をトレースできるすべての <lat> 要素に一致します。

デフォルトでは、XPath 式はすべての要素に一致します。式を特定の要素に一致するように制限するには、述語を角かっこ（[]）で囲んで指定します。たとえば、XPath 式 /GeocodeResponse/result[2] は、常に 2 番目の結果を返します。

    <WebServiceResponse>
     <status>OK</status>
     <result>
      <type>sample</type>
      <name>Sample XML</name>
      <location>
       <lat>37.4217550</lat>
       <lng>-122.0846330</lng>
      </location>
     </result>
     <result>
      <message>The secret message</message>
     </result>
    </WebServiceResponse>
    

    <result>
     <type>sample</type>
     <name>Sample XML</name>
     <location>
      <lat>37.4217550</lat>
      <lng>-122.0846330</lng>
     </location>
    </result>
    <result>
     <message>The secret message</message>
    </result>
    

    <location>
     <lat>37.4217550</lat>
     <lng>-122.0846330</lng>
    </location>
    

    <message>The secret message</message>
    

     <type>sample</type>
     <name>Sample XML</name>
     <location>
      <lat>37.4217550</lat>
      <lng>-122.0846330</lng>
     </location>
    

    Sample XML
    

要素を選択する際は、オブジェクト内のテキストだけでなく、ノードを選択することに注意してください。通常は、一致したすべてのノードで反復処理を行い、テキストを抽出します。テキストノードを直接照合することもできます。以下のテキストノード をご覧ください。

XPath は属性ノードもサポートしていますが、すべての Google マップ ウェブサービスは属性のない要素を提供するため、属性のマッチングは必要ありません。

式でのテキスト選択

XML ドキュメント内のテキストは、テキストノード演算子を使用して XPath 式で指定します。この演算子「text()」は、指定されたノードからのテキストの抽出を示します。たとえば、XPath 式「//formatted_address/text()」は、<formatted_address> 要素内のすべてのテキストを返します。

    sample
    Sample XML

    37.4217550
    -122.0846330
    The secret message
    

    The secret message
    

    Sample XML
    

または、式を評価してノードのセットを返し、その「ノードセット」を繰り返し処理して、各ノードからテキストを抽出することもできます。次の例でこの方法を使用します。

XPath の詳細については、XPath W3C 仕様をご覧ください。

Java での XPath の評価

Java は、javax.xml.xpath.* パッケージ内での XML の解析と XPath 式の使用を幅広くサポートしています。そのため、このセクションのサンプルコードでは、Java を使用して、XML を処理し、XML サービス レスポンスのデータを解析する方法を示しています。

Java コードで XPath を使用するには、まず XPathFactory のインスタンスをインスタンス化し、そのファクトリで newXPath() を呼び出して XPath オブジェクトを作成する必要があります。その後、このオブジェクトで evaluate() メソッドを使用して、渡された XML と XPath 式を処理できます。

XPath 式を評価する場合は、返される可能性があるすべての「ノードセット」を反復処理してください。これらの結果は Java コードでは DOM ノードとして返されるため、NodeList オブジェクト内でこうした複数の値をキャプチャし、そのオブジェクトを反復処理して、ノードからテキストまたは値を抽出する必要があります。

次のコードは、XPath オブジェクトを作成して XML と XPath 式を割り当て、式を評価して関連するコンテンツを表示する方法を示しています。

import org.xml.sax.InputSource;
import org.w3c.dom.*;
import javax.xml.xpath.*;
import java.io.*;

public class SimpleParser {

  public static void main(String[] args) throws IOException {

	XPathFactory factory = XPathFactory.newInstance();

    XPath xpath = factory.newXPath();

    try {
      System.out.print("Web Service Parser 1.0\n");

      // In practice, you'd retrieve your XML via an HTTP request.
      // Here we simply access an existing file.
      File xmlFile = new File("XML_FILE");

      // The xpath evaluator requires the XML be in the format of an InputSource
	  InputSource inputXml = new InputSource(new FileInputStream(xmlFile));

      // Because the evaluator may return multiple entries, we specify that the expression
      // return a NODESET and place the result in a NodeList.
      NodeList nodes = (NodeList) xpath.evaluate("XPATH_EXPRESSION", inputXml, XPathConstants.NODESET);

      // We can then iterate over the NodeList and extract the content via getTextContent().
      // NOTE: this will only return text for element nodes at the returned context.
      for (int i = 0, n = nodes.getLength(); i < n; i++) {
        String nodeString = nodes.item(i).getTextContent();
        System.out.print(nodeString);
        System.out.print("\n");
      }
    } catch (XPathExpressionException ex) {
	  System.out.print("XPath Error");
    } catch (FileNotFoundException ex) {
      System.out.print("File Error");
    }
  }
}