주요 개념

등시선을 생성하려면 API에 출발지, 이동 수단(예: 운전, 이륜차, 자전거, 도보), 시간 제한을 제공합니다. 경로 설정 환경설정과 결과 다각형의 시각적 모양을 조정할 수도 있습니다.

이동 수단

필수 travelMode (travel_mode) 파라미터를 사용하여 이동 수단을 지정합니다.

• DRIVE: 게시된 제한 속도, 도로 계층 구조, 회전 페널티, (선택사항) 실시간 교통 상황을 사용하여 주행 가능한 도로를 따라 승용차의 도달 가능성을 계산합니다.
• TWO_WHEELER: 모드별 도로 접근 규칙과 고속 도로에서 DRIVE보다 낮은 모델링 속도를 사용하여 이륜 자동차 (예: 오토바이 또는 스쿠터)의 도달 가능성을 계산합니다. 따라서 TWO_WHEELER 등시선은 일반적으로 BICYCLE보다 크지만 고속도로를 따라 DRIVE보다 작은 영역을 포함합니다.
• BICYCLE: 자전거 이용자가 자전거로 접근 가능한 도로, 자전거 전용도로, 공유 경로를 따라 이동할 수 있는 도달범위를 계산합니다. 속도는 도로 유형과 경사에 따라 조정되며, 고속도로와 통제된 접근이 가능한 고속도로는 제외됩니다.
• WALK: 보도, 보행자 전용 도로, 산책로, 보행자 접근 가능 도로를 따라 보행자의 도보/차량 접근성을 계산하며, 경사에 따라 보행 속도가 조정됩니다. 도보 이동은 일방통행 차량 제한을 무시합니다.

기간

서비스에 제공하는 기본 제약조건은 travelDuration(travel_duration)입니다. 이는 계산 기간을 정의합니다.

• 최소 및 최대 길이: 길이는 "1s" (1초) 이상이어야 합니다. 0 ("0s"), 음수 기간, 1초 미만의 초 단위 기간 (예: "0.5s")은 400 INVALID_ARGUMENT 오류를 반환합니다. API는 DRIVE 및 TWO_WHEELER 모드의 경우 최대 이동 시간 3,600초 (1시간), WALK 및 BICYCLE 모드의 경우 7,200초 (2시간)를 지원합니다.
• 최소 다각형 하한: API는 도달한 도로 세그먼트를 공간 그리드 셀로 변환하므로, 매우 짧은 시간은 스냅된 출발지 주변의 그리드 셀을 포함하는 작은 다각형을 반환합니다.
• 성능: 계산 시간은 요청된 기간과 선택한 이동 수단에 따라 달라집니다. 1시간 운전 등시선은 1시간 도보 등시선보다 훨씬 더 넓은 지리적 영역과 도로망을 포함하므로 운전 요청의 지연 시간이 더 길어집니다.
• 형식 지정: API는 google.protobuf.Duration를 사용하므로 기간은 정수가 아닌 "s"로 끝나는 문자열 (예: "3600s")로 형식을 지정해야 합니다.

출발지 및 도로 스냅

다음 두 가지 방법으로 등시선의 시작점을 지정할 수 있습니다.

• 좌표 (location): 위도 및 경도 쌍입니다. latitude ([-90, 90]) 및 longitude ([-180, 180])를 모두 제공합니다. 둘 중 하나를 생략하면 API는 이를 0.0로 처리하여 적도 또는 본초 자오선에 지점을 배치합니다. 둘 다 생략하거나 ({}) (0, 0)를 전송하면 API에서 400 INVALID_ARGUMENT 오류를 반환합니다.
• 장소 ID (place): Google 지도에 있는 특정 장소의 고유 식별자입니다. 장소 ID를 제공하면 서비스에서 장소를 중심 좌표로 변환하고 해당 지점을 가장 가까운 도로에 맞춥니다. places/로 시작하는 리소스 이름 형식을 사용합니다 (예: places/ChIJIQBpAG2ahYAR_6128GcTUEo). places/ 접두사가 없는 단순 장소 ID도 허용됩니다. 장소 ID에 대한 자세한 내용은 장소 ID를 참고하세요.

입력 방법과 관계없이 API는 공원이나 건물 내부와 같이 도로에 있지 않은 정확한 물리적 지점의 이동 시간을 계산하지 않습니다. 이러한 상황을 처리하기 위해 서비스는 도로 스냅을 사용합니다. 도로 맞추기에는 다음과 같은 기능이 있습니다.

