Route - Post Snap To Roads

서비스:: Maps

API 버전:: 2024-07-01-preview

도로 맞춤 API는 경도 및 위도 좌표로 표현되는 GPS 지점 데이터를 허용하고 지도의 기존 도로와 일치하는 지점을 생성합니다.
"도로에 맞추기"라고 하는 이 프로세스는 도로 네트워크 뒤의 경로를 밀접하게 추적하는 일련의 개체를 생성합니다. 결과 데이터에는 이동 세그먼트와 관련된 도로 이름 및 해당 속도 제한이 포함됩니다.

또한 도로로 맞춤 API는 GPS 지점을 구체화하여 도로의 기하 도형을 준수하는 더 부드러운 경로를 만드는 보간 기능을 제공합니다. 이 기능은 특히 매핑 애플리케이션에서 자산 추적 및 데이터 시각화 향상에 유용합니다.

Important

GPS 포인트는 서로 6km 이내에 있어야 합니다.

국가/지역의 라우팅 가용성에 대한 자세한 내용은 Azure Maps 라우팅 적용 범위참조하세요.

Important

이 기능을 사용하면 미리 보기 약관에 동의하게 됩니다. 자세한 내용은 미리 보기 추가 약관 참조하세요.

POST https://atlas.microsoft.com/route/snapToRoads?api-version=2024-07-01-preview

URI 매개 변수

Name	In(다음 안에)	필수	형식	Description
api-version	query	True	string	Azure Maps API의 버전 번호입니다.

요청 헤더

Media Types: "application/geo+json"

Name	필수	형식	Description
x-ms-client-id		string	Microsoft Entra ID 보안 모델과 함께 사용할 계정을 지정합니다. Azure Maps 계정에 대한 고유 ID를 나타내며 Azure Maps 관리 평면 계정 API에서 검색할 수 있습니다. To use Microsoft Entra ID security in Azure Maps see the following articles for guidance.
Accept-Language		string	라우팅 결과를 반환해야 하는 언어입니다. 자세한 내용은 Azure Maps지역화 지원을 참조하세요.

Name

필수

형식

Description

x-ms-client-id

string

Microsoft Entra ID 보안 모델과 함께 사용할 계정을 지정합니다. Azure Maps 계정에 대한 고유 ID를 나타내며 Azure Maps 관리 평면 계정 API에서 검색할 수 있습니다. To use Microsoft Entra ID security in Azure Maps see the following articles for guidance.

Accept-Language

string

라우팅 결과를 반환해야 하는 언어입니다.

자세한 내용은 Azure Maps지역화 지원을 참조하세요.

요청 본문

Media Types: "application/geo+json"

Name	필수	형식	Description
features	True	InputSnapToRoadsFeaturesItem[]	도로 네트워크에 맞출 지점 집합입니다. 최소 2포인트에서 최대 100포인트를 가질 수 있으며, 연속된 두 포인트의 거리는 서로 6km 이내여야 합니다. Refer to RFC 7946 for details on the GeoJSON format. `Note`: API는 도로 네트워크에 스냅할 수 없는 GPS 지점에 대한 응답에서 점 개체를 반환하지 않습니다.
type	True	FeatureTypeEnum	`GeoJSON` 형식을 지정합니다. 지원되는 유일한 개체 형식은 `FeatureCollection`. For more information, see RFC 7946.
includeSpeedLimit		boolean	응답에 스냅된 지점에 대한 속도 제한 정보를 포함할지 여부를 지정합니다. 단위는 시간당 킬로미터입니다.
interpolate		boolean	도로 기하 도형을 원활하게 따르는 전체 경로 경로를 완료하기 위해 스냅된 점 사이에 추가 점을 반환할지 여부를 지정합니다. 보간된 지점은 보간된 지점에서 스냅된 점을 식별하는 데 사용할 수 있는 응답에 `isInterpolate:true`.
travelMode		SnapToRoadsTravelModeEnum	점을 맞추기 위한 라우팅 프로필을 지정합니다. 지정되지 않은 경우 기본 모드는 "운전"으로, 주행 경로에 대해 스냅된 지점을 최적화합니다.

