Microsoft Azure Maps Tileset Service

swagger: '2.0'
info:
  title: Microsoft Azure Azure Maps Tileset Service
  version: '2.0'
  description: APIs for managing Tilesets.
x-ms-parameterized-host:
  hostTemplate: '{geography}.atlas.microsoft.com'
  parameters:
    - $ref: '#/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.


      To 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.


      #### Notes

      * 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).

      * 

      The `Authorization URL` is specific to the Azure public cloud instance.
      Sovereign clouds have unique Authorization URLs and Microsoft Entra ID
      configurations. 

      * 

      The 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.

      * 

      Usage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for
      configuration based setup of an application for multiple use cases.

      * 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.

       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.

       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.

       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.

       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: []
responses:
  '400':
    description: >-
      Bad request: one or more parameters were incorrectly specified or are
      mutually exclusive.
    schema:
      $ref: '#/definitions/ODataErrorResponse'
  '401':
    description: >-
      Access denied due to invalid subscription key or invalid Microsoft Entra
      ID bearer token.  Make sure to provide a valid key for an active Azure
      subscription and Maps resource.  Otherwise, verify the
      [WWW-Authenticate](https://tools.ietf.org/html/rfc6750#section-3.1) header
      for error code and description of the provided Microsoft Entra ID bearer
      token.
    schema:
      $ref: '#/definitions/ODataErrorResponse'
    headers:
      WWW-Authenticate:
        type: string
        description: >-
          Bearer realm="https://atlas.microsoft.com/", error="invalid_token",
          error_description="The access token expired"
  '403':
    description: Permission, capacity, or authentication issues.
    schema:
      $ref: '#/definitions/ODataErrorResponse'
  '404':
    description: >-
      Not Found: the requested resource could not be found, but it may be
      available again in the future.
    schema:
      $ref: '#/definitions/ODataErrorResponse'
  '500':
    description: An error occurred while processing the request. Please try again later.
    schema:
      $ref: '#/definitions/ODataErrorResponse'
  200Async:
    description: >-
      The operation is running or complete.  If the operation was successful,
      use the Resource-Location header to obtain the path to the result.
    schema:
      $ref: '#/definitions/LongRunningOperationResult'
    headers:
      Resource-Location:
        type: string
        description: >-
          If successful, a URI where details on the newly created resource can
          be found.
  202Accepted:
    description: >-
      Request Accepted: The request has been accepted for processing. Please use
      the URL in the Operation-Location Header to obtain status.
    headers:
      Operation-Location:
        type: string
        description: >-
          New URL to check for the results of the [long-running
          operation](https://aka.ms/am-creator-lrt-v2).
parameters:
  GeographicResourceLocation:
    name: geography
    description: >-
      This parameter specifies where the Azure Maps Creator resource is
      located.  Valid values are us and eu.
    in: path
    required: true
    type: string
    default: us
    enum:
      - us
      - eu
    x-ms-enum:
      name: GeographicResourceLocation
      modelAsString: true
      values:
        - value: us
          description: Used to access an Azure Maps Creator resource in the United States
        - value: eu
          description: Used to access an Azure Maps Creator resource in Europe
    x-ms-parameter-location: client
  ClientId:
    name: x-ms-client-id
    description: >-
      Specifies which account is intended for usage in conjunction with the
      Microsoft Entra ID security model.  It represents a unique ID for the
      Azure Maps account and can be retrieved from the Azure Maps management  plane Account API. To use Microsoft Entra ID security in Azure Maps see
      the following [articles](https://aka.ms/amauthdetails) for guidance.
    type: string
    in: header
    required: false
    x-ms-parameter-location: client
  SubscriptionKey:
    name: subscription-key
    description: >-
      One of the Azure Maps keys provided from an Azure Map Account. Please
      refer to this
      [article](https://docs.microsoft.com/azure/azure-maps/how-to-manage-authentication)
      for details on how to manage authentication.
    type: string
    in: query
    required: false
    x-ms-parameter-location: client
  ApiVersion:
    name: api-version
    description: Version number of Azure Maps API. Current version is 2.0
    type: string
    in: query
    required: true
    default: '2.0'
    x-ms-parameter-location: client
  JsonFormat:
    name: format
    description: Desired format of the response. Only `json` format is supported.
    type: string
    in: path
    required: true
    enum:
      - json
    x-ms-enum:
      name: JsonFormat
      modelAsString: true
      values:
        - value: json
          description: >-
            [The JavaScript Object Notation Data Interchange
            Format](https://tools.ietf.org/html/rfc8259)
    x-ms-parameter-location: method
  DatasetIdQuery:
    name: datasetId
    description: >-
      The unique `datasetId` that the tileset create API uses to retrieve
      features to generate tiles. The `datasetId` must have been obtained from a
      successful [Dataset Create
      API](https://docs.microsoft.com/en-us/rest/api/maps/v2/dataset/create)
      call.
    type: string
    in: query
    required: true
    x-ms-parameter-location: client
  TilesetId:
    name: tilesetId
    description: The Tileset Id
    type: string
    in: path
    required: true
    x-ms-parameter-location: method
  DescriptionTileset:
    name: description
    description: User provided description of the tileset.
    type: string
    in: query
    required: false
    x-ms-parameter-location: method
  TilesetOperationId:
    name: operationId
    type: string
    in: path
    description: The ID to query the status for the tileset create/import request.
    required: true
    x-ms-parameter-location: method
paths:
  /tilesets:
    post:
      x-publish: true
      description: >-
        **Applies to:** see pricing
        [tiers](https://aka.ms/AzureMapsPricingTier).<br><br>Creator makes it
        possible to develop applications based on your private indoor map data
        using Azure Maps API and SDK.
        [This](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps)
        article introduces concepts and tools that apply to Azure Maps
        Creator.<br><br>
        [This](https://docs.microsoft.com/en-us/azure/azure-maps/creator-indoor-maps)
        article introduces concepts and tools that apply to Azure Maps
        Creator.<br><br>The Tileset Create API allows the caller to create a
        tileset from a dataset. A tileset contains a set of tiles that can be
        consumed <br>from the [Get Map Tile](/rest/api/maps/render/getmaptile)
        to retrieve custom tiles. To make a dataset, use the <br>[DataSet Create
        API](/rest/api/maps-creator/dataset/create).<br><br>## Submit Create
        Request<br><br>To create your tileset you will make a `POST` request
        with an empty body. The `datasetId` query parameter will be <br>used as
        the source of the tileset data.<br><br>The Create Tileset API is a
        <br>[long-running operation](https://aka.ms/am-creator-lrt-v2).
      operationId: microsoftAzureTilesetCreate
      x-ms-examples:
        Create Tileset by providing a Dataset Id:
          $ref: ./examples/Create.json
      parameters:
        - $ref: '#/parameters/ClientId'
        - $ref: '#/parameters/SubscriptionKey'
        - $ref: '#/parameters/ApiVersion'
        - $ref: '#/parameters/DatasetIdQuery'
        - $ref: '#/parameters/DescriptionTileset'
      responses:
        '202':
          $ref: '#/responses/202Accepted'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
      summary: Microsoft Azure Post Tilesets
      tags:
        - Tilesets
    get:
      x-publish: true
      description: >-
        **Applies to:** see pricing
        [tiers](https://aka.ms/AzureMapsPricingTier).<br><br>Creator makes it
        possible to develop applications based on your private indoor map data
        using Azure Maps API and SDK.
        [This](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps)
        article introduces concepts and tools that apply to Azure Maps
        Creator.<br><br>This API allows the caller to fetch a list of all
        tilesets created.   <br>
      operationId: microsoftAzureTilesetList
      x-ms-examples:
        Get a list of all tilesets:
          $ref: ./examples/List.json
      parameters:
        - $ref: '#/parameters/ClientId'
        - $ref: '#/parameters/SubscriptionKey'
        - $ref: '#/parameters/ApiVersion'
      responses:
        '200':
          description: >-
            List tileset request completed successfully. The response body
            contains a list of all tilesets.
          schema:
            $ref: '#/definitions/TilesetListResponse'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
      summary: Microsoft Azure Get Tilesets
      tags:
        - Tilesets
  /tilesets/{tilesetId}:
    get:
      x-publish: true
      description: >-
        **Applies to:** see pricing
        [tiers](https://aka.ms/AzureMapsPricingTier).<br><br>Creator makes it
        possible to develop applications based on your private indoor map data
        using Azure Maps API and SDK.
        [This](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps)
        article introduces concepts and tools that apply to Azure Maps
        Creator.<br><br>This API allows the caller to fetch a tileset.
      operationId: microsoftAzureTilesetGet
      x-ms-examples:
        Gets the details for a single tileset:
          $ref: ./examples/Get.json
      parameters:
        - $ref: '#/parameters/ClientId'
        - $ref: '#/parameters/SubscriptionKey'
        - $ref: '#/parameters/ApiVersion'
        - $ref: '#/parameters/TilesetId'
      responses:
        '200':
          description: >-
            List tileset request completed successfully. The response body
            contains a list of all tilesets.
          schema:
            $ref: '#/definitions/TilesetDetailInfo'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
      summary: Microsoft Azure Get Tilesets Tilesetid
      tags:
        - Tilesets
    delete:
      x-publish: true
      description: >-
        **Applies to:** see pricing
        [tiers](https://aka.ms/AzureMapsPricingTier).<br><br>Creator makes it
        possible to develop applications based on your private indoor map data
        using Azure Maps API and SDK.
        [This](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps)
        article introduces concepts and tools that apply to Azure Maps
        Creator.<br><br>This API allows the caller to delete a created
        tileset.    <br>You can use this API if a tileset is no longer needed.
        <br><br>### Submit Delete Request<br><br>To delete your content you will
        issue a `DELETE` request where the path will contain the `tilesetId` of
        the tileset to delete.    <br><br>#### Delete request
        "Successful"<br><br>The Tileset Delete API returns a HTTP `204 No
        Content` response with an empty body, if the tileset was deleted
        successfully.    <br><br>#### Delete request "Failed"<br><br>A HTTP `400
        Bad Request` error response will be returned if the tileset with the
        passed-in `tilesetId` is not found. <br><br>Here is a sample error
        response:<br><br><br><br>```json<br>{<br>  "error": {<br>      "code":
        "400 BadRequest",<br>      "message": "Bad request - Tileset Id:
        d85b5b27-5fc4-4599-8b50-47160e90f8ce does not exist."<br>  }<br>}<br>```
      operationId: microsoftAzureTilesetDelete
      x-ms-examples:
        Delete a created tileset:
          $ref: ./examples/Delete.json
      parameters:
        - $ref: '#/parameters/ClientId'
        - $ref: '#/parameters/SubscriptionKey'
        - $ref: '#/parameters/ApiVersion'
        - $ref: '#/parameters/TilesetId'
      responses:
        '204':
          description: Tileset delete request completed successfully.
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
      summary: Microsoft Azure Delete Tilesets Tilesetid
      tags:
        - Tilesets
  /tilesets/operations/{operationId}:
    get:
      description: >-
        This path will be obtained from a call to /tilesets/create.  While in
        progress, an http200 will be returned with no extra headers -  followed
        by an http200 with Resource-Location header once successfully completed.
      operationId: microsoftAzureTilesetGetoperation
      x-ms-examples:
        Get the status of an operation which is still running:
          $ref: ./examples/GetOperationStillRunning.json
        Get the status of an operation which has finished successfully:
          $ref: ./examples/GetOperation.json
      parameters:
        - $ref: '#/parameters/SubscriptionKey'
        - $ref: '#/parameters/ApiVersion'
        - $ref: '#/parameters/TilesetOperationId'
      responses:
        '200':
          $ref: '#/responses/200Async'
        '400':
          $ref: '#/responses/400'
      summary: Microsoft Azure Get Tilesets Operations Operationid
      tags:
        - Tilesets
definitions:
  ODataErrorResponse:
    type: object
    description: >-
      This response object is returned when an error occurs in the Azure Maps
      API.
    properties:
      error:
        $ref: '#/definitions/ODataError'
  ODataError:
    type: object
    description: This object is returned when an error occurs in the Azure Maps API.
    properties:
      code:
        type: string
        readOnly: true
        description: The ODataError code.
      message:
        type: string
        readOnly: true
        description: If available, a human-readable description of the error.
      details:
        type: array
        items:
          $ref: '#/definitions/ODataError'
      target:
        type: string
        readOnly: true
        description: If available, the target causing the error.
  LongRunningOperationResult:
    description: The response model for a Long-Running Operations API.
    type: object
    properties:
      operationId:
        description: The Id for this long-running operation.
        type: string
      status:
        description: The status state of the request.
        type: string
        enum:
          - NotStarted
          - Running
          - Failed
          - Succeeded
        x-ms-enum:
          name: type
          modelAsString: true
          values:
            - value: NotStarted
              description: The request has not started processing yet.
            - value: Running
              description: The request has started processing.
            - value: Failed
              description: The request has one or more failures.
            - value: Succeeded
              description: The request has successfully completed.
        readOnly: true
      created:
        description: The created timestamp.
        type: string
        readOnly: true
      error:
        $ref: '#/definitions/ODataError'
      warning:
        $ref: '#/definitions/ODataError'
  TilesetListResponse:
    description: >-
      The response model for the Tileset List API. Returns a list of all
      tilesets.
    type: object
    properties:
      tilesets:
        description: A list of all tilesets.
        type: array
        readOnly: true
        items:
          $ref: '#/definitions/TilesetDetailInfo'
      nextLink:
        description: If present, the location of the next page of data.
        type: string
        readOnly: true
  TilesetDetailInfo:
    description: Detail information for the data.
    type: object
    properties:
      tilesetId:
        description: The unique tileset id for the tileset.
        type: string
        readOnly: true
      ontology:
        description: >-
          The ontology of the source dataset. Please refer to this
          [article](https://docs.microsoft.com/en-us/azure/azure-maps/creator-facility-ontology)
          for more information about Azure Maps Creator ontologies.
        type: string
        readOnly: true
      datasetId:
        description: The unique dataset Id used to create the tileset.
        type: string
        readOnly: true
      description:
        description: >-
          The description the caller provided when creating the tileset. Maximum
          length 1024 characters.
        type: string
        readOnly: true
      minZoom:
        description: The lowest tile zoom level tile generated for the tileset.
        type: integer
        readOnly: true
      maxZoom:
        description: The highest tile zoom level tile generated for the tileset.
        type: integer
        readOnly: true
      bbox:
        description: >-
          Bounding box which all features of the tileset lay within. Projection
          used - EPSG:3857. Format : 'minLon, minLat, maxLon, maxLat'.
        type: array
        readOnly: true
        items:
          type: number
tags:
  - name: Tilesets