Microsoft Azure Styles API

openapi: 3.2.0
info:
  title: Microsoft Azure Styles API
  version: 2023-03-01-preview
  description: 'Operations tagged Styles across 2 of this provider''s published API definitions: azure-maps-map-configuration-service-openapi-original.yml, azure-maps-style-service-openapi-original.yml. Each path carries the servers of the definition it was published in.'
security:
- AADToken:
  - https://atlas.microsoft.com/.default
- SharedKey: []
- SasToken: []
tags:
- name: Styles
paths:
  /styles/mapconfigurations:
    post:
      summary: Microsoft Azure Use To Create A Map Configuration
      description: 'For more information on what a map configuration is, see the Creator for indoor maps concepts article.


        ### Submit Create Request


        The Map Configuration `Create` API is an HTTP `POST` request used to create a new map configuration.'
      operationId: microsoftAzureMapconfigurationCreate
      x-ms-long-running-operation: true
      x-ms-long-running-operation-options:
        final-state-via: location
      x-ms-examples:
        Create a map configuration by providing a configuration file:
          $ref: ./examples/mapconfiguration/MapConfiguration_Create.json
      parameters:
      - $ref: ../../../Common/preview/1.0/common.json#/parameters/ClientId
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/Alias'
      - $ref: '#/components/parameters/DescriptionMapConfiguration'
      responses:
        '202':
          $ref: ../../../Common/preview/1.0/common.json#/responses/202AsyncV2
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      tags:
      - Styles
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MapConfiguration'
          application/zip:
            schema:
              $ref: '#/components/schemas/MapConfiguration'
        description: The configuration file used to create the map configuration. If JSON data format is provided, then the request body should follow [MapConfiguration specification](/rest/api/maps-creator/map-configuration/create?view=rest-maps-creator-2023-03-01-preview&tabs=HTTP#mapconfiguration). If ZIP data format is provided, you should also provide the thumbnail images referenced in the configuration JSON file. ALL files should be put in the root directory of the zip file. The thumbnail image file name should match the thumbnail name provided in the json file. The size limit is 23 MB.
        required: true
    get:
      summary: Microsoft Azure Use To Get A List Of All Map Configurations
      description: '### Submit List Request


        The Map Configuration `List` API is an HTTP `GET` request used to get a list of all map configurations.'
      operationId: microsoftAzureMapconfigurationList
      x-ms-examples:
        Get a list of all map configurations:
          $ref: ./examples/mapconfiguration/MapConfiguration_List.json
      parameters:
      - $ref: ../../../Common/preview/1.0/common.json#/parameters/ClientId
      - $ref: '#/components/parameters/ApiVersion'
      x-ms-pageable:
        itemName: mapConfiguration
        nextLinkName: nextLink
      responses:
        '200':
          description: List map configuration request completed successfully. The response body contains a list of all map configurations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MapConfigurationListResult'
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      tags:
      - Styles
  /styles/mapconfigurations/{mapConfigurationId}:
    get:
      summary: Microsoft Azure Use To Get A Map Configuration
      description: '### Submit Get Request


        The Map Configuration `Get` API is an HTTP `GET` request used to get a map configuration. The response contains a zip file with the map configuration JSON and any image files it references. You can always get the default map configuration using predefined alias `defaultIndoor_{tilesetId}` for a given tileset if you deleted the auto-generated map configuration. The two predefined styles used in default map configuration are `microsoft-maps:indoor_2022-01-01` and `microsoft-maps:indoor_dark_2022-01-01`.'
      operationId: microsoftAzureMapconfigurationGet
      x-ms-examples:
        Gets the details for a single map configuration:
          $ref: ./examples/mapconfiguration/MapConfiguration_Get.json
      parameters:
      - $ref: ../../../Common/preview/1.0/common.json#/parameters/ClientId
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/MapConfigurationId'
      responses:
        '200':
          description: Get map configuration request completed successfully. The response body contains a single map configuration zip file.
          headers:
            Content-Type:
              description: The content-type for the response.
              schema:
                type: string
          content:
            application/zip:
              schema:
                type: object
                format: file
                readOnly: true
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      tags:
      - Styles
    delete:
      summary: Microsoft Azure Use To Delete A Map Configuration
      description: 'The Map Configuration `Delete` API is an HTTP `DELETE` request used to delete a map configuration. For more information on what a map configuration is, see the Creator for indoor maps concepts article.


        ### Submit Delete Request


        An `HTTP DELETE` request with the `mapConfigurationId` in the path of the request is required to remove an existing map configuration from your Azure Maps account.


        #### Delete request "Successful"


        The Map Configuration Delete API returns a HTTP `204 No Content` response with an empty body, if the map configuration was deleted successfully.


        #### Delete request "Failed"


        A HTTP `400 Bad Request` error response will be returned if the map configuration with the passed-in `mapConfigurationId` is not found.


        Here is a sample error response:


        ```json

        {

        "error": {

        "code": "400 BadRequest",

        "message": "Bad request - MapConfiguration Id: d85b5b27-5fc4-4599-8b50-47160e90f8ce does not exist."

        }

        }

        ```'
      operationId: microsoftAzureMapconfigurationDelete
      x-ms-examples:
        Delete a created map configuration:
          $ref: ./examples/mapconfiguration/MapConfiguration_Delete.json
      parameters:
      - $ref: ../../../Common/preview/1.0/common.json#/parameters/ClientId
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/MapConfigurationId'
      responses:
        '204':
          description: Map configuration delete request completed successfully.
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      tags:
      - Styles
  /styles/mapconfigurations/operations/{operationId}:
    get:
      summary: Microsoft Azure Use To Check The Status Of The Map Configuration Creation…
      description: 'The `Get Operation` API is an HTTP `GET` request used to check the status of the map configuration creation process.


        ### Submit Operations Request


        To view the current progress of a map configuration operation, you will use a `GET` request where the `operationId` given the path is the ID that represents the operation.


        ### Operation Response


        While in progress, a `200-OK` http status code is returned with no extra headers. If the operation succeeds, a `200-OK` http status code is returned with the `Resource-Location` in the header.'
      operationId: microsoftAzureMapconfigurationGetoperation
      x-ms-examples:
        Get the status of an operation which is still running:
          $ref: ./examples/mapconfiguration/MapConfiguration_GetOperationStillRunning.json
        Get the status of an operation which has finished successfully:
          $ref: ./examples/mapconfiguration/MapConfiguration_GetOperation.json
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/MapConfigurationOperationId'
      responses:
        '200':
          description: The operation is running or complete. If the operation was successful, use the Resource-Location header to obtain the path to the result.
          headers:
            Resource-Location:
              description: If successful, a URI where details on the newly created resource can be found.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: ./tileset.json#/definitions/LongRunningOperationResult
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      tags:
      - Styles
  /styles:
    post:
      summary: Microsoft Azure Use To Create An Azure Maps Style
      description: '## Submit Create Request


        The `Style Create` API is an HTTP `POST` request used to create an Azure Maps style by passing in either a JSON or ZIP file containing the style information.


        The Create Style API is a long-running operation.'
      operationId: microsoftAzureStyleCreate
      x-ms-long-running-operation: true
      x-ms-long-running-operation-options:
        final-state-via: location
      x-ms-examples:
        Create Style by providing an azure maps style json file:
          $ref: ./examples/style/Style_Create.json
      parameters:
      - $ref: ../../../Common/preview/1.0/common.json#/parameters/ClientId
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/DescriptionStyle'
      - $ref: '#/components/parameters/StyleAlias'
      responses:
        '202':
          $ref: ../../../Common/preview/1.0/common.json#/responses/202AsyncV2
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      tags:
      - Styles
      requestBody:
        content:
          application/json:
            schema:
              type: object
          application/zip:
            schema:
              type: object
        description: The style content to be uploaded. If JSON data format is provided, then the request body should follow [Layers specification](https://maplibre.org/maplibre-gl-js-docs/style-spec/layers) in MapLibre Style specification. If ZIP data format is provided, you should also provide the sprite sheet and associated index files which contains icons used in the style configuration json file.
        required: true
    get:
      summary: Microsoft Azure Use To Get A List Of Styles
      description: 'The `List` API is an HTTP `GET` request that allows the caller to fetch a list of all styles in the current Azure Maps Creator account. The default indoor style `microsoft-maps:indoor_2022-01-01` and `microsoft-maps:indoor_dark_2022-01-01` will not show in the list response. But you can still use it as your own style by the predefined alias.


        ### Submit List Request'
      operationId: microsoftAzureStyleList
      x-ms-examples:
        Get a list of all styles:
          $ref: ./examples/style/Style_List.json
      parameters:
      - $ref: ../../../Common/preview/1.0/common.json#/parameters/ClientId
      - $ref: '#/components/parameters/ApiVersion'
      x-ms-pageable:
        itemName: styles
        nextLinkName: nextLink
      responses:
        '200':
          description: List style request completed successfully. The response body contains a list of all styles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StyleListResult'
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      tags:
      - Styles
  /styles/{styleId}:
    get:
      summary: Microsoft Azure Use To Get Details Of A Style
      description: '### Submit Get Request


        The `Get` API is an HTTP `GET` request that allows the caller to fetch the details of an existing style by passing in the `styleId` or its alias. Get the two predefined default styles using the alias `microsoft-maps:indoor_2022-01-01` for indoor light and `microsoft-maps:indoor_dark_2022-01-01` for indoor dark.'
      operationId: microsoftAzureStyleGet
      x-ms-examples:
        Get the details for a single style:
          $ref: ./examples/style/Style_Get.json
      parameters:
      - $ref: ../../../Common/preview/1.0/common.json#/parameters/ClientId
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/StyleId'
      responses:
        '200':
          description: Get style request completed successfully. The response body contains a zip file with style content.
          headers:
            Content-Type:
              description: The content-type for the response.
              schema:
                type: string
          content:
            application/zip:
              schema:
                type: object
                format: file
                readOnly: true
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      tags:
      - Styles
    delete:
      summary: Microsoft Azure Use To Delete A Style
      description: '### Submit Delete Request


        The `Delete` API is an HTTP `DELETE` request that is used to delete the specified style, where the path will contain the `styleId` of the style to delete.


        #### Delete request "Successful"


        The Style Delete API returns a HTTP `204 No Content` response with an empty body, if the style was deleted successfully.


        #### Delete request "Failed"


        A HTTP `400 Bad Request` error response will be returned if the style with the passed-in `styleId` is not found.


        Here is a sample error response:


        ```json

        {

        "error": {

        "code": "400 BadRequest",

        "message": "Bad request - Style Id: d85b5b27-5fc4-4599-8b50-47160e90f8ce does not exist."

        }

        }

        ```'
      operationId: microsoftAzureStyleDelete
      x-ms-examples:
        Delete a created style:
          $ref: ./examples/style/Style_Delete.json
      parameters:
      - $ref: ../../../Common/preview/1.0/common.json#/parameters/ClientId
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/StyleId'
      responses:
        '204':
          description: Style delete request completed successfully.
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      tags:
      - Styles
  /styles/operations/{operationId}:
    get:
      summary: Microsoft Azure Use To Check The Status Of The Style Creation Process
      description: 'The `Get Operation` API is an HTTP `GET` request used to check the status of the style creation process and retrieve the `styletId`.


        ### Submit Operations Request


        To view the current progress of a style operation, you will use a `GET` request where the `operationId` given the path is the ID that represents the operation.


        ### Operation Response


        While in progress, a `200-OK` http status code is returned with no extra headers. If the operation succeeds, a `200-OK` http status code is returned with the `Resource-Location` in the header.'
      operationId: microsoftAzureStyleGetoperation
      x-ms-examples:
        Get the status of an operation which is still running:
          $ref: ./examples/style/Style_GetOperationStillRunning.json
        Get the status of an operation which has finished successfully:
          $ref: ./examples/style/Style_GetOperation.json
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/StyleOperationId'
      responses:
        '200':
          description: The operation is running or complete. If the operation was successful, use the Resource-Location header to obtain the path to the result.
          headers:
            Resource-Location:
              description: If successful, a URI where details on the newly created resource can be found.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: ./tileset.json#/definitions/LongRunningOperationResult
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      tags:
      - Styles
components:
  schemas:
    MapConfigurationListItem:
      description: One item in map configuration list.
      type: object
      properties:
        mapConfigurationId:
          description: The unique id for the map configuration.
          type: string
          readOnly: true
        description:
          description: The description the caller provided when creating the map configuration. Maximum length 1024 characters.
          type: string
          readOnly: true
        alias:
          description: The alias used for the map configuration. Maximum length 1024 characters. Alias cannot start with `microsoft-maps` which is a reserved prefix.
          type: string
          readOnly: true
        created:
          description: The creation date and time of this map configuration.
          type: string
          format: date-time
          readOnly: true
    BaseMapType:
      description: The available base map types. Currently, we support 9 base map types.
      type: string
      enum:
      - microsoft_light
      - microsoft_dark
      - microsoft_grayscale_light
      - microsoft_grayscale_dark
      - microsoft_high_contrast_light
      - microsoft_high_contrast_dark
      - microsoft_shaded_relief
      - microsoft_satellite
      - microsoft_satellite_road
      x-ms-enum:
        name: BaseMap
        modelAsString: true
        values:
        - value: microsoft_light
          description: The base road map style.
        - value: microsoft_dark
          description: The base dark road map style.
        - value: microsoft_grayscale_light
          description: The grayscale light map style.
        - value: microsoft_grayscale_dark
          description: The grayscale dark map style.
        - value: microsoft_high_contrast_light
          description: The high contrast light map style.
        - value: microsoft_high_contrast_dark
          description: The high contrast dark map style.
        - value: microsoft_shaded_relief
          description: The shaded relief map style.
        - value: microsoft_satellite
          description: The satellite imagery map style.
        - value: microsoft_satellite_road
          description: The satellite and road map style.
    ConfigurationObject:
      description: Define the format to configure a style picker and the associated map in client SDK.
      type: object
      required:
      - name
      - layers
      properties:
        name:
          description: The name for the style. Maximum length 255 characters.
          type: string
        displayName:
          description: The display name for the style picker in client SDK. Maximum length 255 characters.
          type: string
        description:
          description: The description for the style. Maximum length 500 characters.
          type: string
        theme:
          description: The theme for client SDK widgets(style picker, zoom, level picker).
          type: string
          enum:
          - light
          - dark
          x-ms-enum:
            name: theme
            modelAsString: true
            values:
            - value: light
              description: The light theme for client SDK widgets(style picker, zoom, level picker).
            - value: dark
              description: The dark theme for client SDK widgets(style picker, zoom, level picker).
        thumbnail:
          description: The thumbnail image file for the style picker in client SDK. Maximum length 255 characters. The size limit is 400KB and pixel limit is 512*512.
          type: string
        baseMap:
          description: The base map is a background layer for private indoor map. This property is optional, no base map will show if not provided. Maximum length 100 characters.
          $ref: '#/components/schemas/BaseMapType'
        layers:
          description: To configure the style for tileset. You can have one style for the whole tileset. And you can have different styles for different layers in one tileset, for example, one style for `indoor unit` layer and another style for `indoor facility` layer. And you have also have one style for different tileset
          items:
            $ref: '#/components/schemas/TilesetStyleTuple'
    MapConfigurationListResult:
      description: The response model for the Map Configuration List API. Returns a list of all map configurations.
      type: object
      properties:
        mapConfigurations:
          description: A list of all map configurations.
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/MapConfigurationListItem'
        nextLink:
          description: If present, the location of the next page of data.
          type: string
          readOnly: true
    TilesetStyleTuple:
      description: TilesetId and StyleId tuple
      type: object
      required:
      - tilesetId
      - styleId
      properties:
        tilesetId:
          description: The unique id of a tileset.
          type: string
        styleId:
          description: The unique id of an azure map style. Two predefined styleId aliases are `microsoft-maps:indoor_2022-01-01` for indoor light and `microsoft-maps:indoor_dark_2022-01-01` for indoor dark.
          type: string
    MapConfiguration:
      description: A map configuration object which describes the map configuration json format.
      type: object
      required:
      - version
      properties:
        version:
          description: The version of the map configuration, currently only version 1.0 is supported.
          type: number
          format: float
        description:
          description: The description the caller provided when creating the map configuration. Maximum length 1024 characters.
          type: string
        defaultConfiguration:
          description: The default configuration for the map configuration. The value should be one of the 'name' field in ConfigurationObject under 'configurations' array. If not provided, first entry in the 'configurations' list will be used.
          type: string
        configurations:
          description: '''Configurations'' array will allow customer to configure different map representations for their tileset. Each configuration configured here will be reflected as one map style in style picker in client SDK. The name should be unique in the configurations array.'
          items:
            $ref: '#/components/schemas/ConfigurationObject'
    StyleListResult:
      description: The response model for the Style List API. Returns a list of all styles.
      type: object
      properties:
        styles:
          description: A list of all styles.
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/StyleListItem'
        nextLink:
          description: If present, the location of the next page of data.
          type: string
          readOnly: true
    StyleListItem:
      description: Detail information for the data.
      type: object
      properties:
        styleId:
          description: The unique style id for the style.
          type: string
          readOnly: true
        description:
          description: The description the caller provided when creating the style. Maximum length 1024 characters.
          type: string
          readOnly: true
        alias:
          description: The alias of the style. Maximum length 1024 characters. Alias cannot start with `microsoft-maps` which is a reserved prefix.
          type: string
          readOnly: true
        created:
          description: The creation date and time of this style.
          type: string
          format: date-time
          readOnly: true
  parameters:
    ApiVersion:
      name: api-version
      description: Version number of Azure Maps API.
      in: query
      required: true
      x-ms-parameter-location: client
      schema:
        type: string
    MapConfigurationId:
      name: mapConfigurationId
      description: The map configuration Id.
      in: path
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    Alias:
      name: alias
      description: The alias of the map configuration. Maximum length 1024 characters. Alias cannot start with `microsoft-maps` which is a reserved prefix. Alias can be provided optionally during creating a map configuration, and can be used as same as mapConfigurationId after map configuration creation.
      in: query
      required: false
      x-ms-parameter-location: method
      schema:
        type: string
    DescriptionMapConfiguration:
      name: description
      description: User provided description of the map configuration. Maximum length 1024 characters.
      in: query
      x-ms-parameter-location: method
      schema:
        type: string
    MapConfigurationOperationId:
      name: operationId
      in: path
      description: The ID to query the status for the map configuration create request.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    DescriptionStyle:
      name: description
      description: User provided description of the style. Maximum length 1024 characters.
      in: query
      x-ms-parameter-location: method
      schema:
        type: string
    StyleOperationId:
      name: operationId
      in: path
      description: The ID to query the status for the style create request.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    StyleAlias:
      name: alias
      description: 'The alias of the style. Maximum length 1024 characters. Alias cannot start with `microsoft-maps` which is a reserved prefix. Alias can be provided optionally during creating a style, and can be used as same as styleId after style creation. '
      in: query
      required: false
      x-ms-parameter-location: method
      schema:
        type: string
    StyleId:
      name: styleId
      description: The Style Id.
      in: path
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
  securitySchemes:
    AADToken:
      type: oauth2
      flows:
        implicit:
          scopes:
            https://atlas.microsoft.com/.default: https://atlas.microsoft.com/.default
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      description: "These are the [Azure Active Directory OAuth2](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 Azure Active directory 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* Currently, Azure Active Directory [v1.0 or v2.0](https://docs.microsoft.com/azure/active-directory/develop/azure-ad-endpoint-comparison) supports Work, School, and Guests but does not support Personal accounts."
    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
x-refined-from:
- azure-maps-map-configuration-service-openapi-original.yml
- azure-maps-style-service-openapi-original.yml
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'