응답

Name	형식	Description
200 OK	SnapToRoadsResponse	OK Media Types: "application/geo+json", "application/json"
Other Status Codes	MapsErrorResponse	예기치 않은 오류가 발생했습니다. Media Types: "application/geo+json", "application/json" 헤더 x-ms-error-code: string

Name

형식

Description

200 OK

SnapToRoadsResponse

Media Types: "application/geo+json", "application/json"

Other Status Codes

MapsErrorResponse

예기치 않은 오류가 발생했습니다.

Media Types: "application/geo+json", "application/json"

헤더

x-ms-error-code: string

보안

AADToken

다음은 Microsoft Entra OAuth 2.0 흐름에 . Azure 역할 기반 액세스 컨트롤과 쌍을 이루는 경우 Azure Maps REST API에 대한 액세스를 제어하는 데 사용할 수 있습니다. Azure 역할 기반 액세스 제어는 하나 이상의 Azure Maps 리소스 계정 또는 하위 리소스에 대한 액세스를 지정하는 데 사용됩니다. 모든 사용자, 그룹 또는 서비스 주체는 Azure Maps REST API에 대한 하나 이상의 권한으로 구성된 기본 제공 역할 또는 사용자 지정 역할을 통해 액세스 권한을 부여할 수 있습니다.

To implement scenarios, we recommend viewing authentication concepts. 요약하자면, 이 보안 정의는 특정 API 및 범위에 대한 액세스 제어가 가능한 개체를 통해 애플리케이션을 모델링하기 위한 솔루션을 제공합니다.

Note

This security definition requires the use of the x-ms-client-id header to indicate which Azure Maps resource the application is requesting access to. 이는 Maps 관리 API가져올 수 있습니다.
Authorization URL Azure 퍼블릭 클라우드 인스턴스와 관련이 있습니다. 소버린 클라우드에는 고유한 권한 부여 URL 및 Microsoft Entra ID 구성이 있습니다.
Azure 역할 기반 액세스 제어는 Azure Portal, PowerShell, CLI, Azure SDK 또는 REST API를 통해 Azure 관리 평면에서 구성됩니다.
Azure Maps Web SDK 사용하면 여러 사용 사례에 대한 애플리케이션의 구성 기반 설정을 사용할 수 있습니다.
Microsoft ID 플랫폼에 대한 자세한 내용은 Microsoft ID 플랫폼 개요참조하세요.

형식: oauth2
Flow: implicit
권한 부여 URL: https://login.microsoftonline.com/common/oauth2/authorize

범위

Name	Description
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

Azure Portal, PowerShell, CLI, Azure SDK 또는 REST API를 통해 Azure 관리 평면을 통해 Azure Maps 리소스를 만들 때 프로비전되는 공유 키입니다.

이 키를 사용하면 모든 애플리케이션이 모든 REST API에 액세스할 수 있는 권한이 부여됩니다. 즉, 이러한 키는 현재 발급된 계정의 마스터 키로 처리될 수 있습니다.

공개적으로 노출된 애플리케이션의 경우 이 키를 안전하게 저장할 수 있는 Azure Maps REST API의 서버-서버 액세스를 사용하는 것이 좋습니다.

형식: apiKey
In(다음 안에): header

SAS Token

공유 액세스 서명 토큰은 Azure Portal, PowerShell, CLI, Azure SDK 또는 REST API를 통해 Azure 관리 평면을 통해 Azure Maps 리소스의 SAS 나열 작업에서 만들어집니다.

이 토큰을 사용하면 모든 애플리케이션이 Azure 역할 기반 액세스 제어를 사용하여 액세스하고 특정 토큰에 사용할 만료, 속도 및 지역에 대한 세분화된 제어 권한을 부여받습니다. 즉, SAS 토큰을 사용하여 애플리케이션이 공유 키보다 더 보안이 유지되는 방식으로 액세스를 제어할 수 있습니다.

