Route - Post Snap To Roads

Usługa:: Maps

Wersja interfejsu API:: 2025-01-01

Interfejs API przyciągania do dróg akceptuje dane punktów GPS, reprezentowane jako współrzędne geograficzne i współrzędne geograficzne oraz generuje punkty, które są zgodne z istniejącymi drogami na mapie. Ten proces, znany jako "przyciąganie do dróg", tworzy serię obiektów, które śledzą ścieżkę ściśle po sieci drogowej. Wynikowe dane obejmują nazwy dróg i ich odpowiednie ograniczenia prędkości, odpowiednie dla przechodzonych segmentów.

Ponadto interfejs API Snap to Roads oferuje funkcję interpolacji, która uściśli punkty GPS, aby stworzyć łagodniejszą trasę, która jest zgodna z geometrią drogi. Ta funkcja jest szczególnie przydatna w przypadku śledzenia zasobów i ulepszania wizualizacji danych w aplikacjach mapowania.

Ważna

Punkty GPS muszą znajdować się w odległości nie większej niż 6 kilometrów od siebie.

Aby uzyskać informacje o dostępności routingu w krajach/regionach, zobacz Azure Maps pokrycie routingu.

POST {endpoint}/route/snapToRoads?api-version=2025-01-01

Parametry identyfikatora URI

Nazwa	W	Wymagane	Typ	Opis
endpoint	path	True	string (uri)	Nazwa hosta usługi Azure Maps. Użyj `https://atlas.microsoft.com` do Azure chmury publicznej. Aby skupić się na konkretnej Azure Maps geografii lub chmurze suwerennej, zobacz Azure Maps zakres geograficzny.
api-version	query	True	string minLength: 1	Wersja interfejsu API do użycia dla tej operacji.

Nagłówek żądania

Media Types: "application/geo+json"

Nazwa	Wymagane	Typ	Opis
x-ms-client-id		string	Wskazuje konto przeznaczone do użycia z modelem bezpieczeństwa Microsoft Entra ID. Ten unikalny identyfikator konta Azure Maps można uzyskać z API Azure Maps Account API na płaszczyźnie zarządzania. Więcej informacji na temat korzystania z Microsoft Entra ID zabezpieczeń w Azure Maps można znaleźć w Manage authentication in Azure Maps.
Accept-Language		string	Język, w którym powinny być zwracane wyniki routingu. Więcej informacji można znaleźć w Wsparcie lokalizacji w Azure Maps.

Nazwa

Wymagane

Typ

Opis

x-ms-client-id

string

Wskazuje konto przeznaczone do użycia z modelem bezpieczeństwa Microsoft Entra ID. Ten unikalny identyfikator konta Azure Maps można uzyskać z API Azure Maps Account API na płaszczyźnie zarządzania. Więcej informacji na temat korzystania z Microsoft Entra ID zabezpieczeń w Azure Maps można znaleźć w Manage authentication in Azure Maps.

Accept-Language

string

Język, w którym powinny być zwracane wyniki routingu.

Więcej informacji można znaleźć w Wsparcie lokalizacji w Azure Maps.

Treść żądania

Media Types: "application/geo+json"

