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

Google Maps Platform のウェブサービスは、Google サービスへの HTTP インターフェースを集めたもので、地図アプリケーションに地理データを提供します。

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

ウェブサービスとは

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

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

Places API の一般的なリクエストの形式は次のとおりです。

https://places.googleapis.com/v1/places/PLACE_ID?parameters

: すべての Places 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 での使用法
英数字 a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 テキスト文字列、スキームでの使用(http)、ポート(8080)など
未予約 - _ . ~ テキスト文字列
予約済み ! * ' ( ) ; : @ & = + $ , / ? です。% # [ ] 制御文字やテキスト文字列

有効な 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 エンコードされます。

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

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

危険な文字 エンコードされた値
スペース %20
%22
< %3C
> %3E
# %23
% %25
| %7C

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

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

Google API の適切な使用

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

指数関数的バックオフ

まれに、リクエストの処理でなんらかの問題が発生することがあります。4XX または 5XX HTTP レスポンス コードを受け取ったり、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 呼び出しを行うと、異なるデバイス間でも、API 呼び出しは時間の経過とともに均等に分散されず、毎分 0 分に同期されるため、適していません。このような設計の問題があるアプリケーションでは、毎分 00:00 に通常の 60 倍のレベルでトラフィックが急増します。

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

毎正時以外の一般的な同期時刻は、1 時間の開始時や、毎正時の深夜 0 時にターゲットにしないでください。

レスポンスの処理

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

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

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

XPath による XML の処理

XML は、データ交換に使用される比較的成熟した構造化情報形式です。JSON ほど軽量ではありませんが、XML の方がより多くの言語サポートと堅牢なツールを提供します。たとえば、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 式はすべての要素に一致します。特定の要素に一致するように式を制限するには、述語を指定します。述語は角かっこ([])で囲まれていますpredicate。たとえば、XPath 式「/GeocodeResponse/result[2]」は、常に 2 番目の結果を返します。

式のタイプ
ルートノード
XPath 式:/
選択:
    <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 式:/WebServiceResponse/result
選択:
    <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>
    
ワイルドカード付きパス
XPath 式:/WebServiceResponse//location
選択:
    <location>
     <lat>37.4217550</lat>
     <lng>-122.0846330</lng>
    </location>
    
述語付きパス
XPath 式:/WebServiceResponse/result[2]/message
選択:
    <message>The secret message</message>
    
最初の result のすべての直接の子
XPath 式:/WebServiceResponse/result[1]/*
選択:
     <type>sample</type>
     <name>Sample XML</name>
     <location>
      <lat>37.4217550</lat>
      <lng>-122.0846330</lng>
     </location>
    
type テキストが「sample」である resultname
XPath 式:/WebServiceResponse/result[type/text()='sample']/name
選択:
    Sample XML
    

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

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

式でのテキスト選択

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

式のタイプ
すべてのテキストノード(空白を含む)
XPath 式://text()
選択:
    sample
    Sample XML

    37.4217550
    -122.0846330
    The secret message
    
テキストの選択
XPath 式:/WebServiceRequest/result[2]/message/text()
選択:
    The secret message
    
コンテキスト依存の選択
XPath 式:/WebServiceRequest/result[type/text() = 'sample']/name/text()
選択:
    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");
    }
  }
}