공개적으로 노출된 애플리케이션의 경우 렌더링 남용을 제한하고 정기적으로 SAS 토큰을 갱신하도록 맵 계정 리소스 허용된 원본의 특정 목록을 구성하는 것이 좋습니다.

형식: apiKey
In(다음 안에): header

예제

Successfully retrieve snap to roads points with additional parameters in the body

샘플 요청

HTTP

POST https://atlas.microsoft.com/route/snapToRoads?api-version=2024-07-01-preview

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "coordinates": [
          -122.336729,
          47.590868
        ],
        "type": "Point"
      },
      "properties": {}
    },
    {
      "type": "Feature",
      "geometry": {
        "coordinates": [
          -122.336042,
          47.601604
        ],
        "type": "Point"
      },
      "properties": {}
    }
  ],
  "includeSpeedLimit": true,
  "travelMode": "driving"
}

샘플 응답

상태 코드:: 200

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "coordinates": [
          -122.336769,
          47.590885
        ],
        "type": "Point"
      },
      "properties": {
        "inputIndex": 0,
        "isInterpolated": false,
        "name": "State Rte-99 N",
        "speedLimitInKilometersPerHour": 80
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "coordinates": [
          -122.336008,
          47.601609
        ],
        "type": "Point"
      },
      "properties": {
        "inputIndex": 1,
        "isInterpolated": false,
        "name": "State Rte-99 N",
        "speedLimitInKilometersPerHour": 80
      }
    }
  ]
}

정의

Name	Description
FeaturesItemTypeEnum	`GeoJSON` 형식을 지정합니다. 유일하게 지원되는 개체 유형은 Feature입니다. For more information, see RFC 7946.
FeatureTypeEnum	`GeoJSON` 형식을 지정합니다. 지원되는 유일한 개체 형식은 `FeatureCollection`. For more information, see RFC 7946.
GeoJsonPoint	유효한 `GeoJSON Point` 기하 도형 형식입니다. Please refer to RFC 7946 for details.
InputSnapToRoadsFeaturesItem	도로 지점에 대한 입력 스냅을 지정합니다. 기능 개체 및 추가 속성을 `GeoJSON`. Refer to RFC 7946 for details.
MapsErrorDetail	오류 세부 정보입니다.
MapsErrorResponse	실패한 작업에 대한 오류 세부 정보를 반환하는 Azure Maps API에 대한 일반적인 오류 응답입니다.
MapsInnerError	오류에 대한 현재 개체보다 더 구체적인 정보를 포함하는 개체입니다.
PointGeometry	범위 다각형을 계산해야 하는 유효한 `GeoJSON` Geometry 개체로 전달된 원점입니다. Please refer to RFC 7946 for details. `Note`: API는 요청된 원본 지점을 가장 가까운 도로 네트워크에 스냅하고 범위 계산에 사용합니다. 응답의 `center` 지점으로 반환됩니다.
SnapToRoadFeaturesItem	Geometry 개체와 경로의 추가 속성을 포함하는 GeoJSON 기능 개체입니다.
SnapToRoadsFeatureProperties	도로 속성에 스냅합니다.
SnapToRoadsRequest	이 개체는 요청 본문입니다.
SnapToRoadsResponse	이 개체는 성공적인 호출에서 반환됩니다.
SnapToRoadsTravelModeEnum	점을 맞추기 위한 라우팅 프로필을 지정합니다. 지정되지 않은 경우 기본 모드는 "운전"으로, 주행 경로에 대해 스냅된 지점을 최적화합니다.

FeaturesItemTypeEnum

열거형

GeoJSON 형식을 지정합니다. 유일하게 지원되는 개체 유형은 Feature입니다. For more information, see RFC 7946.

값	Description
Feature	`GeoJSON` Feature 개체 형식을 지정합니다.

FeatureTypeEnum

열거형

GeoJSON 형식을 지정합니다. 지원되는 유일한 개체 형식은 FeatureCollection. For more information, see RFC 7946.

