주행 시간 경로 API

PlaidCloud는 주행 시간 경로를 /rest/v1/analyze/route 아래의 두 REST 엔드포인트로 제공합니다. 출발지 주변의 주행 시간(또는 주행 거리) 폴리곤을 그리는 등시선 엔드포인트와, 직선 거리가 아닌 실제 주행 시간으로 후보 목적지의 순위를 매기는 최근접 찾기 엔드포인트입니다. 두 엔드포인트 모두 OpenStreetMap 도로 데이터(ODbL)로 빌드된 PlaidCloud의 자체 호스팅 경로 엔진에서 실행되며, 모든 결과를 출처 표시가 담긴 작은 plaidcloud 봉투로 감쌉니다.

인증 및 사용 권한

모든 경로 호출에는 다음이 필요합니다.

analyze.table.read 역할을 가진 일반 PlaidCloud 세션 또는 베어러 토큰. 프로젝트 데이터에 대한 다른 읽기 액세스를 제어하는 것과 같은 역할이며 경로 전용 역할은 없습니다.
요금제에 포함된 주행 시간 경로, 즉 테넌트에 사용 설정된 주행 시간 사용 권한. 요금제에 포함되지 않은 테넌트는 모든 호출에서 detail: "drive_time_disabled"와 함께 403을 받으며, 부분 모드나 읽기 전용 모드는 없습니다.

엔드포인트

`isochrone` — 출발지 주변의 주행 시간 폴리곤

POST /rest/v1/analyze/route/isochrone

필드	유형	참고
`origin`	`{ lat, lon }`, 필수	단일 좌표입니다. 등시선은 호출당 하나의 출발지를 받습니다
`costing`	문자열	`auto`(기본값), `truck`, `bike`, `pedestrian`
`contours_minutes`	정수 배열, 필수	원하는 등고선 링마다 항목 하나이며 각각 1~120분입니다. 호출당 최대 5개의 등고선
`costing_options.truck.height`	실수, 미터	선택 사항이며 0 초과 10 이하입니다. `truck` 비용 산정에서만 적용됩니다
`costing_options.truck.weight`	실수, 킬로그램	선택 사항이며 0 초과 100000 이하입니다. `truck` 비용 산정에서만 적용됩니다
`costing_options.truck.length`	실수, 미터	선택 사항이며 0 초과 50 이하입니다. `truck` 비용 산정에서만 적용됩니다

{
  "origin": { "lon": -122.4194, "lat": 37.7749 },
  "costing": "auto",
  "contours_minutes": [10, 20, 30]
}

응답은 경로 엔진 자체의 등시선 GeoJSON을 수정 없이 그대로 반환하며 plaidcloud 봉투가 추가됩니다.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "contour": 10, "metric": "time" },
      "geometry": { "type": "Polygon", "coordinates": [[[-122.44, 37.79], [-122.40, 37.79], [-122.40, 37.76], [-122.44, 37.76], [-122.44, 37.79]]] }
    },
    {
      "type": "Feature",
      "properties": { "contour": 20, "metric": "time" },
      "geometry": { "type": "Polygon", "coordinates": [[[-122.47, 37.81], [-122.37, 37.81], [-122.37, 37.74], [-122.47, 37.74], [-122.47, 37.81]]] }
    }
  ],
  "plaidcloud": {
    "attribution": "Routing data © OpenStreetMap contributors, licensed under ODbL (https://www.openstreetmap.org/copyright)."
  }
}

`find-nearest` — 주행 시간 기준 최근접 목적지

POST /rest/v1/analyze/route/find-nearest

필드	유형	참고
`origins`	`{ lat, lon }` 배열, 필수	출발지 1~5개
`destinations`	`{ lat, lon }` 배열, 필수	후보 1~500개. 아래 목적지 사전 필터링을 참조하십시오
`costing`	문자열	`auto`(기본값), `truck`, `bike`, `pedestrian`
`top_n`	정수	출발지마다 반환할 최근접 목적지 수입니다. 1~50, 기본값 5
`costing_options.truck.{height,weight,length}`	등시선과 동일	`truck` 비용 산정에서만 적용됩니다

{
  "origins": [{ "lon": -122.4194, "lat": 37.7749 }],
  "destinations": [
    { "lon": -122.4310, "lat": 37.7660 },
    { "lon": -122.4010, "lat": 37.7890 },
    { "lon": -122.4200, "lat": 37.7700 }
  ],
  "costing": "auto",
  "top_n": 2
}

