데이터 세트를 만드는 과정은 두 단계로 이루어집니다.
데이터 세트를 만들도록 요청합니다.
데이터 세트에 데이터를 업로드하도록 요청합니다.
기본 요건
데이터 세트를 만들 때는 다음 조건을 충족해야 합니다.
- 표시 이름은 Google Cloud 프로젝트 내에서 고유해야 합니다.
- 표시 이름은 64바이트 미만이어야 합니다. 이러한 문자는 UTF-8로 표시되므로 일부 언어에서는 각 문자가 여러 바이트로 표시될 수 있습니다.
- 설명은 1,000바이트 미만이어야 합니다.
데이터를 업로드할 때는 다음 사항에 유의하세요.
- 지원되는 파일 형식은 CSV, GeoJSON, KML입니다.
- 지원되는 최대 파일 크기는 350MB입니다.
- 속성 열 이름은 '?_' 문자열로 시작할 수 없습니다.
- 3차원 도형은 지원되지 않습니다. WKT 형식의 'Z' 서픽스와 GeoJSON 형식의 고도 좌표가 여기에 포함됩니다.
GeoJSON 요구사항
Maps Datasets API는 최신 GeoJSON 사양을 지원합니다. Maps Datasets API는 다음 객체 유형이 포함된 GeoJSON 파일도 지원합니다.
- 도형 객체. 도형 객체는 점, 선, 다각형(구멍이 있을 수 있음)으로 설명된 공간 도형입니다.
- 지형지물 객체. 지형지물 객체에는 도형과 추가 이름/값 쌍이 포함되어 있으며, 그 의미는 애플리케이션별로 다릅니다.
- 지형지물 컬렉션. 지형지물 컬렉션은 지형지물 객체의 집합입니다.
Maps Datasets API는 좌표 참조 시스템(CRS)에 WGS84 이외의 데이터가 있는 GeoJSON 파일을 지원하지 않습니다.
GeoJSON에 대한 자세한 내용은 RFC 7946 준수를 참고하세요.
KML 요구사항
Maps Datasets API를 사용하기 위한 요구사항은 다음과 같습니다.
- 모든 URL은 파일 자체에 대한 로컬 URL 또는 상대 URL이어야 합니다.
- 점, 선, 다각형 도형이 지원됩니다.
- 모든 데이터 속성은 문자열로 간주됩니다.
- 파일 외부에 정의된 아이콘 또는
<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
라는 열이 포함되어 있는 경우,
위 목록에 표시된 지원되는 열 이름의 순서에 따라 x
및 y
의 우선순위가 더 높기 때문에 x
및 y
열의 값이 사용되고 wkt
열은 무시됩니다.
다음 사항도 적용됩니다.
- 하나의 열 이름은 하나의 열에 속해야 합니다. 즉, x와 y 좌표 데이터를 모두 포함하는
xy
라는 열은 있을 수 없습니다. x 좌표와 y 좌표는 각각 별도의 열에 있어야 합니다. - 열 이름은 대소문자를 구분하지 않습니다.
- 열 이름의 순서는 중요하지 않습니다. 예를 들어 CSV 파일에
lat
열과long
열이 포함되어 있으면 어떤 순서로든 발생할 수 있습니다.
데이터 업로드 오류 처리
데이터 세트에 데이터를 업로드할 때 이 섹션에서 설명하는 일반적인 오류 중 하나가 발생할 수 있습니다.
GeoJSON 오류
일반적인 GeoJSON 오류는 다음과 같습니다.
type
필드가 누락되었거나type
이 문자열이 아닙니다. 업로드된 GeoJSON 데이터 파일에는 각 지형지물 객체 및 도형 객체 정의의 일부로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
헤더 아래에 다른 좌표계를 사용합니다. 잘못된 단위를 사용해도 데이터 세트를 성공적으로 가져올 수 있지만 렌더링된 데이터에서 데이터 세트 포인트가 예기치 않은 위치에 표시될 수 있습니다.
데이터 세트 만들기 요청
datasets 엔드포인트에 POST
요청을 전송하여 데이터 세트를 만듭니다.
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에서 데이터 업로드
데이터 세트 ID도 포함된 데이터 세트 엔드포인트에 POST
요청을 전송하여 Cloud Storage에서 데이터 세트로 업로드합니다.
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" }
파일에서 데이터 업로드
파일에서 데이터를 업로드하려면 HTTP POST
요청을 데이터 세트 ID도 포함된 데이터 세트 엔드포인트로 전송합니다.
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
옵션을 사용하여 두 파일의 경로를 지정합니다.
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" }