값	Description
FeatureCollection	`GeoJSON` `FeatureCollection` 개체 형식을 지정합니다.

GeoJsonPoint

Object

유효한 GeoJSON Point 기하 도형 형식입니다. Please refer to RFC 7946 for details.

Name	형식	Description
coordinates	number[] (double)	`Position` 두 개 이상의 요소가 있는 숫자 배열입니다. The first two elements are longitude and latitude, precisely in that order. Altitude/Elevation is an optional third element. Please refer to RFC 7946 for details.
type	string: Point	`GeoJSON` 형식을 지정합니다. Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, FeatureCollection 등 유효한 9가지 GeoJSON 개체 형식 중 하나여야 합니다.

InputSnapToRoadsFeaturesItem

Object

도로 지점에 대한 입력 스냅을 지정합니다. 기능 개체 및 추가 속성을 GeoJSON. Refer to RFC 7946 for details.

Name	형식	Description
geometry	GeoJsonPoint: PointGeometry	유효한 `GeoJSON Point` 기하 도형 형식입니다. Please refer to RFC 7946 for details.
properties	object	속성 개체는 유효한 GeoJSON에 필요하지만 메타데이터가 도로로 스냅하는 데 사용되지 않으므로 비어 있을 수 있습니다.
type	FeaturesItemTypeEnum	`GeoJSON` 형식을 지정합니다. 유일하게 지원되는 개체 유형은 Feature입니다. For more information, see RFC 7946.

MapsErrorDetail

Object

오류 세부 정보입니다.

Name	형식	Description
code	string	서버에서 정의한 오류 코드 집합 중 하나입니다.
details	MapsErrorDetail[]	이 보고된 오류로 이어진 특정 오류에 대한 세부 정보 배열입니다.
innererror	MapsInnerError	오류에 대한 현재 개체보다 더 구체적인 정보를 포함하는 개체입니다.
message	string	사람이 읽을 수 있는 오류 표현입니다.
target	string	오류의 대상입니다.

MapsErrorResponse

Object

실패한 작업에 대한 오류 세부 정보를 반환하는 Azure Maps API에 대한 일반적인 오류 응답입니다.

Name	형식	Description
error	MapsErrorDetail	오류 세부 정보입니다.

MapsInnerError

Object

오류에 대한 현재 개체보다 더 구체적인 정보를 포함하는 개체입니다.

Name	형식	Description
code	string	오류 코드입니다.
innererror	MapsInnerError	오류에 대한 현재 개체보다 더 구체적인 정보를 포함하는 개체입니다.

PointGeometry

Object

범위 다각형을 계산해야 하는 유효한 GeoJSON Geometry 개체로 전달된 원점입니다. Please refer to RFC 7946 for details.

Note: API는 요청된 원본 지점을 가장 가까운 도로 네트워크에 스냅하고 범위 계산에 사용합니다. 응답의 center 지점으로 반환됩니다.

Name	형식	Description
coordinates	number[] (double)	`Position` 두 개 이상의 요소가 있는 숫자 배열입니다. The first two elements are longitude and latitude, precisely in that order. Altitude/Elevation is an optional third element. Please refer to RFC 7946 for details.
type	string: Point	`GeoJSON` Geometry 개체의 기하 도형 형식을 지정합니다. For more information, see RFC 7946.

SnapToRoadFeaturesItem

Object

Geometry 개체와 경로의 추가 속성을 포함하는 GeoJSON 기능 개체입니다.

Name	형식	Description
bbox	number[] (double)	경계 상자 개체로 정의된 지구의 사각형 영역입니다. 사각형의 측면은 위도 및 경도 값으로 정의됩니다. 자세한 내용은 RFC 7946, 섹션 5참조하세요. 예: "bbox": [-10.0, -10.0, 10.0, 10.0]
geometry	GeoJsonPoint: PointGeometry	유효한 `GeoJSON Point` 기하 도형 형식입니다. Please refer to RFC 7946 for details.
properties	SnapToRoadsFeatureProperties	도로 속성에 스냅합니다.
type	FeaturesItemTypeEnum	`GeoJSON` 형식을 지정합니다. 유일하게 지원되는 개체 유형은 Feature입니다. For more information, see RFC 7946.

