データセットの作成

データセットは、次の 2 段階のプロセスで作成します。

  1. データセットの作成をリクエストします。

  2. データセットへのデータのアップロードをリクエストします。

最初のデータのアップロード後、データセットに新しいデータをアップロードし、 変更します。

前提条件

データセットの作成:

  • 表示名を同じ Google Cloud プロジェクト内で重複させることはできません。
  • 表示名は 64 バイト以内にする必要があります（文字は UTF-8 で表現されるため、言語によっては 1 文字で 2 バイト以上使用することがあります）。
  • 説明は 1,000 バイト未満にする必要があります。

データのアップロード:

  • サポートされるファイル形式は CSV、GeoJSON、KML です。
  • ファイルサイズは 350 MB が上限です。
  • 属性列の名前の先頭を「?_」にすることはできません。
  • 3 次元のジオメトリ（WKT 形式の「Z」接尾辞、GeoJSON 形式の標高座標など）はサポートされていません。

データを準備する際のベスト プラクティス

密集したポイント、長いラインストリング、ポリゴンなど、ソースデータが複雑であったり大きかったりする場合（多くの場合、サイズが 50 MB を超えるソースファイルがこのカテゴリに該当）、視覚的な地図で最高のパフォーマンスを実現するには、アップロードする前にデータを簡素化することを検討してください。

データを準備する際のベスト プラクティスを以下にご紹介します。

  1. 地図対象物のプロパティを最小化します。地図のスタイル設定に必要な地図対象物プロパティ（「id」や「category」など）のみを残します。データドリブン スタイル設定で一意の識別子キーを使用して、クライアント アプリケーションで地図対象物に追加のプロパティを結合できます。たとえば、データドリブン スタイル設定を使ってデータをリアルタイムに確認する方法についての記事をご覧ください。
  2. タイルのサイズを最小限に抑え、地図のパフォーマンスを向上させるには、可能な場合はプロパティ オブジェクトに整数などの単純なデータ型を使用します。
  3. ファイルをアップロードする前に、複雑なジオメトリを簡略化します。複雑なポリゴン ジオメトリに対してオープンソースの Mapshaper.org ユーティリティなどの地理空間ツールか BigQuery で ST_Simplify を使用して簡略化できます。
  4. ファイルをアップロードする前に、非常に密集したポイントをクラスタ化します。密集したポイント ジオメトリに対してオープンソースの turf.js クラスタ関数などの地理空間ツールか BigQuery で ST_CLUSTERDBSCAN を使用してクラスタ化できます。

データセットのベスト プラクティスに関する追加のガイダンスについては、データセットと BigQuery を使用してデータを視覚化する方法についての記事をご覧ください。

GeoJSON での要件

Maps Datasets API は GeoJSON 仕様。 Maps Datasets API では、次のいずれかのオブジェクト タイプを含む GeoJSON ファイルがサポートされています。

  • ジオメトリ（geometry）オブジェクト: ジオメトリ オブジェクトは、ポイント（点）、ライン（線）、ポリゴン（多角形）の結合体として記述される空間形状です。ポリゴンには穴を開けることも可能です。
  • 対象物（feature）オブジェクト: ジオメトリ情報に、名前と値のペアから成るプロパティ（複数可）を付加したものです。プロパティには、各アプリケーションで固有の意味を持たせることができます。
  • 対象物（feature）コレクション: 対象物オブジェクトの集合です。

Maps Datasets API は、座標参照系にデータが含まれる GeoJSON ファイルをサポートしていません （CRS）（WGS84 を除く）

GeoJSON について詳しくは、RFC 7946 仕様をご覧ください。

KML での要件

Maps Datasets API には次の要件があります。

  • URL はすべて、ファイル自体を基準としたローカル（相対）指定で記述する必要があります。
  • サポートされるジオメトリ情報はポイント、ライン、ポリゴンです。
  • データ属性はすべて文字列と見なされます。
KML の以下の機能はサポート外です。
  • ファイル外で定義された <styleUrl> やアイコン
  • ネットワーク リンク（<NetworkLink> など）
  • グラウンド オーバーレイ（<GroundOverlay> など）
  • 3D ジオメトリや標高関連のタグ（<altitudeMode> など）
  • カメラ指定（<LookAt> など）
  • KML ファイル内で定義されたスタイル

CSV での要件

CSV ファイルの場合、以下の列名がサポートされます。記載順は優先順位を表しています。

  • latitude、longitude
  • lat、long
  • x、y
  • wkt（Well-Known Text）
  • address、city、state、zip
  • address
  • 住所情報をすべて含む単一の列（1600 Amphitheatre Parkway Mountain View, CA 94043 など）

たとえばファイルに「x」「y」「wkt」の 3 列が含まれるとします。 上のサポート対象列名リストの記載順のとおり、x と y のほうが優先度が高いため、「wkt」列に値が入っていても無視され、「x」および「y」列の値が使用されます。

その他の留意事項:

  • 指定されている名前の列は、それぞれ単独で存在する必要があります。つまり、たとえば「xy」という名前の列を設けて x 座標と y 座標の両方のデータを持たせることはできません。x 座標と y 座標はそれぞれ独立した列にしてください。
  • 列名の大文字と小文字は区別されません。
  • 指定列の記載順は自由です。たとえば「lat」列と「long」列を設ける場合、どのような順序であれ CSV ファイル内に含まれていれば問題ありません。

データ アップロード時のエラーへの対処

データセットにデータをアップロードする際、エラーが発生することがあります。このセクションでは、一般的なエラーについて解説します。

