Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

선택한 경로 만들기

이 페이지에서는 다음 섹션에서 Roads Selection API를 사용하여 경로를 만들고 맞춤 속성을 추가하는 방법을 설명합니다.

경로 만들기: create 엔드포인트를 사용하여 단일 경로를 정의합니다.
경로 일괄 생성: batchCreate 엔드포인트를 사용하여 단일 요청에서 여러 경로를 정의합니다.
중간 경유지가 있는 경로 만들기: 최대 25개의 중간 경유지가 있는 경로를 정의합니다.
커스텀 경로 속성 활용: 조직 목적으로 경로에 최대 10개의 커스텀 키-값 쌍을 추가합니다.

경로 만들기

경로를 만들려면 POST 요청을 create 엔드포인트에 보냅니다.

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID

요청 본문은 SelectedRoute 리소스를 정의하는 JSON 객체여야 합니다. 이 객체는 다음 정보를 지정합니다.

다음 정보가 포함된 dynamicRoute 객체:
- 선택한 경로의 origin입니다.
- 선택한 경로의 destination입니다.
- 경로의 모든 intermediates(경유지라고도 함)입니다.
고유한 selectedRouteId입니다. 이 값은 4~63자(영문 기준)여야 하며 유효한 문자는 a-z, A-Z, 0-9, -, _입니다. ID를 제공하지 않으면 시스템에서 선택한 경로에 대한 고유 ID를 생성합니다.

고정 경로 만들기 (기본값)

경로는 기본적으로 고정 경로로 생성되며 실시간 교통정보 없이 생성 시 계산된 정적 경로 도형 (routes_status BigQuery 테이블로 내보냄)과 일관되게 유지됩니다. 이렇게 하면 교통 상황 변경의 영향을 받지 않고 일관된 교통정보 데이터 모니터링이 보장됩니다.

요청 본문에서 dynamicRouting 불리언 필드를 설정하여 경로가 고정 (false, 기본값)인지 동적 (true)인지 지정할 수 있습니다.

다음 코드 샘플은 고정 경로를 create하는 POST 요청의 구조를 보여줍니다.

curl -X POST -d '
    {
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE,
          "longitude": ORIGIN_LONGITUDE
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE,
          "longitude": DESTINATION_LONGITUDE
        }
      }
    }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/"\
"PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

성공하면 API가 SelectedRoute 리소스를 반환합니다. 응답에는 name 필드의 selectedRouteId가 포함됩니다. 이 selectedRouteId를 사용하여 SelectedRoute 리소스를 검색하거나 삭제할 수 있습니다.

다음 코드 샘플은 성공적인 create 엔드포인트 응답의 구조를 보여줍니다.

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": ORIGIN_LATITUDE,
      "longitude": ORIGIN_LONGITUDE
    },
    "destination": {
      "latitude": DESTINATION_LATITUDE,
      "longitude": DESTINATION_LONGITUDE
    }
  },
  "createTime": "CREATE_TIME",
  "state": "STATE_VALIDATING",
  "dynamicRouting": false
}

동적 경로 만들기

원하는 경우 dynamicRouting 필드를 true로 설정하여 동적 경로를 만들 수 있습니다. Google의 경로 플랫폼은 매번 최적의 경로를 찾기 때문에 교통 상황에 따라 경로 도형이 변경될 수 있습니다.

다음 코드 샘플은 동적 경로를 create하는 POST 요청의 구조를 보여줍니다.

curl -X POST -d '
    {
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE,
          "longitude": ORIGIN_LONGITUDE
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE,
          "longitude": DESTINATION_LONGITUDE
        }
      },
      "dynamicRouting": true
    }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/"\
"PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

다음 코드 샘플은 성공적인 create 엔드포인트 응답의 구조를 보여줍니다.

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": ORIGIN_LATITUDE,
      "longitude": ORIGIN_LONGITUDE
    },
    "destination": {
      "latitude": DESTINATION_LATITUDE,
      "longitude": DESTINATION_LONGITUDE
    }
  },
  "createTime": "CREATE_TIME",
  "state": "STATE_VALIDATING",
  "dynamicRouting": true
}

중간 경유지가 있는 경로 만들기

출발지와 목적지 사이의 특정 지점을 통과하는 경로를 만들려면 요청 본문의 dynamicRoute 객체 내에 intermediates 배열을 포함합니다. intermediates 배열의 각 요소는 latitude 및 longitude로 정의된 경유지입니다. 경로에는 최대 25개의 경유지가 포함될 수 있습니다.

다음 코드 샘플은 중간 경유지가 있는 SelectedRoute를 만드는 방법을 보여줍니다.

curl -X POST -d '
    {
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE,
          "longitude": ORIGIN_LONGITUDE
        },
        "intermediates": [
          {"latitude": INTERMEDIATE_LATITUDE_1, "longitude": INTERMEDIATE_LONGITUDE_1},
          {"latitude": INTERMEDIATE_LATITUDE_2, "longitude": INTERMEDIATE_LONGITUDE_2},
          {"latitude": INTERMEDIATE_LATITUDE_3, "longitude": INTERMEDIATE_LONGITUDE_3}
        ],
        "destination": {
          "latitude": DESTINATION_LATITUDE,
          "longitude": DESTINATION_LONGITUDE
        }
      }
    }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/"\
"PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

