Roads API ウェブサービスの使用に関するベスト プラクティス

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

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

ウェブサービスとは

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

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

通常、Roads API ウェブサービスのリクエストは、次のような形式になります。

https://roads.googleapis.com/v1/snapToRoads?parameters&key=YOUR_API_KEY

ここで、snapToRoads はリクエストされた特定のサービスを示します。その他の Roads サービスには nearestRoads と speedLimits があります。

注: すべての Roads API アプリケーションには認証が必要です。詳しくは、認証情報についての記事をご覧ください。

SSL/TLS アクセス

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

有効な URL の作成

「有効」な URL とは何か、説明の必要はないと考えられるかもしれませんが、それほど単純なことではありません。ブラウザのアドレスバーに入力される URL には特殊文字（"上海+中國" など）が含まれている場合があります。このような特殊文字は、ブラウザで別のエンコードに内部的に変換してから送信する必要があります。同様に、UTF-8 入力を生成するコードや受け付けるコードでは、UTF-8 の文字が使用された URL を「有効」な URL として扱うことがありますが、それらの文字を Web サーバーに送信する前に変換する必要があります。このプロセスは、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 で 8,192 文字に制限されています。ほとんどのサービスでは、この文字制限に達することはめったにありません。ただし、複数のパラメータを持つ特定のサービスでは、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 リクエストが同期されないようにする必要があります。

たとえば、現在のタイムゾーンの時刻を表示するアプリケーションを考えてみましょう。このアプリは、表示されている時刻を更新できるように、開始時にアラームをクライアント オペレーティング システムで作動させます。アプリケーションは、そのアラームに関連する処理の一環として API 呼び出しを行わないでください。

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

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

毎分 1 秒以外に、ターゲットにしない一般的な同期時刻は、1 時間の開始時刻と、毎日午前 0 時に開始することです。

レスポンスの処理

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

Google マップのウェブサービスが提供するレスポンスは理解しやすいものですが、必ずしもユーザー フレンドリーであるとは言えません。クエリを実行するときは、一連のデータを表示するのではなく、具体的な値を抽出することをおすすめします。一般的には、ウェブサービスからのレスポンスを解析し、関心のある値のみを抽出します。

使用する解析スキームは、JSON で出力を返すかどうかによって異なります。JSON レスポンスは、すでに JavaScript オブジェクトの形で、クライアント上の JavaScript 自体内で処理されることがあります。