Route - Post Route Matrix

La API de Route Matrix es una solicitud de POST HTTP que permite calcular una matriz de resúmenes de ruta para un conjunto de rutas definidas por ubicaciones de origen y destino mediante una solicitud de sincronización. Para cada origen determinado, el servicio calcula el costo de enrutamiento desde ese origen a cada destino determinado. El conjunto de orígenes y el conjunto de destinos se pueden considerar como los encabezados de columna y fila de una tabla y cada celda de la tabla contiene los costos de enrutamiento desde el origen hasta el destino de esa celda. Las matrices de ruta se pueden calcular para conducir, caminar y rutas de camión. Por ejemplo, una empresa de entrega de alimentos tiene 20 conductores y necesitan encontrar el conductor más cercano para recoger la entrega del restaurante. Para resolver este caso de uso, pueden llamar a Route Matrix API y usar el costo de viaje para ordenar los conductores por su distancia de viaje real o tiempo desde el restaurante.

Las matrices de ruta se usan en varios tipos diferentes de aplicaciones, normalmente para resolver el problema del vendedor de viajes (TSP) y el problema de enrutamiento de vehículos (VRP). Para cada par de origen-destino de la matriz, se devuelve el tiempo de viaje y la distancia. Puede usar los costos calculados para determinar qué rutas detalladas se van a calcular mediante Route Directions API.

El tamaño máximo de una matriz para la solicitud de sincronización es 2500 (el número de orígenes multiplicado por el número de destinos).

Enviar solicitud de matriz de ruta sincrónica

Si el escenario requiere solicitudes sincrónicas y el tamaño máximo de la matriz es menor o igual que 2500, es posible que desee realizar una solicitud sincrónica. El tamaño máximo de una matriz para esta API es 2500 (el número de orígenes multiplicado por el número de destinos). Teniendo en cuenta esa restricción, algunos ejemplos de posibles dimensiones de matriz son: 50x50, 60x40, 90x20 (no es necesario que sea cuadrado).

Limitaciones de api

El procesamiento sincrónico de matriz es más adecuado para matrices rápidas y pequeñas de cálculo de ruta. Para calcular matrices de mayor tamaño y cálculo de rutas pesadas, use el punto de conexión asincrónico. La siguiente limitación es aplicable a las solicitudes sincrónicas. Si ninguna de las filas de la tabla siguiente coincide con los parámetros de la solicitud, la solicitud no cumple los requisitos y no se procesará.

Ejemplos:

• Solicitud de matriz de 10x20 con traffic=live: esta solicitud se procesará con un límite de rectángulo de límite, ya que coincide con un límite de hasta 200, que incluye restricciones de rectángulo de límite.

• Solicitud de matriz de 10x20 con parámetros predeterminados (traffic=historical): esta solicitud se procesará sin un límite de rectángulo de límite, ya que coincide con un límite de hasta 2500, que no impone restricciones de rectángulo de límite.

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

Parámetros de identificador URI

Encabezado de la solicitud

Media Types: "application/geo+json"

Cuerpo de la solicitud

Media Types: "application/geo+json"

Respuestas

Seguridad

AADToken

Estos son los flujos de Microsoft Entra OAuth 2.0. Cuando se empareja con acceso basado en rol de Azure control, se puede usar para controlar el acceso a las API REST de Azure Maps. Los controles de acceso basados en roles de Azure se usan para designar el acceso a una o varias cuentas de recursos o subrecursos de Azure Maps. Se puede conceder acceso a cualquier usuario, grupo o entidad de servicio a través de un rol integrado o de un rol personalizado compuesto por uno o varios permisos para las API REST de Azure Maps.

Para implementar escenarios, se recomienda ver los conceptos de autenticación. En resumen, esta definición de seguridad proporciona una solución para modelar aplicaciones a través de objetos capaces de controlar el acceso en determinadas API y ámbitos.

Tipo: oauth2
Flujo: implicit
Dirección URL de autorización: https://login.microsoftonline.com/common/oauth2/authorize