Nazwa	Wymagane	Typ	Opis
features	True	InputSnapToRoadsFeaturesItem[]	Zestaw punktów do przyciągania do sieci drogowej. Możesz mieć minimum 2 punkty i maksimum 5000 punktów, a dwa kolejne punkty muszą znajdować się w odległości do 6 kilometrów od siebie, a łączny dystans drogowy nie może przekraczać 100 kilometrów. Zapoznaj się z dokumentem RFC 7946 , aby uzyskać szczegółowe informacje na temat formatu GeoJSON. `Note`: interfejs API nie zwróci obiektu punktu w odpowiedzi dla punktu GPS, którego nie można przyciągnął do sieci drogowej.
type	True	FeatureTypeEnum	Określa typ `GeoJSON`. Jedynym obsługiwanym typem obiektu jest `FeatureCollection`. Aby uzyskać więcej informacji, zobacz RFC 7946.
includeSpeedLimit		boolean	Określa, czy należy uwzględnić informacje o limicie prędkości dla przyciąganych punktów w odpowiedzi. Jednostka jest wyrażona w kilometrach na godzinę.
interpolate		boolean	Określa, czy zwracać dodatkowe punkty między przyciętymi punktami, aby ukończyć pełną ścieżkę trasy, która płynnie podąża za geometrią drogi. Punkty interpolowane będą miały `isInterpolate:true` w odpowiedzi, która może służyć do identyfikowania punktów przyciąganych z punktów interpolowanych.
travelMode		SnapToRoadsTravelModeEnum	Określa profil routingu do przyciągania punktów. Jeśli nie określono, domyślny tryb to "jazda", który optymalizuje przyciągane punkty dla tras jazdy.

Odpowiedzi

Nazwa	Typ	Opis
200 OK	SnapToRoadsResponse	Żądanie zakończyło się pomyślnie. Media Types: "application/geo+json", "application/json"
Other Status Codes	MapsErrorResponse	Nieoczekiwana odpowiedź na błąd. Media Types: "application/geo+json", "application/json"

Nazwa

Typ

Opis

200 OK

SnapToRoadsResponse

Żądanie zakończyło się pomyślnie.

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

Other Status Codes

MapsErrorResponse

Nieoczekiwana odpowiedź na błąd.

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

Zabezpieczenia

AadToken

Są to przepływy Microsoft Entra OAuth 2.0. W połączeniu z Azure zarządzaniem dostępem opartym na rolach może być używany do kontroli dostępu do Azure Maps API REST. Kontrola dostępu oparta na rolach Azure służy do wyznaczania dostępu do jednego lub więcej kont zasobów lub podzasobów Azure Maps. Każdy użytkownik, grupa lub jednostka usługi mogą mieć dostęp za pośrednictwem wbudowanej roli lub roli niestandardowej składającej się z co najmniej jednego uprawnienia do interfejsów API REST usługi Azure Maps.

Aby zaimplementować scenariusze, zalecamy wyświetlenie koncepcji uwierzytelniania . Podsumowując, ta definicja zabezpieczeń zawiera rozwiązanie do modelowania aplikacji za pośrednictwem obiektów, które mogą kontrolować dostęp do określonych interfejsów API i zakresów.

Note

Ta definicja zabezpieczeń wymaga użycia nagłówka x-ms-client-id w celu wskazania, do którego zasobu usługi Azure Maps aplikacja żąda dostępu. Można to uzyskać za pomocą interfejsu API zarządzania usługami Maps.
Authorization URL jest specyficzna dla wystąpienia chmury publicznej platformy Azure. Suwerenne chmury mają unikalne adresy URL autoryzacji oraz konfiguracje Microsoft Entra ID.
Kontrola dostępu oparta na rolach platformy Azure jest konfigurowana na podstawie płaszczyzny zarządzania platformy Azure za pośrednictwem witryny Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów AZURE SDK lub interfejsów API REST.
Użycie zestawu Web SDK usługi Azure Maps umożliwia skonfigurowanie aplikacji na podstawie konfiguracji dla wielu przypadków użycia.
Aby uzyskać więcej informacji na temat platformy tożsamości firmy Microsoft, zobacz Platforma tożsamości Microsoft overview.

Typ: oauth2
Flow: implicit
Adres URL autoryzacji: https://login.microsoftonline.com/common/oauth2/authorize

Zakresy

Nazwa	Opis
https://atlas.microsoft.com/.default

subscription-key

Jest to klucz wspólny aprowizowany podczas tworzenie konta usługi Azure Maps w witrynie Azure Portal lub przy użyciu programu PowerShell, interfejsu wiersza polecenia, zestawów SDK platformy Azure lub interfejsu API REST.