• 스마트 스냅: 서비스가 출발 지점을 가장 가까운 이동 가능한 도로 세그먼트에 스냅하려고 시도합니다.
• 모드 인식: 맞추기 로직은 travel_mode를 고려합니다. DRIVE 또는 TWO_WHEELER를 요청하면 API는 보행자 전용 경로를 무시하고 가장 가까운 주행 가능한 도로를 찾습니다. WALK을 요청하면 API는 도보 경로와 인도를 우선시합니다.
• 실패 사례: API가 출발지의 최대 스냅 거리 (약 200미터, WALK 및 BICYCLE의 경우 더 짧음) 내에서 적절한 도로 구간을 찾을 수 없는 경우 API는 404 NOT_FOUND 오류를 반환합니다. 대형 지형지물 (예: 공원, 캠퍼스, 전망대)은 이동 수단에서 사용할 수 있는 가장 가까운 도로에서 스냅 거리보다 먼 장소 ID 중심점을 가질 수 있습니다. 이 경우 도로 입구의 명시적 location 좌표를 대신 전달하세요.

이동 방향 (인바운드 또는 아웃바운드)

travelDirection (travel_direction) 매개변수를 사용하여 인바운드 및 아웃바운드 연결 가능성을 모두 계산할 수 있습니다.

• FROM (출발): 지정된 시간 제한 내에 출발지에서 도달할 수 있는 영역을 계산합니다. 이는 배송 구역 또는 서비스 범위와 같은 사용 사례에 적합합니다.
• TO (인바운드): 지정된 시간 제한 내에 출발지로 이동할 수 있는 영역을 계산합니다. 이는 직원이 중앙 사무실에 도달하기 위해 통근할 수 있는 위치와 같은 집수 구역을 결정하는 데 적합합니다.

교통 상황 인식

routingPreference (routing_preference) 매개변수를 사용하여 교통정보 데이터가 생성된 다각형에 미치는 영향을 제어합니다.

• TRAFFIC_UNAWARE (기본값): 자유 흐름 속도 제한 및 도로 계층 구조를 사용하여 등시선 다각형을 생성합니다. 이렇게 하면 시간에 따라 변동되지 않는 결정론적 형태가 생성됩니다. 이 매개변수는 일반 분석 또는 기준 시나리오 계획에 적합합니다.
• TRAFFIC_AWARE: 요청이 처리되는 정확한 시점의 실시간 교통 상황을 사용하여 등시선을 계산합니다 (v1에서는 커스텀 미래 또는 과거 출발 또는 도착 타임스탬프를 구성할 수 없음). 이로 인해 혼잡한 시간대에는 도달 가능한 영역이 축소되고 사용량이 적은 시간대에는 확장됩니다. 교통 흐름이 원활하거나 사용량이 적은 시간대에는 TRAFFIC_AWARE 및 TRAFFIC_UNAWARE가 거의 동일한 다각형을 반환할 수 있습니다. 참고: 트래픽 인식 라우팅은 travelMode가 DRIVE 또는 TWO_WHEELER로 설정된 경우에만 지원됩니다.

스무딩 및 충실도

polygonFidelity (polygon_fidelity) 및 enableSmoothing(enable_smoothing) 매개변수를 사용하여 출력 다각형의 모양과 정밀도를 맞춤설정할 수 있습니다. 이러한 옵션은 독립적이지만 함께 작동하여 최종 형태를 결정합니다.

• polygonFidelity: 도달 가능한 경계를 근사화하는 데 사용되는 공간 그리드 셀 해상도를 제어합니다.

  • LOW: 가장 큰 그리드 셀 (수백 미터 너비)을 사용합니다. 꼭짓점이 적고 내부 간격이 없는 넓은 영역을 커버하는 데 가장 적합하며, 이로 인해 좁은 도로를 따라 도달 가능한 영역을 과대평가할 수 있는 일반화된 형태가 생성됩니다.
  • MEDIUM: 정밀도와 꼭짓점 수의 균형을 맞춥니다.
  • HIGH: 가장 작은 그리드 셀 (가로 약 100~150미터)을 사용합니다. 도달한 도로망에 더 가깝게 맞지만 도로망이 희소한 내부 구멍이 생길 수 있습니다.
  • POLYGON_FIDELITY_UNSPECIFIED: 지정하지 않으면 서비스에서 이동 수단과 소요 시간에 따라 자동으로 해상도를 선택합니다. 소요 시간이 짧은 경우와 WALK의 경우 더 세밀한 셀을 사용하고 소요 시간이 긴 경우 더 거친 셀을 사용합니다. 여러 기간 또는 이동 수단에 걸쳐 등시선을 비교하려면 polygonFidelity를 명시적으로 설정합니다.

    

• enableSmoothing: 충실도로 정의된 그리드 셀의 계단식 가장자리를 반올림할지 여부를 제어합니다.

  • false (원시): 기본값입니다. 그리드 정렬 경계를 반환합니다. 가장자리가 그리드 셀을 따라 계단식으로 표시됩니다. 엄격한 다각형 내 점 테스트와 같은 분석 정확도에 가장 적합합니다.
  • true (평활화): 각 링의 면적을 대략적으로 유지하면서 시각적 지도 표시를 위해 날카로운 모서리를 둥글게 처리합니다. 경계는 더 이상 그리드 셀을 따르지 않습니다.