Ámbitos

subscription-key

Se trata de una clave compartida que se aprovisiona al crear una recurso de Azure Maps a través del plano de administración de Azure a través de Azure Portal, PowerShell, CLI, SDK de Azure o API REST.

Con esta clave, cualquier aplicación está autorizada para acceder a todas las API REST. En otras palabras, estos se pueden tratar actualmente como claves maestras para la cuenta para la que se emiten.

Para las aplicaciones expuestas públicamente, nuestra recomendación es usar el acceso de servidor a servidor de las API REST de Azure Maps donde esta clave se puede almacenar de forma segura.

Tipo: apiKey
En: header

SAS Token

Se crea un token de firma de acceso compartido a partir de la operación List SAS en el recurso de Azure Maps a través del plano de administración de Azure a través de Azure Portal, PowerShell, CLI, SDK de Azure o API REST.

Con este token, cualquier aplicación tiene autorización para acceder a los controles de acceso basados en rol de Azure y el control específico a la expiración, la tasa y las regiones de uso para el token determinado. Es decir, el token de SAS se puede usar para permitir que las aplicaciones controle el acceso de forma más segura que la clave compartida.

En el caso de las aplicaciones expuestas públicamente, nuestra recomendación es configurar una lista específica de orígenes permitidos en el recurso de cuenta de mapa de limitar el abuso de representación y renovar periódicamente el token de SAS.

Tipo: apiKey
En: header

Ejemplos

Successfully retrieve a route matrix with additional parameters in the body

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

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [
            9.15049,
            45.458545
          ],
          [
            11.050541,
            45.403337
          ]
        ]
      },
      "properties": {
        "pointType": "origins"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [
            11.499931,
            48.149853
          ],
          [
            14.538226,
            50.033688
          ]
        ]
      },
      "properties": {
        "pointType": "destinations"
      }
    }
  ],
  "departAt": "2022-12-19T16:39:57+01:00",
  "optimizeRoute": "fastest",
  "traffic": "historical",
  "travelMode": "truck",
  "avoid": [
    "unpavedRoads"
  ]
}

{
  "type": "Feature",
  "geometry": null,
  "properties": {
    "summary": {
      "totalCount": 4,
      "successfulCount": 4
    },
    "matrix": [
      {
        "statusCode": 200,
        "originIndex": 0,
        "destinationIndex": 0,
        "durationTrafficInSeconds": 21007,
        "durationInSeconds": 21007,
        "distanceInMeters": 492466,
        "departureAt": "2022-12-19T16:39:57+01:00",
        "arrivalAt": "2022-12-19T22:30:03+01:00"
      },
      {
        "statusCode": 200,
        "originIndex": 0,
        "destinationIndex": 1,
        "durationTrafficInSeconds": 33623,
        "durationInSeconds": 33623,
        "distanceInMeters": 877028,
        "departureAt": "2022-12-19T16:39:57+01:00",
        "arrivalAt": "2022-12-20T02:00:19+01:00"
      },
      {
        "statusCode": 200,
        "originIndex": 1,
        "destinationIndex": 0,
        "durationTrafficInSeconds": 19520,
        "durationInSeconds": 19520,
        "distanceInMeters": 427769,
        "departureAt": "2022-12-19T16:39:57+01:00",
        "arrivalAt": "2022-12-19T22:05:16+01:00"
      },
      {
        "statusCode": 200,
        "originIndex": 1,
        "destinationIndex": 1,
        "durationTrafficInSeconds": 32070,
        "durationInSeconds": 32070,
        "distanceInMeters": 836080,
        "departureAt": "2022-12-19T16:39:57+01:00",
        "arrivalAt": "2022-12-20T01:34:27+01:00"
      }
    ]
  }
}

Definiciones

AdrTunnelRestrictionCodeEnum

Código de restricción del túnel ADR. ADR es un acuerdo europeo relativo al transporte internacional de mercancías peligrosas por carretera. El código de restricción del túnel ADR se utiliza para determinar si se permite que un vehículo pase a través de un túnel con restricciones sobre el transporte de mercancías peligrosas.