Za pomocą tego klucza każda aplikacja może uzyskiwać dostęp do całego interfejsu API REST. Innymi słowy, ten klucz może służyć jako klucz główny na koncie, w którym są wystawiane.

W przypadku publicznie uwidocznionych aplikacji zalecamy użycie poufnych aplikacji klienckich podejście do uzyskiwania dostępu do interfejsów API REST usługi Azure Maps, aby klucz mógł być bezpiecznie przechowywany.

Typ: apiKey
W: header

SAS Token

Jest to token sygnatury dostępu współdzielonego tworzony na podstawie operacji List SAS na zasobie usługi Azure Maps za pośrednictwem płaszczyzny zarządzania platformy Azure za pośrednictwem witryny Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów AZURE SDK lub interfejsów API REST.

Dzięki temu tokenowi każda aplikacja jest autoryzowana do uzyskiwania dostępu za pomocą kontroli dostępu opartej na rolach platformy Azure i szczegółowej kontroli wygaśnięcia, szybkości i regionów użycia dla określonego tokenu. Innymi słowy, token SAS może służyć do umożliwienia aplikacjom kontrolowania dostępu w sposób bardziej zabezpieczony niż klucz wspólny.

W przypadku publicznie uwidocznionych aplikacji zalecamy skonfigurowanie określonej listy dozwolonych źródeł w zasobie Mapowanie konta w celu ograniczenia nadużyć renderowania i regularnego odnawiania tokenu SAS.

Typ: apiKey
W: header

Przykłady

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

Przykładowe żądanie

HTTP

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

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

Przykładowa odpowiedź

Kod stanu:: 200

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

Definicje

Nazwa	Opis
FeaturesItemTypeEnum	Określa typ `GeoJSON`. Jedynym obsługiwanym typem obiektu jest Funkcja. Aby uzyskać więcej informacji, zobacz RFC 7946.
FeatureTypeEnum	Określa typ `GeoJSON`. Jedynym obsługiwanym typem obiektu jest `FeatureCollection`. Aby uzyskać więcej informacji, zobacz RFC 7946.
GeoJsonObjectType	Określa typ `GeoJSON`. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.
GeoJsonPoint	Prawidłowy typ geometrii `GeoJSON Point`. Aby uzyskać szczegółowe informacje, zobacz RFC 7946.
InputSnapToRoadsFeaturesItem	Określa przyciąganie danych wejściowych do punktów dróg. `GeoJSON` obiekt funkcji i dodatkowe właściwości. Szczegółowe informacje można znaleźć w dokumencie RFC 7946 .
MapsErrorDetail	Szczegóły błędu.
MapsErrorResponse	Typowa odpowiedź na błędy dla API Azure Maps do zwracania szczegółów błędu dla nieudanych operacji.
MapsInnerError	Obiekt zawierający bardziej szczegółowe informacje niż bieżący obiekt o błędzie.
SnapToRoadFeaturesItem	Obiekt funkcji GeoJSON, który zawiera obiekt Geometry i dodatkowe właściwości trasy.
SnapToRoadsFeatureProperties	Przyciągaj do właściwości Drogi.
SnapToRoadsRequest	Ten obiekt jest treścią żądania.
SnapToRoadsResponse	Ten obiekt jest zwracany z pomyślnego wywołania.
SnapToRoadsTravelModeEnum	Określa profil routingu do przyciągania punktów. Jeśli nie określono, domyślny tryb to "jazda", który optymalizuje przyciągane punkty dla tras jazdy.

FeaturesItemTypeEnum

Wyliczenie

Określa typ GeoJSON. Jedynym obsługiwanym typem obiektu jest Funkcja. Aby uzyskać więcej informacji, zobacz RFC 7946.

Wartość	Opis
Feature	Określa typ obiektu funkcji `GeoJSON`.

FeatureTypeEnum

Wyliczenie

Określa typ GeoJSON. Jedynym obsługiwanym typem obiektu jest FeatureCollection. Aby uzyskać więcej informacji, zobacz RFC 7946.