SnapToRoadsFeatureProperties

Object

도로 속성에 스냅합니다.

Name	형식	Description
inputIndex	integer (int64)	각 맞춤 지점의 원래 점 목록에서 해당 인덱스 식별 스냅된 점만 인덱스를 반환하고 보간된 점과 구분하는 데 사용할 수 있습니다.
isInterpolated	boolean	이것이 보간된 지점인지 여부를 식별합니다.
name	string	지점이 스냅되는 도로의 이름입니다.
speedLimitInKilometersPerHour	number (double)	속도 제한(시간당 킬로미터)입니다.

SnapToRoadsRequest

Object

이 개체는 요청 본문입니다.

Name	형식	Default value	Description
features	InputSnapToRoadsFeaturesItem[]		도로 네트워크에 맞출 지점 집합입니다. 최소 2포인트에서 최대 100포인트를 가질 수 있으며, 연속된 두 포인트의 거리는 서로 6km 이내여야 합니다. Refer to RFC 7946 for details on the GeoJSON format. `Note`: API는 도로 네트워크에 스냅할 수 없는 GPS 지점에 대한 응답에서 점 개체를 반환하지 않습니다.
includeSpeedLimit	boolean	False	응답에 스냅된 지점에 대한 속도 제한 정보를 포함할지 여부를 지정합니다. 단위는 시간당 킬로미터입니다.
interpolate	boolean	False	도로 기하 도형을 원활하게 따르는 전체 경로 경로를 완료하기 위해 스냅된 점 사이에 추가 점을 반환할지 여부를 지정합니다. 보간된 지점은 보간된 지점에서 스냅된 점을 식별하는 데 사용할 수 있는 응답에 `isInterpolate:true`.
travelMode	SnapToRoadsTravelModeEnum	driving	점을 맞추기 위한 라우팅 프로필을 지정합니다. 지정되지 않은 경우 기본 모드는 "운전"으로, 주행 경로에 대해 스냅된 지점을 최적화합니다.
type	FeatureTypeEnum		`GeoJSON` 형식을 지정합니다. 지원되는 유일한 개체 형식은 `FeatureCollection`. For more information, see RFC 7946.

SnapToRoadsResponse

Object

이 개체는 성공적인 호출에서 반환됩니다.

Name	형식	Description
features	SnapToRoadFeaturesItem[]	geometry 개체 및 추가 속성을 포함하는 기능 개체를 `GeoJSON`. 자세한 내용은 RFC 7946 섹션 3.2 참조하세요.
type	FeatureTypeEnum	`GeoJSON` 형식을 지정합니다. 지원되는 유일한 개체 형식은 `FeatureCollection`. For more information, see RFC 7946.

SnapToRoadsTravelModeEnum

열거형

점을 맞추기 위한 라우팅 프로필을 지정합니다. 지정되지 않은 경우 기본 모드는 "운전"으로, 주행 경로에 대해 스냅된 지점을 최적화합니다.

값	Description
driving	포인트는 자동차에 적합한 도로에 스냅됩니다.
truck	트럭에 적합한 도로에 포인트가 스냅됩니다.

다음을 통해 공유

Route - Post Snap To Roads

URI 매개 변수

요청 헤더

요청 본문

응답

보안

AADToken

범위

subscription-key

SAS Token

예제

Successfully retrieve snap to roads points with additional parameters in the body

샘플 요청

샘플 응답

정의

FeaturesItemTypeEnum

FeatureTypeEnum

GeoJsonPoint

InputSnapToRoadsFeaturesItem

MapsErrorDetail

MapsErrorResponse

MapsInnerError

PointGeometry

SnapToRoadFeaturesItem

SnapToRoadsFeatureProperties

SnapToRoadsRequest

SnapToRoadsResponse

SnapToRoadsTravelModeEnum