wayfind.json

{
  "swagger": "2.0",
  "info": {
    "version": "2022-09-01-preview",
    "title": "Azure Maps Wayfinding Service",
    "description": "Azure Maps Wayfinding REST APIs"
  },
  "x-ms-parameterized-host": {
    "hostTemplate": "{geography}.atlas.microsoft.com",
    "parameters": [
      {
        "$ref": "../../../Common/preview/1.0/common.json#/parameters/GeographicResourceLocation"
      }
    ]
  },
  "schemes": [
    "https"
  ],
  "consumes": [],
  "produces": [
    "application/json"
  ],
  "securityDefinitions": {
    "AADToken": {
      "type": "oauth2",
      "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize",
      "flow": "implicit",
      "description": "These are the [Microsoft Entra OAuth 2.0](https://docs.microsoft.com/azure/active-directory/develop/v1-overview) Flows. When paired with [Azure role-based access](https://docs.microsoft.com/azure/role-based-access-control/overview) control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a  built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.\n\nTo implement scenarios, we recommend viewing [authentication concepts](https://aka.ms/amauth). In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.\n\n#### Notes\n* 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. This can be acquired from the [Maps management API](https://aka.ms/amauthdetails).\n* \nThe `Authorization URL` is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Microsoft Entra ID configurations. \n* \nThe Azure role-based access control is configured from the [Azure management plane](https://aka.ms/amrbac) via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n* \nUsage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for configuration based setup of an application for multiple use cases.\n* For more information on Microsoft identity platform, see [Microsoft identity platform overview](https://learn.microsoft.com/entra/identity-platform/v2-overview).",
      "scopes": {
        "https://atlas.microsoft.com/.default": "https://atlas.microsoft.com/.default"
      }
    },
    "SharedKey": {
      "type": "apiKey",
      "description": "This is a shared key that is provisioned when you [Create an Azure Maps account](https://docs.microsoft.com/azure/azure-maps/quick-demo-map-app#create-an-azure-maps-account) in the Azure portal or using PowerShell, CLI, Azure SDKs, or REST API.\n\n With this key, any application can access all REST API. In other words, this key can be used as a master key in the account that they are issued in.\n\n For publicly exposed applications, our recommendation is to use the [confidential client applications](https://docs.microsoft.com/azure/azure-maps/authentication-best-practices#confidential-client-applications) approach to access Azure Maps REST APIs so your key can be securely stored.",
      "name": "subscription-key",
      "in": "query"
    },
    "SasToken": {
      "type": "apiKey",
      "description": "This is a shared access signature token is created from the List SAS operation on the [Azure Maps resource](https://aka.ms/amauth) through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n\n With this token, any application is authorized to access with Azure role-based access controls and fine-grain control to the expiration, rate, and region(s) of use for the particular token. In other words, the SAS Token can be used to allow applications to control access in a more secured way than the shared key.\n\n For publicly exposed applications, our recommendation is to configure a specific list of allowed origins on the [Map account resource](https://aka.ms/amauth) to limit rendering abuse and regularly renew the SAS Token.",
      "name": "SAS Token",
      "in": "header"
    }
  },
  "security": [
    {
      "AADToken": [
        "https://atlas.microsoft.com/.default"
      ]
    },
    {
      "SharedKey": []
    },
    {
      "SasToken": []
    }
  ],
  "definitions": {
    "Point": {
      "description": "A point within the facility.",
      "type": "object",
      "properties": {
        "latitude": {
          "description": "the point latitude",
          "type": "number"
        },
        "longitude": {
          "description": "the point longitude",
          "type": "number"
        }
      },
      "required": [
        "latitude",
        "longitude"
      ]
    },
    "Leg": {
      "description": "A section of the overall path.",
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "description": "The leg mode of traversal for this leg. It can be default (all on the same level), elevators or stairs when moving vertically between levels."
        },
        "lengthInMeters": {
          "type": "number",
          "description": "The leg length, in meters, of this leg."
        },
        "timeInSeconds": {
          "type": "integer",
          "format": "int64",
          "description": "The leg travel time, in seconds, to travel between the first and last point of this leg."
        },
        "startLevel": {
          "type": "integer",
          "format": "int32",
          "description": "The floor where this leg starts."
        },
        "endLevel": {
          "type": "integer",
          "format": "int32",
          "description": "The floor where this leg ends."
        },
        "points": {
          "description": "The leg shape points. Their vertical position is determined as follows: all the points are at the same height when startLevel and endLevel are the same, otherwise the array will contain only two points: the first at startLevel and the second at endLevel.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/Point"
          },
          "x-ms-identifiers": []
        }
      }
    },
    "Path": {
      "description": "The details about a particular path between the origin and destination. It can be made up of one or more legs.",
      "type": "object",
      "properties": {
        "lengthInMeters": {
          "type": "number",
          "description": "The path length, in meters, of the entire path."
        },
        "timeInSeconds": {
          "type": "integer",
          "format": "int64",
          "description": "The path total time, in seconds, to travel between the origin and the destination when following this path."
        },
        "legs": {
          "description": "The different travel sections of this path.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/Leg"
          },
          "x-ms-identifiers": []
        }
      }
    },
    "WayfindResult": {
      "description": "The object returned by this Wayfinding Path request.",
      "type": "object",
      "properties": {
        "noResultExplanation": {
          "type": "string",
          "description": "In the event that no paths are found, the `paths` array will be empty. If the reason no paths were found can be determined, this property will provide an explanation why.",
          "enum": [
            "NoExplanation"
          ],
          "x-ms-enum": {
            "name": "NoResultExplanation",
            "modelAsString": true,
            "values": [
              {
                "value": "NoExplanation",
                "description": "Default value provided when a result is returned or it wasn't possible to determine why a path wasn't found."
              }
            ]
          },
          "readOnly": true
        },
        "paths": {
          "description": "An array of wayfinding path results.  An empty array will be returned if no results were found.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/Path"
          },
          "x-ms-identifiers": []
        }
      }
    }
  },
  "parameters": {
    "ApiVersion": {
      "name": "api-version",
      "description": "Version number of Azure Maps API.",
      "type": "string",
      "in": "query",
      "required": true,
      "default": "2022-09-01-preview",
      "x-ms-parameter-location": "method"
    },
    "RoutesetId": {
      "name": "routesetId",
      "description": "The ID of the routeset to query from.",
      "type": "string",
      "in": "query",
      "required": true,
      "x-ms-parameter-location": "client"
    },
    "FacilityId": {
      "name": "facilityId",
      "type": "string",
      "in": "query",
      "description": "The identifier of the facility within the routeset where to find the path.",
      "required": true,
      "x-ms-parameter-location": "client"
    },
    "FromPoint": {
      "name": "fromPoint",
      "type": "string",
      "in": "query",
      "description": "The path origin point in the following format: {latitude},{longitude}.",
      "required": true,
      "x-ms-parameter-location": "client"
    },
    "FromLevel": {
      "name": "fromLevel",
      "type": "integer",
      "format": "int32",
      "in": "query",
      "description": "The path origin level.",
      "required": true,
      "x-ms-parameter-location": "client"
    },
    "ToPoint": {
      "name": "toPoint",
      "type": "string",
      "in": "query",
      "description": "The path destination in the following format: {latitude},{longitude}.",
      "required": true,
      "x-ms-parameter-location": "client"
    },
    "ToLevel": {
      "name": "toLevel",
      "type": "integer",
      "format": "int32",
      "in": "query",
      "description": "The path destination level.",
      "required": true,
      "x-ms-parameter-location": "client"
    },
    "AvoidFeatures": {
      "name": "avoidFeatures",
      "in": "query",
      "description": "To avoid certain types of connectors in the resulting path. Can be specified multiple times in one request, for example, '&avoidFeatures=elevators&avoidFeatures=escalators'.",
      "type": "array",
      "collectionFormat": "multi",
      "items": {
        "type": "string",
        "enum": [
          "stairs",
          "elevators"
        ],
        "x-ms-enum": {
          "name": "avoidFeatures",
          "modelAsString": true,
          "values": [
            {
              "value": "stairs",
              "description": "Avoids the use of stairs in route calculation."
            },
            {
              "value": "elevators",
              "description": "Avoids the use of elevators in route calculation."
            }
          ]
        },
        "x-ms-parameter-location": "client"
      }
    },
    "MinWidth": {
      "name": "minWidth",
      "description": "The minimum width (in meters) of openings in the searched path. For example, if you specified a minimum width of 0.85, the searched path will avoid openings less than 85 centimeters wide. Note: by using this value, the resulting path points will be buffered from walls and other vertical obstacles by half of the width provided.",
      "type": "number",
      "in": "query",
      "default": "0.55",
      "x-ms-parameter-location": "client"
    }
  },
  "paths": {
    "/wayfinding/path": {
      "get": {
        "description": "**Applies to:** see [pricing tiers](https://aka.ms/AzureMapsPricingTier).\n\n Creator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. See the [Creator for indoor maps](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps) article for an introduction to the Azure Maps Creator concepts and tools.\n\nThe Wayfinding Service API is part of Creator, and adheres to the [Open Geospatial Consortium](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) standard and uses indoor maps data from the routeset to calculate the best path between two locations within the same facility.",
        "operationId": "Wayfinding_GetPath",
        "x-ms-examples": {
          "Get the shortest path between two points in the facility.": {
            "$ref": "./examples/wayfind/Wayfinding_GetPath.json"
          }
        },
        "parameters": [
          {
            "$ref": "../../../Common/preview/1.0/common.json#/parameters/ClientId"
          },
          {
            "$ref": "#/parameters/ApiVersion"
          },
          {
            "$ref": "#/parameters/RoutesetId"
          },
          {
            "$ref": "#/parameters/FacilityId"
          },
          {
            "$ref": "#/parameters/FromPoint"
          },
          {
            "$ref": "#/parameters/FromLevel"
          },
          {
            "$ref": "#/parameters/ToPoint"
          },
          {
            "$ref": "#/parameters/ToLevel"
          },
          {
            "$ref": "#/parameters/AvoidFeatures"
          },
          {
            "$ref": "#/parameters/MinWidth"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/WayfindResult"
            }
          },
          "default": {
            "$ref": "../../../Common/preview/1.0/common.json#/responses/default"
          }
        }
      }
    }
  }
}