GeoJSON でのエラー

GeoJSON での一般的なエラーの例:

  • type フィールドが存在しないか、type の値が文字列になっていません。アップロードする GeoJSON データファイルでは、各 feature オブジェクトおよび geometry フィールドが、type という名前の文字列フィールドを持っている必要があります。

KML でのエラー

KML での一般的なエラーの例:

  • データファイルに、サポート外の KML 機能（前述）が含まれていると、データのインポートが失敗することがあります。

CSV でのエラー

CSV での一般的なエラーの例:

  • ジオメトリ列に値が入っていない行があります。CSV ファイルの全行で、ジオメトリ列に空でない値が入っている必要があります。ジオメトリ列とは次のようなものを指します。
    • latitude、longitude
    • lat、long
    • x、y
    • wkt
    • address、city、state、zip
    • address
    • 住所情報をすべて含む単一の列（1600 Amphitheatre Parkway Mountain View, CA 94043 など）
  • ジオメトリ列として「x」列および「y」列を使用する場合、値は経度と緯度で指定する必要がある点に注意しましょう。一般公開されているデータセットの中には、同じ「x」「y」という名前の列に、別の座標系の値が入っているものもあります。値の単位が違っていると、データセットのインポート自体が成功していても、レンダリング後のデータではデータセットの各ポイントが想定外の位置に表示される可能性があります。

データセットの作成

POST リクエストを datasets エンドポイント:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets

JSON 本文を渡す データセットを定義する必要があります。以下を行ってください:

  • データセットの displayName を指定します。displayName の値は、 一意である必要があります。

  • usage を USAGE_DATA_DRIVEN_STYLING に設定する。

例:

curl -X POST -d '{
    "displayName": "My Test Dataset", 
    "usage": "USAGE_DATA_DRIVEN_STYLING"
  }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets

レスポンスには、データセットの ID が次の形式で含まれます。 projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID 追加情報が表示されますこのデータセット ID は、 データセットの更新または変更を行います

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "createTime": "2022-08-15T17:50:00.189682Z",
  "updateTime": "2022-08-15T17:50:00.189682Z" 
}

データセットへのデータのアップロード

データセットを作成したら、Cloud Storage から Google Cloud Storage ローカル ファイルからデータセットにエクスポートできます。

Cloud Storage からデータをアップロードする

Cloud Storage からデータセットにアップロードするには、POST リクエストを データセット エンドポイントを使用して、 には、データセットの ID が含まれます。

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import

JSON リクエスト本文で次のようにします。

  • inputUri を使用して、データを含むリソースのファイルパスを指定します。 作成されます。このパスの形式は次のとおりです。 gs://GCS_BUCKET/FILE。

    リクエストを行うユーザーには、Storage オブジェクトが必要です。 閲覧者 ロール、または storage.objects.get 権限を含むその他のロール。対象 Cloud Storage へのアクセスの管理について詳しくは、 アクセス制御の概要

  • fileFormat を使用して、データのファイル形式を次のいずれかとして指定します。 FILE_FORMAT_GEOJSON（GeoJson ファイル）、FILE_FORMAT_KML（KML ファイル）、または FILE_FORMAT_CSV（CSV ファイル）。

例:

curl -X POST  -d '{
    "gcs_source":{
      "inputUri": "gs://my_bucket/my_csv_file",
      "fileFormat": "FILE_FORMAT_CSV"
    }
  }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:import

レスポンスの形式は次のとおりです。

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER"
}

ファイルからデータをアップロードする

ファイルからデータをアップロードするには、HTTP POST リクエストを データセット エンドポイントを使用して、 には、データセットの ID が含まれています。

https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import

リクエストには以下が含まれます。

  • Goog-Upload-Protocol ヘッダーが multipart に設定されている。

  • metadata プロパティ。 アップロードするデータの種類。次のいずれかです。FILE_FORMAT_GEOJSON（GeoJSON ファイル） FILE_FORMAT_KML（KML ファイル）、FILE_FORMAT_CSV（CSV ファイル）のいずれか。

    このファイルの内容の形式は次のとおりです。

    {"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}

  • GeoJSON、KML、または CSV ファイルのパスを指定する rawdata プロパティ アップロードするデータを指定します。

次のリクエストでは、curl -F オプションを使用して、2 つのファイルへのパスを指定しています。 ファイル:

curl -X POST \
  -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Goog-Upload-Protocol: multipart" \
  -F "metadata=@csv_metadata_file" \
  -F "rawdata=@csv_data_file" \
  https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:import

レスポンスの形式は次のとおりです。

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER"
}

新しいデータをデータセットにアップロードする

データセットを作成して初期データを正常にアップロードすると、 STATE_COMPLETED に設定されている。つまりデータセットは 使用できます。データセットの state を特定するには、 データセットをご覧ください。

新しいデータをデータセットにアップロードして、データの新しいバージョンを 見てみましょう。新しいデータをアップロードする際は、データのアップロードと同じ手順で操作します。 またはファイルからデータをアップロード、 アップロードする新しいデータを指定します。

新しいデータが正常にアップロードされると、次のようになります。

  • データセットの新しいバージョンの状態は STATE_COMPLETED に設定されます。

  • 新しいバージョンは「アクティブ」Pod で使用されるバージョンです。 。

アップロード中にエラーが発生した場合:

  • 新しいデータセットのバージョンの状態は、次のいずれかの状態に設定されます。

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED

  • 前のデータセットの成功バージョンは「アクティブ」のままであり、 アプリが使用しているバージョン。