{
  "results": [
    {
      "origin_index": 0,
      "nearest": [
        { "destination_index": 2, "destination": { "lon": -122.4200, "lat": 37.7700 }, "time_seconds": 184, "distance_km": 1.2 },
        { "destination_index": 0, "destination": { "lon": -122.4310, "lat": 37.7660 }, "time_seconds": 412, "distance_km": 2.8 }
      ]
    }
  ],
  "plaidcloud": {
    "attribution": "Routing data © OpenStreetMap contributors, licensed under ODbL (https://www.openstreetmap.org/copyright)."
  }
}

destination_index는 내부 순위의 위치가 아니라 제출한 destinations 배열에서 해당 목적지의 위치를 가리킵니다. 결과를 자신의 데이터에 다시 매핑하려면 이 값을 보관하십시오.

목적지 사전 필터링

최대 500개의 목적지를 제출할 수 있지만, 출발지 중 어느 하나로부터 직선 거리가 가장 가까운 50개만 실제 주행 시간 경로 계산에 전달됩니다. 50개를 초과하여 제출하면 PlaidCloud는 남은 목적지를 실제 주행 시간으로 순위를 매기기 전에 직선(대원) 사전 필터로 범위를 좁힙니다. 따라서 지도상으로는 가깝지만 직선 거리 기준선의 바깥쪽에 있는 목적지는 주행 시간이 계산되기 전에 제외될 수 있습니다. 목적지 집합이 이미 50개 미만이면 모든 후보가 경로 계산에 포함되며 이 필터는 영향을 주지 않습니다. top_n도 같은 이유로 50으로 제한됩니다. 경로 단계가 고려하는 후보보다 많은 후보를 반환할 수 없기 때문입니다.

비용 산정 모드

auto, truck, bike, pedestrian이 지원됩니다. truck 비용 산정에서는 차량 치수 costing_options.truck.height, .weight, .length로 경로를 제한할 수도 있으므로, 낮은 다리나 중량 제한 도로를 피하는 경로를 만들 수 있습니다. 위험물 경로는 지원되지 않습니다. 두 엔드포인트 모두 위험물 매개변수가 없으며, truck 비용 산정을 통해 간접적으로도 사용할 수 없습니다. 이 API는 위험물 규제를 우회하는 경로를 산정하지 않으므로 위험물 규제 화물 운송에는 의존하지 마십시오.

오류

상태	의미
`403`	`analyze.table.read` 역할이 없거나 요금제에 주행 시간 사용 권한이 포함되어 있지 않습니다
`422`	요청 필드의 유효성 검사에 실패했습니다. 예를 들어 등고선이 5개를 초과하거나, 등고선이 1~120분 범위를 벗어나거나, 출발지가 5개를 초과하거나, 트럭 치수가 범위를 벗어난 경우입니다
`503 route_unavailable`	경로 엔진에 연결할 수 없거나, 시간 초과되었거나, 오류를 반환했습니다. 또는 테넌트의 동시 요청 허용량이 이미 사용 중이었습니다(제한 참조)

여기서의 503은 원시 5xx도 아니고 무한정 대기하는 것도 아닙니다. 경로 엔진에 대한 모든 호출은 제한된 시간 초과 아래에서 실행되므로, 느리거나 응답이 없는 업스트림은 요청을 계속 열어 두지 않고 503으로 빠르게 나타납니다.

제한

테넌트당 동시성은 동시 요청 2개로 제한됩니다. 이는 요금제별 할당량이 아니라 미리 보기를 뒷받침하는 공유 경로 풀을 반영한 것입니다. 같은 테넌트의 세 번째 동시 요청은 처음 두 요청 중 하나가 끝날 때까지 503 route_unavailable을 받습니다. 대기열은 없으므로 잠시 대기한 후 다시 시도하십시오.
응답 캐싱이 없습니다. 모든 호출은 현재 경로 인덱스를 기준으로 실시간으로 응답됩니다.
좌표는 로그에 기록되지 않습니다. 실패 로그에는 요청 경로와 오류 유형만 기록되며 제출한 출발지, 목적지 또는 기타 위치 데이터는 기록되지 않습니다.
경로 데이터는 OpenStreetMap 도로 데이터(ODbL)로 빌드되므로 PlaidCloud 지오코딩 API에 적용되는 적용 범위와 최신성에 관한 주의 사항이 여기에도 동일하게 적용됩니다. 지도가 잘 만들어진 지역에서는 강력하지만 다른 지역에서는 편차가 더 크며, 버전이 관리되는 상용 데이터셋이 아니라 커뮤니티가 지속적으로 편집합니다.
경로 결과나 주행 시간 영역을 최종 사용자에게 표시하는 경우 plaidcloud.attribution 문자열(또는 동등한 OSM 출처 표시)을 함께 표시하십시오. 지오코딩 결과에 적용되는 ODbL 의무가 경로 결과에도 동일하게 적용됩니다.