Wartość	Opis
FeatureCollection	Określa typ obiektu `GeoJSONFeatureCollection`.

GeoJsonObjectType

Wyliczenie

Określa typ GeoJSON. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.

Wartość	Opis
Point	`GeoJSON Point` geometrii.
MultiPoint	`GeoJSON MultiPoint` geometrii.
LineString	`GeoJSON LineString` geometrii.
MultiLineString	`GeoJSON MultiLineString` geometrii.
Polygon	`GeoJSON Polygon` geometrii.
MultiPolygon	`GeoJSON MultiPolygon` geometrii.
GeometryCollection	`GeoJSON GeometryCollection` geometrii.
Feature	`GeoJSON Feature` obiekt.
FeatureCollection	`GeoJSON FeatureCollection` obiekt.

GeoJsonPoint

Objekt

Prawidłowy typ geometrii GeoJSON Point. Aby uzyskać szczegółowe informacje, zobacz RFC 7946.

Nazwa	Typ	Opis
coordinates	number[] (double)	`Position` to tablica liczb z co najmniej dwoma elementami. Dwa pierwsze elementy to długości geograficznej i szerokości geograficznej, dokładnie w tej kolejności. wysokości/wysokości jest opcjonalnym trzecim elementem. Aby uzyskać szczegółowe informacje, zobacz RFC 7946.
type	string: Point	Określa typ `GeoJSON`. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.

InputSnapToRoadsFeaturesItem

Objekt

Określa przyciąganie danych wejściowych do punktów dróg. GeoJSON obiekt funkcji i dodatkowe właściwości. Szczegółowe informacje można znaleźć w dokumencie RFC 7946 .

Nazwa	Typ	Opis
geometry	GeoJsonPoint	Prawidłowy typ geometrii `GeoJSON Point`. Aby uzyskać szczegółowe informacje, zobacz RFC 7946.
properties		Obiekt właściwości jest wymagany w prawidłowym formacie GeoJSON, ale może być pusty, ponieważ metadane nie są używane do przyciągania do drogi.
type	FeaturesItemTypeEnum	Określa typ `GeoJSON`. Jedynym obsługiwanym typem obiektu jest Funkcja. Aby uzyskać więcej informacji, zobacz RFC 7946.

MapsErrorDetail

Objekt

Szczegóły błędu.

Nazwa	Typ	Opis
code	string	Jeden z zdefiniowanych przez serwer zestaw kodów błędów.
details	MapsErrorDetail[]	Tablica szczegółów dotyczących określonych błędów, które doprowadziły do tego zgłoszonego błędu.
innererror	MapsInnerError	Obiekt zawierający bardziej szczegółowe informacje niż bieżący obiekt o błędzie.
message	string	Czytelna dla człowieka reprezentacja błędu.
target	string	Element docelowy błędu.

MapsErrorResponse

Objekt

Typowa odpowiedź na błędy dla API Azure Maps do zwracania szczegółów błędu dla nieudanych operacji.

Nazwa	Typ	Opis
error	MapsErrorDetail	Szczegóły błędu.

MapsInnerError

Objekt

Obiekt zawierający bardziej szczegółowe informacje niż bieżący obiekt o błędzie.

Nazwa	Typ	Opis
code	string	Kod błędu.
innererror	MapsInnerError	Obiekt zawierający bardziej szczegółowe informacje niż bieżący obiekt o błędzie.

SnapToRoadFeaturesItem

Objekt

Obiekt funkcji GeoJSON, który zawiera obiekt Geometry i dodatkowe właściwości trasy.