ErrorAdditionalInfo

Información adicional sobre el error de administración de recursos.

ErrorDetail

Detalle del error.

FeaturesItemTypeEnum

Especifica el tipo de GeoJSON. El único tipo de objeto admitido es Feature. Para obtener más información, consulte RFC 7946.

FeatureTypeEnum

Especifica el tipo de GeoJSON. El único tipo de objeto admitido es FeatureCollection. Para obtener más información, consulte RFC 7946.

GeoJsonMultiPoint

Un tipo de geometría GeoJSON MultiPoint válido. Consulte RFC 7946 para obtener más información.

InputRouteMatrixFeaturesItem

Especifica los puntos de origen y destino de entrada y propiedades adicionales para el objeto de característica de GeoJSON MultiPoint. Consulte RFC 7946 para obtener más detalles.

InputRouteMatrixProperties

Especifica el objeto properties de la matriz de entrada.

MapsErrorDetail

Detalle del error.

MapsErrorResponse

Respuesta de error común para las API de Azure Maps para devolver los detalles de error de las operaciones con errores.

MapsInnerError

Objeto que contiene información más específica que el objeto actual sobre el error.

RouteMatrixAsyncResponse

Especifica las instrucciones de conducción y propiedades adicionales para cada punto de maniobra de la pierna de ruta.

RouteMatrixAvoidEnum

Especifica las restricciones que debe respetar el cálculo de la ruta al determinar la ruta. Evite admitir varios valores en una solicitud y solo se admite para la conducción y el travelMode del camión.

RouteMatrixFeatureProperties

Propiedades de la matriz de rutas.

RouteMatrixItemResult

Resultado del elemento Route Matrix

RouteMatrixOptimizeRouteEnum

Especifica el parámetro que se va a usar para optimizar la ruta. Si no se define, el valor predeterminado es "más rápido" que devuelve la ruta para minimizar el tiempo de viaje.

Ejemplo: "optimizeRoute":"fastest"

RouteMatrixRequest

Use para obtener una matriz de rutas que muestre el tiempo de viaje y la distancia de todos los pares posibles en una lista de orígenes y destino. GeoJSON objeto de característica y propiedades adicionales. Consulte RFC 7946 para obtener más detalles.

RouteMatrixResponse

Este objeto se devuelve de una llamada correcta.

RouteMatrixSummary

Resumen de la solicitud de matriz de rutas

RouteMatrixTrafficEnum

Especifica cómo se considera el tráfico para las rutas informáticas.

Valor predeterminado: historical

RouteMatrixTravelModeEnum

Especifica el perfil de viaje que se debe tener en cuenta al calcular la matriz. Si no se especifica, el valor predeterminado es "driving".

Ejemplo: "travelMode":"conducción"

RouteMatrixTypeEnum

Especifica el tipo multipoint de origen y el tipo multipoint de destino para la matriz de entrada.

RouteMatrixVehicleSpec

Especifica los atributos del vehículo, como la altura del vehículo, el peso, la velocidad máxima, el tipo de carga, etc. que se deben tener en cuenta al calcular la matriz de rutas. Esto ayuda a evitar bajas distancias de puente, restricciones de carretera, giros difíciles a la derecha para proporcionar la ruta optimizada en función de las especificaciones del vehículo. Los atributos del vehículo se especifican dentro de la propiedad vehicleSpec.

RouteOperationKindEnum

Tipo de operación asincrónica

VehicleLoadTypeEnum

Tipos de carga que se pueden clasificar como materiales peligrosos y restringidos de algunas carreteras. Los valores de vehicleLoadType disponibles son clases hazmat de EE. UU. de 1 a 9, además de clasificaciones genéricas para su uso en otros países. Los valores que comienzan con USHazmat son para el enrutamiento de EE. UU., mientras que otroshazmat deben usarse para todos los demás países. vehicleLoadType admite varios valores en una solicitud.