データセットの作成

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

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

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

前提条件

データセットの作成:

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

データのアップロード:

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

GeoJSON での要件

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

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

Maps Datasets API は、WGS84 以外の座標参照系（CRS）のデータを持つ GeoJSON ファイルをサポートしていません。

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

データセットへのデータのアップロードをリクエストする

データセットを作成したら、Google Cloud Storage またはローカル ファイルからデータセットにデータをアップロードします。

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

Cloud Storage からデータセットにアップロードするには、データセットの ID も含めた datasets エンドポイントに POST リクエストを送信します。

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

JSON リクエストの本文:

  • inputUri を使用して、Cloud Storage のデータを含むリソースへのファイルパスを指定します。このパスの形式は gs://GCS_BUCKET/FILE です。

    リクエストを行うユーザーには、ストレージ オブジェクト閲覧者のロール、または 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"
}

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

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

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

リクエストには次のものが含まれます。

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

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

    このファイルの内容は、次の形式になります。

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