커스텀 경로 속성 활용

Roads Management Insights 내에서 경로 관리 및 데이터 분석을 개선하기 위해 SelectedRoute 객체에는 routeAttributes 필드가 포함되어 있습니다.

routeAttributes 필드를 사용하여 개별 경로의 자체 맞춤 속성을 정의합니다. 여기서 각 속성은 키-값 쌍입니다. 경로당 최대 25개의 커스텀 키-값 쌍을 제공할 수 있습니다.

이러한 속성은 특정 경로를 식별하거나 필요에 따라 기준에 따라 경로를 그룹화하는 데 유용합니다.

다음은 사용할 수 있는 경로 속성의 예입니다.

"road_classification": "highway"
"maintenance_zone": "north_district"
"event_id": "marathon_2024"
"pavement_type": "asphalt"

routeAttributes 필드를 정의할 때는 다음 가이드라인을 따르세요.

키는 프리픽스 goog로 시작할 수 없습니다.
각 키와 각 값의 길이는 100자(영문 기준)를 초과할 수 없습니다.

그런 다음 도로 관리 정보 내에서 이러한 커스텀 routeAttributes를 다음과 같은 방법으로 사용할 수 있습니다.

Pub/Sub 알림 필터링: Pub/Sub 구독에 필터를 설정하여 특정 속성 키 및 해당 값과 일치하거나 일치하지 않는 경로에 대한 업데이트만 수신할 수 있습니다.
BigQuery 분석 미세 조정: BigQuery 테이블에서 이러한 속성을 사용하여 속성 값을 기준으로 특정 경로를 필터링할 수 있습니다. 또한 보다 타겟팅된 데이터 분석을 위해 특정 속성 키로 경로를 그룹화할 수 있습니다.

다음 코드 샘플은 커스텀 routeAttributes로 SelectedRoute를 만드는 방법을 보여줍니다.

curl -X POST -d '
    {
    "dynamicRoute": {
      "origin": {
        "latitude": ORIGIN_LATITUDE,
        "longitude": ORIGIN_LONGITUDE
      },
      "destination": {
        "latitude": DESTINATION_LATITUDE,
        "longitude": DESTINATION_LONGITUDE
      }
    },
    "routeAttributes": {
      "ATTRIBUTE_KEY": "ATTRIBUTE_VALUE"
    }
  }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/"\
"PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

경로 일괄 생성

단일 요청으로 여러 경로를 만들려면 batchCreate 엔드포인트를 사용합니다. 이 엔드포인트를 사용하면 한 번의 호출로 최대 1,000개의 경로를 정의할 수 있습니다.

batchCreate 엔드포인트에 POST 요청을 보냅니다.

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate

URL은 gRPC 트랜스코딩 문법을 사용합니다.

요청 본문은 requests 배열을 포함하는 JSON 객체여야 합니다. 이 배열 내의 각 객체는 개별 SelectedRoute 리소스를 정의하는 CreateSelectedRouteRequest입니다.

다음 코드 샘플은 batchCreate 엔드포인트에 대한 POST 요청의 구조를 보여줍니다.

curl -X POST -d '
    {
      "requests": [
        {
          "selectedRoute": {
            "dynamicRoute": {
              "origin": {
                "latitude": ORIGIN_LATITUDE_1,
                "longitude": ORIGIN_LONGITUDE_1
              },
              "destination": {
                "latitude": DESTINATION_LATITUDE_1,
                "longitude": DESTINATION_LONGITUDE_1
              }
            }
          },
          "selectedRouteId": "route-one"
        },
        {
          "selectedRoute": {
            "dynamicRoute": {
              "origin": {
                "latitude": ORIGIN_LATITUDE_2,
                "longitude": ORIGIN_LONGITUDE_2
              },
              "destination": {
                "latitude": DESTINATION_LATITUDE_2,
                "longitude": DESTINATION_LONGITUDE_2
              }
            }
          },
          "selectedRouteId": "route-two"
        }
      ]
    }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/"\
"PROJECT_NUMBER/selectedRoutes:batchCreate"

성공하면 API는 생성된 SelectedRoute 리소스 배열이 포함된 응답을 반환합니다.

다음 코드 샘플은 batchCreate 엔드포인트 응답의 구조를 보여줍니다.

{
  "selectedRoutes": [
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_1,
          "longitude": ORIGIN_LONGITUDE_1
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_1,
          "longitude": DESTINATION_LONGITUDE_1
        }
      },
      "createTime": "CREATE_TIME_1",
      "state": "STATE_VALIDATING",
      "dynamicRouting": false
    },
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_2,
          "longitude": ORIGIN_LONGITUDE_2
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_2,
          "longitude": DESTINATION_LONGITUDE_2
        }
      },
      "createTime": "CREATE_TIME_2",
      "state": "STATE_VALIDATING",
      "dynamicRouting": false
    }
  ]
}