Nazwa	Typ	Opis
bbox	number[] (double)	Prostokątny obszar na ziemi zdefiniowany jako obiekt pola ograniczenia. Boki prostokątów są definiowane przez wartości szerokości i długości geograficznej. Aby uzyskać więcej informacji, zobacz RFC 7946, sekcja 5. Przykład: "bbox": [-10.0, -10.0, 10.0, 10.0]
geometry	GeoJsonPoint	Prawidłowy typ geometrii `GeoJSON Point`. Aby uzyskać szczegółowe informacje, zobacz RFC 7946.
properties	SnapToRoadsFeatureProperties	Przyciągaj do właściwości Drogi.
type	FeaturesItemTypeEnum	Określa typ `GeoJSON`. Jedynym obsługiwanym typem obiektu jest Funkcja. Aby uzyskać więcej informacji, zobacz RFC 7946.

SnapToRoadsFeatureProperties

Objekt

Przyciągaj do właściwości Drogi.

Nazwa	Typ	Opis
inputIndex	integer (int64)	Zidentyfikuj odpowiedni indeks na oryginalnej liście punktów dla każdego przyciąganego punktu. Tylko przyciągane punkty będą zwracać indeksy i mogą służyć do odróżnienia ich od punktów interpolowanych.
isInterpolated	boolean	Określ, czy jest to punkt interpolowany.
name	string	Nazwa drogi, do których punkt jest przyciągany.
speedLimitInKilometersPerHour	number (double)	Ograniczenie prędkości w kilometrach na godzinę.

SnapToRoadsRequest

Objekt

Ten obiekt jest treścią żądania.

Nazwa	Typ	Domyślna wartość	Opis
features	InputSnapToRoadsFeaturesItem[]		Zestaw punktów do przyciągania do sieci drogowej. Możesz mieć minimum 2 punkty i maksimum 5000 punktów, a dwa kolejne punkty muszą znajdować się w odległości do 6 kilometrów od siebie, a łączny dystans drogowy nie może przekraczać 100 kilometrów. Zapoznaj się z dokumentem RFC 7946 , aby uzyskać szczegółowe informacje na temat formatu GeoJSON. `Note`: interfejs API nie zwróci obiektu punktu w odpowiedzi dla punktu GPS, którego nie można przyciągnął do sieci drogowej.
includeSpeedLimit	boolean	False	Określa, czy należy uwzględnić informacje o limicie prędkości dla przyciąganych punktów w odpowiedzi. Jednostka jest wyrażona w kilometrach na godzinę.
interpolate	boolean	False	Określa, czy zwracać dodatkowe punkty między przyciętymi punktami, aby ukończyć pełną ścieżkę trasy, która płynnie podąża za geometrią drogi. Punkty interpolowane będą miały `isInterpolate:true` w odpowiedzi, która może służyć do identyfikowania punktów przyciąganych z punktów interpolowanych.
travelMode	SnapToRoadsTravelModeEnum	driving	Określa profil routingu do przyciągania punktów. Jeśli nie określono, domyślny tryb to "jazda", który optymalizuje przyciągane punkty dla tras jazdy.
type	FeatureTypeEnum		Określa typ `GeoJSON`. Jedynym obsługiwanym typem obiektu jest `FeatureCollection`. Aby uzyskać więcej informacji, zobacz RFC 7946.

SnapToRoadsResponse

Objekt

Ten obiekt jest zwracany z pomyślnego wywołania.

Nazwa	Typ	Opis
features	SnapToRoadFeaturesItem[]	`GeoJSON` obiekt funkcji, który zawiera obiekt Geometry i dodatkowe właściwości. Aby uzyskać szczegółowe informacje, zobacz RFC 7946, sekcja 3.2.
type	FeatureTypeEnum	Określa typ `GeoJSON`. Jedynym obsługiwanym typem obiektu jest `FeatureCollection`. Aby uzyskać więcej informacji, zobacz RFC 7946.

SnapToRoadsTravelModeEnum

Wyliczenie

Określa profil routingu do przyciągania punktów. Jeśli nie określono, domyślny tryb to "jazda", który optymalizuje przyciągane punkty dla tras jazdy.

Wartość	Opis
driving	Punkty są przyciągane do drogi odpowiedniej dla samochodów.
truck	Zwrotnice są przytwierdzone do drogi odpowiedniej dla ciężarówki.